<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.28 2001/05/08 02:26:09 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.29 2001/05/08 02:53:24 tgl Exp $
-->
<chapter id="plpgsql">
RAISE <replaceable class="parameter">level</replaceable> '<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">variable</replaceable> <optional>...</optional></optional>;
</synopsis>
- Inside the format, <literal>%</literal> is replaced by the next argument's
- external representation. Double <literal>%</literal>'s are output as <literal>%</literal>.
- Possible levels are DEBUG (silently suppressed in production
- running databases), NOTICE (written into the database log and forwarded to
- the client application) and EXCEPTION (written into the database log and
+ Possible levels are DEBUG (write the message into the postmaster log),
+ NOTICE (write the message into the postmaster log and forward it to
+ the client application) and EXCEPTION (raise an error,
aborting the transaction).
+ Inside the format string, <literal>%</literal> is replaced by the next
+ optional argument's external representation.
+ Write <literal>%%</literal> to emit a literal <literal>%</literal>.
+ Note that the optional arguments must presently
+ be simple variables, not expressions, and the format must be a simple
+ string literal.
</para>
+ <!--
+ This example should work, but does not:
+ RAISE NOTICE ''Id number '' || key || '' not found!'';
+ Put it back when we allow non-string-literal formats.
+ -->
+
<para>
<programlisting>
-RAISE NOTICE ''Id number '' || key || '' not found!'';
RAISE NOTICE ''Calling cs_create_job(%)'',v_job_id;
</programlisting>
- In this last example, v_job_id will replace the % in the
+ In this example, the value of v_job_id will replace the % in the
string.
</para>
<programlisting>
RAISE EXCEPTION ''Inexistent ID --> %'',user_id;
</programlisting>
- This will abort the transaction and write to the database log.
+ This will abort the transaction with the given error message.
</para>
</sect2>