pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedAdd small detail to RAISE statement descripton
12+ messages / 4 participants
[nested] [flat]
* Add small detail to RAISE statement descripton
@ 2024-05-14 15:09 Igor Gnatyuk <ig953or@gmail.com>
2024-05-15 09:18 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
0 siblings, 1 reply; 12+ messages in thread
From: Igor Gnatyuk @ 2024-05-14 15:09 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
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
Attachments:
[text/x-patch] fix_doc_raise.patch (3.8K, ../../CAEu6iLvhF5sdGeat2x4_L0FvWW_SiN--ma8ya7CZd-oJoV+yqQ@mail.gmail.com/2-fix_doc_raise.patch)
download | inline diff:
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 6f880b705f..97bbf5244c 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>
***************
*** 3855,3861 **** RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
<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
--- 3855,3861 ----
<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
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Add small detail to RAISE statement descripton
2024-05-14 15:09 Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
@ 2024-05-15 09:18 ` jian he <jian.universality@gmail.com>
2024-05-17 08:39 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
0 siblings, 1 reply; 12+ messages in thread
From: jian he @ 2024-05-15 09:18 UTC (permalink / raw)
To: Igor Gnatyuk <ig953or@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On Tue, May 14, 2024 at 11:09 PM Igor Gnatyuk <ig953or@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.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Add small detail to RAISE statement descripton
2024-05-14 15:09 Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-15 09:18 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
@ 2024-05-17 08:39 ` Igor Gnatyuk <ig953or@gmail.com>
2024-05-19 08:43 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
0 siblings, 1 reply; 12+ messages in thread
From: Igor Gnatyuk @ 2024-05-17 08:39 UTC (permalink / raw)
To: jian he <jian.universality@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
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.universality@gmail.com>:
>
> On Tue, May 14, 2024 at 11:09 PM Igor Gnatyuk <ig953or@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.
Attachments:
[text/x-patch] fix_doc_raise_v2.patch (6.2K, ../../CAEu6iLuwjyhP8LMb5++V0NEdP_7-44xt=wS_bVuUJZXxjUXQdQ@mail.gmail.com/2-fix_doc_raise_v2.patch)
download | inline diff:
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 ----
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Add small detail to RAISE statement descripton
2024-05-14 15:09 Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-15 09:18 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-17 08:39 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
@ 2024-05-19 08:43 ` jian he <jian.universality@gmail.com>
2024-05-22 08:18 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
0 siblings, 1 reply; 12+ messages in thread
From: jian he @ 2024-05-19 08:43 UTC (permalink / raw)
To: Igor Gnatyuk <ig953or@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On Fri, May 17, 2024 at 4:39 PM Igor Gnatyuk <ig953or@gmail.com> wrote:
>
> 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
there occurrence of sqlcode:
+ <replaceable class="parameter">sqlcode</replaceable>
should be:
<replaceable class="parameter">sqlstate</replaceable>
+ <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>
>> options
>> <literal>USING</literal> clause can be used to supply a custom error message,
>> detail, or hint.
"options" should be "optional"?
I am not sure we need to explicitly say, "error message, error detail,
error hint"?
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Add small detail to RAISE statement descripton
2024-05-14 15:09 Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-15 09:18 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-17 08:39 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-19 08:43 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
@ 2024-05-22 08:18 ` Igor Gnatyuk <ig953or@gmail.com>
2024-05-22 11:13 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
0 siblings, 1 reply; 12+ messages in thread
From: Igor Gnatyuk @ 2024-05-22 08:18 UTC (permalink / raw)
To: jian he <jian.universality@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
Hi.
Thanks for the comments. I fixed my mistakes by specifying sqlcode
instead of sqlstate and changed the phrase
with an explicit listing of options in USING. In addition, I moved the
paragraph with it below.
Please check out the new patch version in the attachment.
Regards, Igor Gnatyuk
вс, 19 мая 2024 г. в 11:43, jian he <jian.universality@gmail.com>:
>
> On Fri, May 17, 2024 at 4:39 PM Igor Gnatyuk <ig953or@gmail.com> wrote:
> >
> > 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
>
> there occurrence of sqlcode:
> + <replaceable class="parameter">sqlcode</replaceable>
> should be:
> <replaceable class="parameter">sqlstate</replaceable>
>
>
> + <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>
>
> >> options
> >> <literal>USING</literal> clause can be used to supply a custom error message,
> >> detail, or hint.
>
> "options" should be "optional"?
> I am not sure we need to explicitly say, "error message, error detail,
> error hint"?
Attachments:
[text/x-patch] fix_doc_raise_v3.patch (5.8K, ../../CAEu6iLsL+Gw79f-8ZdU-GPnHXgSeEcPCk5qu9BcE1FRfO8Qbgg@mail.gmail.com/2-fix_doc_raise_v3.patch)
download | inline diff:
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
old mode 100644
new mode 100755
index 6f880b705f..eccba15cdc
*** 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">sqlstate</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:
***************
*** 3925,3939 **** RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
</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>
--- 3944,3954 ----
</para>
<para>
! In the <command>RAISE</command> command syntax with
! <replaceable class="parameter">condition_name</replaceable> or
! <replaceable class="parameter">sqlstate</replaceable> you can
! additionally use the <literal>USING</literal> clause too.
! A variation of the example above:
<programlisting>
RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
</programlisting>
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Add small detail to RAISE statement descripton
2024-05-14 15:09 Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-15 09:18 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-17 08:39 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-19 08:43 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-22 08:18 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
@ 2024-05-22 11:13 ` jian he <jian.universality@gmail.com>
2024-05-22 15:34 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
0 siblings, 1 reply; 12+ messages in thread
From: jian he @ 2024-05-22 11:13 UTC (permalink / raw)
To: Igor Gnatyuk <ig953or@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On Wed, May 22, 2024 at 4:18 PM Igor Gnatyuk <ig953or@gmail.com> wrote:
>
> Hi.
>
> Thanks for the comments. I fixed my mistakes by specifying sqlcode
> instead of sqlstate and changed the phrase
> with an explicit listing of options in USING. In addition, I moved the
> paragraph with it below.
> Please check out the new patch version in the attachment.
>
after git apply
jian@jian:~/Desktop/pg_src/src7/postgres$ git apply
$PATCHES/fix_doc_raise_v3.patch
jian@jian:~/Desktop/pg_src/src7/postgres$ git diff
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
old mode 100644
new mode 100755
-----------------
i guess, that means your patch (fix_doc_raise_v3) has some structural problem.
so I wrote it based on fix_doc_raise_v2.patch.
please check attached.
Feel free to change it.
Attachments:
[text/x-patch] v4-0001-fix-plpgsql-raise-command-doc-issue.patch (4.6K, ../../CACJufxEu+nCkQ6hLxwpFYNhCLJvCzFNOu=A5FhFc=+o5CUZJ2Q@mail.gmail.com/2-v4-0001-fix-plpgsql-raise-command-doc-issue.patch)
download | inline diff:
From 28f32f22095b262654ab204327678c7f027a5d36 Mon Sep 17 00:00:00 2001
From: jian he <jian.universality@gmail.com>
Date: Wed, 22 May 2024 19:07:26 +0800
Subject: [PATCH v4 1/1] fix plpgsql raise command doc issue.
1. fix plpgsql raise command synopsis.
2. explain <replaceable class="parameter">condition_name</replaceable>
and <replaceable class="parameter">sqlstate</replaceable>,
also add a example for it.
---
doc/src/sgml/plpgsql.sgml | 29 ++++++++++++++++++++++++-----
1 file changed, 24 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 6f880b70..e48e9d10 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -3805,10 +3805,10 @@ 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 <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,11 +3852,30 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
</programlisting>
</para>
+ <para>
+ The <replaceable class="parameter">condition_name</replaceable> and
+ <replaceable class="parameter">sqlstate</replaceable> specifies
+ error condition name and the five-character SQLSTATE error code respectively.
+ See <xref linkend="errcodes-appendix"/> for more information.
+ </para>
+
+ <para>
+ The examples 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> items. Each
+ 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:
--
2.34.1
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Add small detail to RAISE statement descripton
2024-05-14 15:09 Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-15 09:18 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-17 08:39 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-19 08:43 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-22 08:18 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-22 11:13 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
@ 2024-05-22 15:34 ` Igor Gnatyuk <ig953or@gmail.com>
2024-05-24 00:53 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-07-10 20:36 ` Re: Add small detail to RAISE statement descripton Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 2 replies; 12+ messages in thread
From: Igor Gnatyuk @ 2024-05-22 15:34 UTC (permalink / raw)
To: jian he <jian.universality@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
Hi,
thanks for the response and for your corrections to the patch.
But I checked my changes by running make html, make postgres-A4.pdf,
make postgres-US.pdf and viewing
the results: everything is OK.
Message
'old mode 100644
new mode 100755'
this means, imho, that access rights were changed during changes to
the file. I fixed it in the patch
fix_doc_raise_v3-bios.patch. Please check it out.
Thanks again for your comments.
ср, 22 мая 2024 г. в 14:13, jian he <jian.universality@gmail.com>:
>
> On Wed, May 22, 2024 at 4:18 PM Igor Gnatyuk <ig953or@gmail.com> wrote:
> >
> > Hi.
> >
> > Thanks for the comments. I fixed my mistakes by specifying sqlcode
> > instead of sqlstate and changed the phrase
> > with an explicit listing of options in USING. In addition, I moved the
> > paragraph with it below.
> > Please check out the new patch version in the attachment.
> >
>
> after git apply
>
> jian@jian:~/Desktop/pg_src/src7/postgres$ git apply
> $PATCHES/fix_doc_raise_v3.patch
> jian@jian:~/Desktop/pg_src/src7/postgres$ git diff
> diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
> old mode 100644
> new mode 100755
>
> -----------------
> i guess, that means your patch (fix_doc_raise_v3) has some structural problem.
>
> so I wrote it based on fix_doc_raise_v2.patch.
> please check attached.
>
>
> Feel free to change it.
Attachments:
[text/x-patch] fix_doc_raise_v3-bis.patch (5.7K, ../../CAEu6iLvde6Pe9pvacVD8Ni5oLFgSH2yE-cE+s=yM9b0byOb3TA@mail.gmail.com/2-fix_doc_raise_v3-bis.patch)
download | inline diff:
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 6f880b705f..eccba15cdc 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">sqlstate</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:
***************
*** 3925,3939 **** RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
</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>
--- 3944,3954 ----
</para>
<para>
! In the <command>RAISE</command> command syntax with
! <replaceable class="parameter">condition_name</replaceable> or
! <replaceable class="parameter">sqlstate</replaceable> you can
! additionally use the <literal>USING</literal> clause too.
! A variation of the example above:
<programlisting>
RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
</programlisting>
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Add small detail to RAISE statement descripton
2024-05-14 15:09 Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-15 09:18 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-17 08:39 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-19 08:43 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-22 08:18 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-22 11:13 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-22 15:34 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
@ 2024-05-24 00:53 ` jian he <jian.universality@gmail.com>
1 sibling, 0 replies; 12+ messages in thread
From: jian he @ 2024-05-24 00:53 UTC (permalink / raw)
To: Igor Gnatyuk <ig953or@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On Wed, May 22, 2024 at 11:35 PM Igor Gnatyuk <ig953or@gmail.com> wrote:
>
> Hi,
>
> thanks for the response and for your corrections to the patch.
> But I checked my changes by running make html, make postgres-A4.pdf,
> make postgres-US.pdf and viewing
> the results: everything is OK.
>
> Message
> 'old mode 100644
> new mode 100755'
> this means, imho, that access rights were changed during changes to
> the file. I fixed it in the patch
> fix_doc_raise_v3-bios.patch. Please check it out.
>
looks good to me.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Add small detail to RAISE statement descripton
2024-05-14 15:09 Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-15 09:18 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-17 08:39 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-19 08:43 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-22 08:18 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-22 11:13 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-22 15:34 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
@ 2024-07-10 20:36 ` Laurenz Albe <laurenz.albe@cybertec.at>
2024-07-15 18:30 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
1 sibling, 1 reply; 12+ messages in thread
From: Laurenz Albe @ 2024-07-10 20:36 UTC (permalink / raw)
To: Igor Gnatyuk <ig953or@gmail.com>; jian he <jian.universality@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On Wed, 2024-05-22 at 18:34 +0300, Igor Gnatyuk wrote:
> fix_doc_raise_v3-bios.patch. Please check it out.
I think the patch is fine.
> + <para>
> + <replaceable class="parameter">condition_name</replaceable> and
> + <replaceable class="parameter">sqlstate</replaceable> specify
> + error condition name and the five-character SQLSTATE code respectively.
> + See <xref linkend="errcodes-appendix"/> for more information.
> + </para>
There should be a comma before "respectively".
> 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
> + 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.
I think that is unnecessarily verbose. The original wording was fine;
everybody can see from the syntax diagram that you can also use :=
But I won't fight over it.
> + In the <command>RAISE</command> command syntax with
> + <replaceable class="parameter">condition_name</replaceable> or
> + <replaceable class="parameter">sqlstate</replaceable> you can
> + additionally use the <literal>USING</literal> clause too.
> + A variation of the example above:
I think that the final sentence should be more complete.
Suggestions:
Here is a variation of the above example:
A variation of the above example is:
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Add small detail to RAISE statement descripton
2024-05-14 15:09 Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-15 09:18 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-17 08:39 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-19 08:43 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-22 08:18 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-22 11:13 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-22 15:34 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-07-10 20:36 ` Re: Add small detail to RAISE statement descripton Laurenz Albe <laurenz.albe@cybertec.at>
@ 2024-07-15 18:30 ` Igor Gnatyuk <ig953or@gmail.com>
2024-07-16 01:18 ` Re: Add small detail to RAISE statement descripton Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 12+ messages in thread
From: Igor Gnatyuk @ 2024-07-15 18:30 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
Hi, thanks for the review.
I tried to take your comments into account:
- added a missing comma
- still left a verbose version ;)
- made the last sentence more complete (according to the 2nd option).
Attached you will find new patch version fix_doc_raise_v4.patch,
please check it out.
Thanks again for review and comments.
Regards, Igor Gnatyuk
ср, 10 июл. 2024 г. в 23:36, Laurenz Albe <laurenz.albe@cybertec.at>:
>
> On Wed, 2024-05-22 at 18:34 +0300, Igor Gnatyuk wrote:
> > fix_doc_raise_v3-bios.patch. Please check it out.
>
> I think the patch is fine.
>
> > + <para>
> > + <replaceable class="parameter">condition_name</replaceable> and
> > + <replaceable class="parameter">sqlstate</replaceable> specify
> > + error condition name and the five-character SQLSTATE code respectively.
> > + See <xref linkend="errcodes-appendix"/> for more information.
> > + </para>
>
> There should be a comma before "respectively".
>
> > 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
> > + 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.
>
> I think that is unnecessarily verbose. The original wording was fine;
> everybody can see from the syntax diagram that you can also use :=
>
> But I won't fight over it.
>
> > + In the <command>RAISE</command> command syntax with
> > + <replaceable class="parameter">condition_name</replaceable> or
> > + <replaceable class="parameter">sqlstate</replaceable> you can
> > + additionally use the <literal>USING</literal> clause too.
> > + A variation of the example above:
>
> I think that the final sentence should be more complete.
> Suggestions:
>
> Here is a variation of the above example:
>
> A variation of the above example is:
>
> Yours,
> Laurenz Albe
Attachments:
[text/x-patch] fix_doc_raise_v4.patch (5.7K, ../../CAEu6iLuoJe1xLzazw6nwrCk4VDKCwOaBL1R0XtzkWq+TBjAL_Q@mail.gmail.com/2-fix_doc_raise_v4.patch)
download | inline diff:
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 6f880b705f..df316e5757 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">sqlstate</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:
***************
*** 3925,3939 **** RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
</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>
--- 3944,3954 ----
</para>
<para>
! In the <command>RAISE</command> command syntax with
! <replaceable class="parameter">condition_name</replaceable> or
! <replaceable class="parameter">sqlstate</replaceable> you can
! additionally use the <literal>USING</literal> clause too.
! A variation of the above example is:
<programlisting>
RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
</programlisting>
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Add small detail to RAISE statement descripton
2024-05-14 15:09 Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-15 09:18 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-17 08:39 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-19 08:43 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-22 08:18 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-22 11:13 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-22 15:34 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-07-10 20:36 ` Re: Add small detail to RAISE statement descripton Laurenz Albe <laurenz.albe@cybertec.at>
2024-07-15 18:30 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
@ 2024-07-16 01:18 ` Laurenz Albe <laurenz.albe@cybertec.at>
2024-07-18 16:40 ` Re: Add small detail to RAISE statement descripton Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 12+ messages in thread
From: Laurenz Albe @ 2024-07-16 01:18 UTC (permalink / raw)
To: Igor Gnatyuk <ig953or@gmail.com>; +Cc: jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
On Mon, 2024-07-15 at 21:30 +0300, Igor Gnatyuk wrote:
> I tried to take your comments into account:
>
> - added a missing comma
> - still left a verbose version ;)
> - made the last sentence more complete (according to the 2nd option).
>
> Attached you will find new patch version fix_doc_raise_v4.patch,
> please check it out.
Thanks. I have marked the patch as "ready for committer".
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Add small detail to RAISE statement descripton
2024-05-14 15:09 Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-15 09:18 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-17 08:39 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-19 08:43 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-22 08:18 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-22 11:13 ` Re: Add small detail to RAISE statement descripton jian he <jian.universality@gmail.com>
2024-05-22 15:34 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-07-10 20:36 ` Re: Add small detail to RAISE statement descripton Laurenz Albe <laurenz.albe@cybertec.at>
2024-07-15 18:30 ` Re: Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-07-16 01:18 ` Re: Add small detail to RAISE statement descripton Laurenz Albe <laurenz.albe@cybertec.at>
@ 2024-07-18 16:40 ` Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 12+ messages in thread
From: Tom Lane @ 2024-07-18 16:40 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Igor Gnatyuk <ig953or@gmail.com>; jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
Laurenz Albe <laurenz.albe@cybertec.at> writes:
> On Mon, 2024-07-15 at 21:30 +0300, Igor Gnatyuk wrote:
>> Attached you will find new patch version fix_doc_raise_v4.patch,
>> please check it out.
> Thanks. I have marked the patch as "ready for committer".
I fooled with the wording a bit more and pushed it.
Thanks for the submission!
regards, tom lane
^ permalink raw reply [nested|flat] 12+ messages in thread
end of thread, other threads:[~2024-07-18 16:40 UTC | newest]
Thread overview: 12+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2024-05-14 15:09 Add small detail to RAISE statement descripton Igor Gnatyuk <ig953or@gmail.com>
2024-05-15 09:18 ` jian he <jian.universality@gmail.com>
2024-05-17 08:39 ` Igor Gnatyuk <ig953or@gmail.com>
2024-05-19 08:43 ` jian he <jian.universality@gmail.com>
2024-05-22 08:18 ` Igor Gnatyuk <ig953or@gmail.com>
2024-05-22 11:13 ` jian he <jian.universality@gmail.com>
2024-05-22 15:34 ` Igor Gnatyuk <ig953or@gmail.com>
2024-05-24 00:53 ` jian he <jian.universality@gmail.com>
2024-07-10 20:36 ` Laurenz Albe <laurenz.albe@cybertec.at>
2024-07-15 18:30 ` Igor Gnatyuk <ig953or@gmail.com>
2024-07-16 01:18 ` Laurenz Albe <laurenz.albe@cybertec.at>
2024-07-18 16:40 ` Tom Lane <tgl@sss.pgh.pa.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox