begriffs open source - ai-pg/blob - full-docs/txt/plpgsql-structure.txt

   1
   2 41.2. Structure of PL/pgSQL #
   3
   4    Functions written in PL/pgSQL are defined to the server by executing
   5    CREATE FUNCTION commands. Such a command would normally look like, say,
   6 CREATE FUNCTION somefunc(integer, text) RETURNS integer
   7 AS 'function body text'
   8 LANGUAGE plpgsql;
   9
  10    The function body is simply a string literal so far as CREATE FUNCTION
  11    is concerned. It is often helpful to use dollar quoting (see
  12    Section 4.1.2.4) to write the function body, rather than the normal
  13    single quote syntax. Without dollar quoting, any single quotes or
  14    backslashes in the function body must be escaped by doubling them.
  15    Almost all the examples in this chapter use dollar-quoted literals for
  16    their function bodies.
  17
  18    PL/pgSQL is a block-structured language. The complete text of a
  19    function body must be a block. A block is defined as:
  20 [ <<label>> ]
  21 [ DECLARE
  22     declarations ]
  23 BEGIN
  24     statements
  25 END [ label ];
  26
  27    Each declaration and each statement within a block is terminated by a
  28    semicolon. A block that appears within another block must have a
  29    semicolon after END, as shown above; however the final END that
  30    concludes a function body does not require a semicolon.
  31
  32 Tip
  33
  34    A common mistake is to write a semicolon immediately after BEGIN. This
  35    is incorrect and will result in a syntax error.
  36
  37    A label is only needed if you want to identify the block for use in an
  38    EXIT statement, or to qualify the names of the variables declared in
  39    the block. If a label is given after END, it must match the label at
  40    the block's beginning.
  41
  42    All key words are case-insensitive. Identifiers are implicitly
  43    converted to lower case unless double-quoted, just as they are in
  44    ordinary SQL commands.
  45
  46    Comments work the same way in PL/pgSQL code as in ordinary SQL. A
  47    double dash (--) starts a comment that extends to the end of the line.
  48    A /* starts a block comment that extends to the matching occurrence of
  49    */. Block comments nest.
  50
  51    Any statement in the statement section of a block can be a subblock.
  52    Subblocks can be used for logical grouping or to localize variables to
  53    a small group of statements. Variables declared in a subblock mask any
  54    similarly-named variables of outer blocks for the duration of the
  55    subblock; but you can access the outer variables anyway if you qualify
  56    their names with their block's label. For example:
  57 CREATE FUNCTION somefunc() RETURNS integer AS $$
  58 << outerblock >>
  59 DECLARE
  60     quantity integer := 30;
  61 BEGIN
  62     RAISE NOTICE 'Quantity here is %', quantity;  -- Prints 30
  63     quantity := 50;
  64     --
  65     -- Create a subblock
  66     --
  67     DECLARE
  68         quantity integer := 80;
  69     BEGIN
  70         RAISE NOTICE 'Quantity here is %', quantity;  -- Prints 80
  71         RAISE NOTICE 'Outer quantity here is %', outerblock.quantity;  -- Prints
  72  50
  73     END;
  74
  75     RAISE NOTICE 'Quantity here is %', quantity;  -- Prints 50
  76
  77     RETURN quantity;
  78 END;
  79 $$ LANGUAGE plpgsql;
  80
  81 Note
  82
  83    There is actually a hidden “outer block” surrounding the body of any
  84    PL/pgSQL function. This block provides the declarations of the
  85    function's parameters (if any), as well as some special variables such
  86    as FOUND (see Section 41.5.5). The outer block is labeled with the
  87    function's name, meaning that parameters and special variables can be
  88    qualified with the function's name.
  89
  90    It is important not to confuse the use of BEGIN/END for grouping
  91    statements in PL/pgSQL with the similarly-named SQL commands for
  92    transaction control. PL/pgSQL's BEGIN/END are only for grouping; they
  93    do not start or end a transaction. See Section 41.8 for information on
  94    managing transactions in PL/pgSQL. Also, a block containing an
  95    EXCEPTION clause effectively forms a subtransaction that can be rolled
  96    back without affecting the outer transaction. For more about that see
  97    Section 41.6.8.