linkend="plpgsql-statements-executing-dyn">. This chart may be useful
- as a summary of the needed numbers of quote marks in
+ as a summary of the needed numbers of quotation marks in
various situations.
- 1 quote mark
+ 1 quotation mark
To begin and end the function body, for example:
CREATE FUNCTION foo() RETURNS integer AS '...'
LANGUAGE plpgsql;
- Anywhere within the function body, quote marks must
+ Anywhere within the function body, quotation marks must
appear in pairs.
- 2 quote marks
+ 2 quotation marks
For string literals inside the function body, for example:
- 4 quote marks
+ 4 quotation marks
- When you need a single quote in a string constant inside the function
+ When you need a single quotation mark in a string constant inside the function
body, for example:
a_output := a_output || '' AND name LIKE ''''foobar'''' AND xyz''
- 6 quote marks
+ 6 quotation marks
- When a single quote in a string inside the function body is
+ When a single quotation mark in a string inside the function body is
adjacent to the end of that string constant, for example:
a_output := a_output || '' AND name LIKE ''''foobar''''''
- 10 quote marks
+ 10 quotation marks
- When you want two single quotes in a string constant (which
- accounts for 8 quotes) and this is adjacent to the end of that
+ When you want two single quotation marks in a string constant (which
+ accounts for 8 quotation marks) and this is adjacent to the end of that
string constant (2 more). You will probably only need that if
you are writing a function that generates other functions. For
example:
- A different approach is to escape quote marks in the function body
+ A different approach is to escape quotation marks in the function body
with a backslash rather than by doubling them. With this method
you'll find yourself writing things like \'\' instead
of ''''. Some find this easier to keep track of, some
linkend="extend-types-polymorphic">).
This allows the function to access its actual return type
as shown in .
- $0 is initialized to NULL and can be modified by
+ $0 is initialized to null and can be modified by
the function, so it can be used to hold the return value if desired,
though that is not required. $0 can also be
given an alias. For example, this function works on any data type
-
-
Record Types
+
+
Record Types
name RECORD;
-
Record variables are similar to row-type variables, but they have no
-
-
<literal>RENAME</>
+
+
<literal>RENAME</>
RENAME oldname TO newname;
- Using the RENAME declaration you can change the name of a variable,
- record or row. This is primarily useful if NEW or OLD should be
- referenced by another name inside a trigger procedure. See also ALIAS.
-
+ Using the RENAME declaration you can change the
+ name of a variable, record or row. This is primarily useful if
+ NEW or OLD should be
+ referenced by another name inside a trigger procedure. See also
+ ALIAS.
+
- Examples:
+ Examples:
RENAME id TO user_id;
RENAME this_var TO that_var;
-
+
- RENAME appears to be broken as of
PostgreSQL- 7.3. Fixing this is of low priority, since ALIAS covers most of
- the practical uses of RENAME.
-
+ RENAME appears to be broken as of
+
PostgreSQL 7.3. Fixing this is of low priority,+ since ALIAS covers most of the practical uses
+ of RENAME.
+
-
-
+
Obtaining the Result Status
- There are several ways to determine the effect of a command. The
- first method is to use the GET DIAGNOSTICS
- command, which has the form:
+ There are several ways to determine the effect of a command. The
+ first method is to use the GET DIAGNOSTICS
+ command, which has the form:
GET DIAGNOSTICS variable = item , ... ;
type boolean. FOUND starts out
false within each
PL/pgSQL function call.
It is set by each of the following types of statements:
-
-
- A SELECT INTO statement sets
- FOUND true if it returns a row, false if no
- row is returned.
-
-
-
- A PERFORM statement sets FOUND
- true if it produces (and discards) a row, false if no row is
- produced.
-
-
-
- UPDATE, INSERT, and DELETE
- statements set FOUND true if at least one
- row is affected, false if no row is affected.
-
-
-
- A FETCH statement sets FOUND
- true if it returns a row, false if no row is returned.
-
-
-
- A FOR statement sets FOUND true
- if it iterates one or more times, else false. This applies to
- all three variants of the FOR statement (integer
- FOR loops, record-set FOR loops, and
- dynamic record-set FOR
- loops). FOUND is only set when the
- FOR loop exits: inside the execution of the loop,
- FOUND is not modified by the
- FOR statement, although it may be changed by the
- execution of other statements within the loop body.
-
-
-
+
+
+ A SELECT INTO statement sets
+ FOUND true if it returns a row, false if no
+ row is returned.
+
+
+
+ A PERFORM statement sets FOUND
+ true if it produces (and discards) a row, false if no row is
+ produced.
+
+
+
+ UPDATE, INSERT, and DELETE
+ statements set FOUND true if at least one
+ row is affected, false if no row is affected.
+
+
+
+ A FETCH statement sets FOUND
+ true if it returns a row, false if no row is returned.
+
+
+
+ A FOR statement sets FOUND true
+ if it iterates one or more times, else false. This applies to
+ all three variants of the FOR statement (integer
+ FOR loops, record-set FOR loops, and
+ dynamic record-set FOR
+ loops). FOUND is only set when the
+ FOR loop exits: inside the execution of the loop,
+ FOUND is not modified by the
+ FOR statement, although it may be changed by the
+ execution of other statements within the loop body.
+
+
+
FOUND is a local variable; any changes
to it affect only the current
PL/pgSQL function.
If WHEN is present, loop exit occurs only if the specified condition
- is true, otherwise control passes to the statement after EXIT.
+ is true, otherwise control passes to the statement after EXIT.
The WHILE statement repeats a
sequence of statements so long as the condition expression
- evaluates to true. The condition is checked just before
- each entry to the loop body.
+ evaluates to true. The condition is checked just before
+ each entry to the loop body.
This form of FOR creates a loop that iterates over a range of integer
- values. The variable
+ values. The variable
name is automatically defined as type
integer and exists only inside the loop. The two expressions giving
the lower and upper bound of the range are evaluated once when entering
the loop. The iteration step is normally 1, but is -1 when REVERSE is
- specified.
+ specified.
If the lower bound is greater than the upper bound (or less than,
- in the REVERSE case), the loop body is not
+ in the REVERSE case), the loop body is not
executed at all. No error is raised.
The cursor variable is opened and given the specified query to
- execute. The cursor cannot be open already, and it must have been
- declared as an unbound cursor (that is, as a simple
- refcursor variable). The SELECT query
- is treated in the same way as other SELECT
- statements in
PL/pgSQL: PL/pgSQL- variable names are substituted, and the query plan is cached for
- possible reuse.
+ execute. The cursor cannot be open already, and it must have been
+ declared as an unbound cursor (that is, as a simple
+ refcursor variable). The SELECT query
+ is treated in the same way as other SELECT
+
statements in
PL/pgSQL: PL/pgSQL+ variable names are substituted, and the query plan is cached for
+ possible reuse.
OPEN unbound-cursor FOR EXECUTE query-string;
- The cursor variable is opened and given the specified query to
- execute. The cursor cannot be open already, and it must have been
- declared as an unbound cursor (that is, as a simple
- refcursor variable). The query is specified as a string
- expression in the same way as in the EXECUTE
- command. As usual, this gives flexibility so the query can vary
- from one run to the next.
+ The cursor variable is opened and given the specified query to
+ execute. The cursor cannot be open already, and it must have been
+ declared as an unbound cursor (that is, as a simple
+ refcursor variable). The query is specified as a string
+ expression in the same way as in the EXECUTE
+ command. As usual, this gives flexibility so the query can vary
+ from one run to the next.
OPEN bound-cursor ( argument_values ) ;
- This form of OPEN is used to open a cursor
- variable whose query was bound to it when it was declared. The
- cursor cannot be open already. A list of actual argument value
- expressions must appear if and only if the cursor was declared to
- take arguments. These values will be substituted in the query.
- The query plan for a bound cursor is always considered cacheable;
- there is no equivalent of EXECUTE in this case.
+ This form of OPEN is used to open a cursor
+ variable whose query was bound to it when it was declared. The
+ cursor cannot be open already. A list of actual argument value
+ expressions must appear if and only if the cursor was declared to
+ take arguments. These values will be substituted in the query.
+ The query plan for a bound cursor is always considered cacheable;
+ there is no equivalent of EXECUTE in this case.
FETCH cursor INTO target;
- FETCH retrieves the next row from the
- cursor into a target, which may be a row variable, a record
- variable, or a comma-separated list of simple variables, just like
- SELECT INTO. As with SELECT
- INTO, the special variable FOUND may
- be checked to see whether a row was obtained or not.
+ FETCH retrieves the next row from the
+ cursor into a target, which may be a row variable, a record
+ variable, or a comma-separated list of simple variables, just like
+ SELECT INTO. As with SELECT
+ INTO, the special variable FOUND may
+ be checked to see whether a row was obtained or not.
CLOSE closes the portal underlying an open
- cursor. This can be used to release resources earlier than end of
- transaction, or to free up the cursor variable to be opened again.
+ cursor. This can be used to release resources earlier than end of
+ transaction, or to free up the cursor variable to be opened again.
PL/pgSQL functions can return cursors to the
caller. This is useful to return multiple rows or columns,
- especially with very large result sets. To do this, the function
- opens the cursor and returns the cursor name to the caller (or simply
- opens the cursor using a portal name specified by or otherwise known
- to the caller). The caller can then fetch rows from the cursor. The
- cursor can be closed by the caller, or it will be closed automatically
+ especially with very large result sets. To do this, the function
+ opens the cursor and returns the cursor name to the caller (or simply
+ opens the cursor using a portal name specified by or otherwise known
+ to the caller). The caller can then fetch rows from the cursor. The
+ cursor can be closed by the caller, or it will be closed automatically
when the transaction closes.
The portal name used for a cursor can be specified by the
- programmer or automatically generated. To specify a portal name,
- simply assign a string to the refcursor variable before
- opening it. The string value of the refcursor variable
- will be used by OPEN as the name of the underlying portal.
- However, if the refcursor variable is NULL,
- OPEN automatically generates a name that does not
- conflict with any existing portal, and assigns it to the
- refcursor variable.
+ programmer or automatically generated. To specify a portal name,
+ simply assign a string to the refcursor variable before
+ opening it. The string value of the refcursor variable
+ will be used by OPEN as the name of the underlying portal.
+ However, if the refcursor variable is null,
+ OPEN automatically generates a name that does not
+ conflict with any existing portal, and assigns it to the
+ refcursor variable.
- A bound cursor variable is initialized to the string value
- representing its name, so that the portal name is the same as
- the cursor variable name, unless the programmer overrides it
- by assignment before opening the cursor. But an unbound cursor
- variable defaults to an initial value of NULL, so it will receive
- an automatically-generated unique name, unless overridden.
+ A bound cursor variable is initialized to the string value
+ representing its name, so that the portal name is the same as
+ the cursor variable name, unless the programmer overrides it
+ by assignment before opening the cursor. But an unbound cursor
+ variable defaults to the null value initially , so it will receive
+ an automatically-generated unique name, unless overridden.
The following example shows one way a cursor name can be supplied by
- the caller:
+ the caller:
CREATE TABLE test (col text);
-
PL/pgSQL can be used to define trigger
- procedures. A trigger procedure is created with the
- CREATE FUNCTION command, declaring it as a function with
- no arguments and a return type of trigger. Note that
- the function must be declared with no arguments even if it expects
- to receive arguments specified in CREATE TRIGGER ---
- trigger arguments are passed via TG_ARGV, as described
- below.
+
PL/pgSQL can be used to define trigger
+ procedures. A trigger procedure is created with the
+ CREATE FUNCTION command, declaring it as a function with
+ no arguments and a return type of trigger. Note that
+ the function must be declared with no arguments even if it expects
+ to receive arguments specified in CREATE TRIGGER ---
+ trigger arguments are passed via TG_ARGV, as described
+ below.
projects / postgresql.git / commitdiff