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 <jian.universal...@gmail.com>: > > On Tue, May 14, 2024 at 11:09 PM Igor Gnatyuk <ig95...@gmail.com> 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 ----