diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/sources.sgml | 46 |
1 files changed, 30 insertions, 16 deletions
diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml index 32ca2201b85..283c3e03573 100644 --- a/doc/src/sgml/sources.sgml +++ b/doc/src/sgml/sources.sgml @@ -103,9 +103,9 @@ less -x4 message text. In addition there are optional elements, the most common of which is an error identifier code that follows the SQL spec's SQLSTATE conventions. - <function>ereport</function> itself is just a shell function, that exists + <function>ereport</function> itself is just a shell macro, that exists mainly for the syntactic convenience of making message generation - look like a function call in the C source code. The only parameter + look like a single function call in the C source code. The only parameter accepted directly by <function>ereport</function> is the severity level. The primary message text and any optional message elements are generated by calling auxiliary functions, such as <function>errmsg</function>, @@ -116,36 +116,50 @@ less -x4 A typical call to <function>ereport</function> might look like this: <programlisting> ereport(ERROR, - (errcode(ERRCODE_DIVISION_BY_ZERO), - errmsg("division by zero"))); + errcode(ERRCODE_DIVISION_BY_ZERO), + errmsg("division by zero")); </programlisting> This specifies error severity level <literal>ERROR</literal> (a run-of-the-mill error). The <function>errcode</function> call specifies the SQLSTATE error code using a macro defined in <filename>src/include/utils/errcodes.h</filename>. The - <function>errmsg</function> call provides the primary message text. Notice the - extra set of parentheses surrounding the auxiliary function calls — - these are annoying but syntactically necessary. + <function>errmsg</function> call provides the primary message text. + </para> + + <para> + You will also frequently see this older style, with an extra set of + parentheses surrounding the auxiliary function calls: +<programlisting> +ereport(ERROR, + (errcode(ERRCODE_DIVISION_BY_ZERO), + errmsg("division by zero"))); +</programlisting> + The extra parentheses were required + before <productname>PostgreSQL</productname> version 12, but are now + optional. </para> <para> Here is a more complex example: <programlisting> ereport(ERROR, - (errcode(ERRCODE_AMBIGUOUS_FUNCTION), - errmsg("function %s is not unique", - func_signature_string(funcname, nargs, - NIL, actual_arg_types)), - errhint("Unable to choose a best candidate function. " - "You might need to add explicit typecasts."))); + errcode(ERRCODE_AMBIGUOUS_FUNCTION), + errmsg("function %s is not unique", + func_signature_string(funcname, nargs, + NIL, actual_arg_types)), + errhint("Unable to choose a best candidate function. " + "You might need to add explicit typecasts.")); </programlisting> This illustrates the use of format codes to embed run-time values into a message text. Also, an optional <quote>hint</quote> message is provided. + The auxiliary function calls can be written in any order, but + conventionally <function>errcode</function> + and <function>errmsg</function> appear first. </para> <para> If the severity level is <literal>ERROR</literal> or higher, - <function>ereport</function> aborts the execution of the user-defined - function and does not return to the caller. If the severity level is + <function>ereport</function> aborts execution of the current query + and does not return to the caller. If the severity level is lower than <literal>ERROR</literal>, <function>ereport</function> returns normally. </para> @@ -390,7 +404,7 @@ elog(level, "format string", ...); </programlisting> is exactly equivalent to: <programlisting> -ereport(level, (errmsg_internal("format string", ...))); +ereport(level, errmsg_internal("format string", ...)); </programlisting> Notice that the SQLSTATE error code is always defaulted, and the message string is not subject to translation. |