Hi.
Thank you for your letter. I tried to take your comments into account:
I added explanations to the condition_name, sqlstate options and
slightly changed
the explanations for USING. Attached you will find new patch version.
Thank you for your help.
Ragards, Igor Gnatyuk
ср, 15 мая 2024 г. в 12:18, jian he <[email protected]>:
>
> On Tue, May 14, 2024 at 11:09 PM Igor Gnatyuk <[email protected]> wrote:
> >
> > Hi,
> >
> > There is a slight syntax inaccuracy in the description of the RAISE
> > statement - assignments of parameter values in USING.
> > (Chapter 43. PL/pgSQL — SQL Procedural Language / 43.9 Errors and
> > Messages / 43.9.1 Reporting Errors and Messages):
> >
> > "...You can attach additional information to the error report by
> > writing USING followed by option = expression items..."
> > It should, apparently, be like this: "...option { = | := } expression..."
> >
> > The patch corrects this little omission. Attached: fix_doc_raise.patch
> >
> > Regards, Igor Gnatyuk
>
>
> while at it,
> I found out there is no brief explanation of:
> <replaceable class="parameter">condition_name</replaceable>
> and
> <replaceable class="parameter">sqlstate</replaceable>
> should we add it?
>
> one more minor thing.
>
> You can attach additional information to the error report by writing
> <literal>USING</literal> followed by <replaceable
> class="parameter">option</replaceable> { = | := } <replaceable
> class="parameter">expression</replaceable> items. Each
>
> we are not in <synopsis>, maybe
>
> You can attach additional information to the error report by writing
> <literal>USING</literal> followed by <replaceable
> class="parameter">option</replaceable> = <replaceable
> class="parameter">expression</replaceable> or
> <replaceable class="parameter">option</replaceable> :=
> <replaceable class="parameter">expression</replaceable>
> items
>
> will make it more clear.
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 6f880b705f..4375c9aa5a 100644
*** a/doc/src/sgml/plpgsql.sgml
--- b/doc/src/sgml/plpgsql.sgml
***************
*** 3805,3814 **** CALL transaction_test2();
raise errors.
<synopsis>
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> '<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">expression</replaceable> <optional>, ... </optional></optional> <optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> <replaceable class="parameter">condition_name</replaceable> <optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> SQLSTATE '<replaceable class="parameter">sqlstate</replaceable>' <optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional>;
RAISE ;
</synopsis>
--- 3805,3814 ----
raise errors.
<synopsis>
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> '<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">expression</replaceable> <optional>, ... </optional></optional> <optional> USING <replaceable class="parameter">option</replaceable> { = | := } <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> <replaceable class="parameter">condition_name</replaceable> <optional> USING <replaceable class="parameter">option</replaceable> { = | := } <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> SQLSTATE '<replaceable class="parameter">sqlstate</replaceable>' <optional> USING <replaceable class="parameter">option</replaceable> { = | := } <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
! RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> USING <replaceable class="parameter">option</replaceable> { = | := } <replaceable class="parameter">expression</replaceable> <optional>, ... </optional>;
RAISE ;
</synopsis>
***************
*** 3852,3862 **** RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
</programlisting>
</para>
<para>
You can attach additional information to the error report by writing
<literal>USING</literal> followed by <replaceable
class="parameter">option</replaceable> = <replaceable
! class="parameter">expression</replaceable> items. Each
<replaceable class="parameter">expression</replaceable> can be any
string-valued expression. The allowed <replaceable
class="parameter">option</replaceable> key words are:
--- 3852,3881 ----
</programlisting>
</para>
+ <para>
+ <replaceable class="parameter">condition_name</replaceable> and
+ <replaceable class="parameter">sqlcode</replaceable> specify
+ error condition name and the five-character SQLSTATE code respectively.
+ See <xref linkend="errcodes-appendix"/> for more information.
+ </para>
+
+ <para>
+ The example below shows <replaceable class="parameter">condition_name</replaceable>
+ and <replaceable class="parameter">sqlstate</replaceable> options usage:
+ <programlisting>
+ RAISE division_by_zero;
+ RAISE SQLSTATE '22012';
+ </programlisting>
+ </para>
+
<para>
You can attach additional information to the error report by writing
<literal>USING</literal> followed by <replaceable
class="parameter">option</replaceable> = <replaceable
! class="parameter">expression</replaceable> or
! <replaceable class="parameter">option</replaceable> :=
! <replaceable class="parameter">expression</replaceable>
! items, where
<replaceable class="parameter">expression</replaceable> can be any
string-valued expression. The allowed <replaceable
class="parameter">option</replaceable> key words are:
***************
*** 3907,3912 **** RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
--- 3926,3942 ----
</variablelist>
</para>
+ <para>
+ In the syntax of <command>RAISE</command> command with the
+ <replaceable class="parameter">condition_name</replaceable> or
+ <replaceable class="parameter">sqlcode</replaceable> options
+ <literal>USING</literal> clause can be used to supply a custom error message,
+ detail, or hint. A variation of the example above:
+ <programlisting>
+ RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
+ </programlisting>
+ </para>
+
<para>
This example will abort the transaction with the given error message
and hint:
***************
*** 3924,3944 **** RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
</programlisting>
</para>
- <para>
- There is a second <command>RAISE</command> syntax in which the main argument
- is the condition name or SQLSTATE to be reported, for example:
- <programlisting>
- RAISE division_by_zero;
- RAISE SQLSTATE '22012';
- </programlisting>
- In this syntax, <literal>USING</literal> can be used to supply a custom
- error message, detail, or hint. Another way to do the earlier
- example is
- <programlisting>
- RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
- </programlisting>
- </para>
-
<para>
Still another variant is to write <literal>RAISE USING</literal> or <literal>RAISE
<replaceable class="parameter">level</replaceable> USING</literal> and put
--- 3954,3959 ----
