function.
    </para>

   </sect2>

   <sect2 id="plpgsql-statements-null">
    <title>Doing Nothing At All</title>

    <para>
     Sometimes a placeholder statement that does nothing is useful.
     For example, it can indicate that one arm of an if/then/else
     chain is deliberately empty.  For this purpose, use the
     <command>NULL</command> statement:

<synopsis>
NULL;
</synopsis>
    </para>

    <para>
     For example, the following two fragments of code are equivalent:
<programlisting>
BEGIN
    y := x / 0;
EXCEPTION
    WHEN division_by_zero THEN
        NULL;  -- ignore the error
END;
</programlisting>

<programlisting>
BEGIN
    y := x / 0;
EXCEPTION
    WHEN division_by_zero THEN  -- ignore the error
END;
</programlisting>
     Which is preferable is a matter of taste.
    </para>

    <note>
     <para>
      In Oracle's PL/SQL, empty statement lists are not allowed, and so
      <command>NULL</command> statements are <emphasis>required</emphasis> for situations
      such as this.  <application>PL/pgSQL</application> allows you to
      just write nothing, instead.
     </para>
    </note>

   </sect2>
  </sect1>

  <sect1 id="plpgsql-control-structures">
   <title>Control Structures</title>

   <para>
    Control structures are probably the most useful (and
    important) part of <application>PL/pgSQL</application>. With
    <application>PL/pgSQL</application>'s control structures,
    you can manipulate <productname>PostgreSQL</productname> data in a very
    flexible and powerful way.
   </para>

   <sect2 id="plpgsql-statements-returning">
    <title>Returning from a Function</title>

    <para>
     There are two commands available that allow you to return data
     from a function: <command>RETURN</command> and <command>RETURN
     NEXT</command>.
    </para>

    <sect3 id="plpgsql-statements-returning-return">
     <title><command>RETURN</command></title>

<synopsis>
RETURN <replaceable>expression</replaceable>;
</synopsis>

     <para>
      <command>RETURN</command> with an expression terminates the
      function and returns the value of
      <replaceable>expression</replaceable> to the caller.  This form
      is used for <application>PL/pgSQL</application> functions that do
      not return a set.
     </para>

     <para>
      In a function that returns a scalar type, the expression's result will
      automatically be cast into the function's return type as described for
      assignments.  But to return a composite (row) value, you must write an
      expression delivering exactly the requested column set.  This may
      require use of explicit casting.
     </para>

     <para>
      If you declared the function with output parameters, write just
      <command>RETURN</command> with no expression.  The current values
      of the output parameter variables will be returned.
     </para>

     <para>
      If you declared the function to return <type>void</type>, a
      <command>RETURN</command> statement can be used to exit the function
      early; but do not write an expression following
      <command>RETURN</command>.
     </para>

     <para>
      The return value of a function cannot be left undefined. If
      control reaches the end of the top-level block of the function
      without hitting a <command>RETURN</command> statement, a run-time
      error will occur.  This restriction does not apply to functions
      with output parameters and functions returning <type>void</type>,
      however.  In those cases a <command>RETURN</command> statement is
      automatically executed if the top-level block finishes.
     </para>

     <para>
      Some examples:

<programlisting>
-- functions returning a scalar type
RETURN 1 + 2;
RETURN scalar_var;

-- functions returning a composite type
RETURN composite_type_var;
RETURN (1, 2, 'three'::text);  -- must cast columns to correct types
</programlisting>
     </para>
    </sect3>

    <sect3 id="plpgsql-statements-returning-return-next">