postgres.git / summary / log / commit / refs
commit 8e9b7c63877094bee343283d00b4e29bd9bb4ffa
Author: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri Apr 30 19:10:06 2021 +0000
First released in: 14.0, 9.6.22, 10.17, 11.12, 12.7, 13.3
Doc: update libpq's documentation for PQfn().
Mention specifically that you can't call aggregates, window functions,
or procedures this way (the inability to call SRFs was already
mentioned).
Also, the claim that PQfn doesn't support NULL arguments or results
has been a lie since we invented protocol 3.0. Not sure why this
text was never updated for that, but do it now.
Discussion: https://postgr.es/m/2039442.1615317309@sss.pgh.pa.us
doc/src/sgml/libpq.sgml | 26 +++++++++++++++++++++++---
1 file changed, 23 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 7e9fbe72425..0156bd0f0ce 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -5341,15 +5341,35 @@ typedef struct
<para>
<function>PQfn</function> always returns a valid
- <structname>PGresult</structname> pointer. The result status should be
+ <structname>PGresult</structname> pointer, with
+ status <literal>PGRES_COMMAND_OK</literal> for success
+ or <literal>PGRES_FATAL_ERROR</literal> if some problem was encountered.
+ The result status should be
checked before the result is used. The caller is responsible for
freeing the <structname>PGresult</structname> with
<function>PQclear</function> when it is no longer needed.
</para>
<para>
- Note that it is not possible to handle null arguments, null results,
- nor set-valued results when using this interface.
+ To pass a NULL argument to the function, set
+ the <parameter>len</parameter> field of that parameter structure
+ to <literal>-1</literal>; the <parameter>isint</parameter>
+ and <parameter>u</parameter> fields are then irrelevant.
+ (But this works only in protocol 3.0 and later connections.)
+ </para>
+
+ <para>
+ If the function returns NULL, <parameter>*result_len</parameter> is set
+ to <literal>-1</literal>, and <parameter>*result_buf</parameter> is not
+ modified. (This works only in protocol 3.0 and later connections; in
+ protocol 2.0, neither <parameter>*result_len</parameter>
+ nor <parameter>*result_buf</parameter> are modified.)
+ </para>
+
+ <para>
+ Note that it is not possible to handle set-valued results when using
+ this interface. Also, the function must be a plain function, not an
+ aggregate, window function, or procedure.
</para>
</sect1>
[parent: 89768ee696bf]