mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: update libpq's documentation for PQfn().

Browse Source 
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
This commit is contained in:
Tom Lane 2021-04-30 15:10:06 -04:00
parent ebc2ff076e
commit d25997f898
1 changed files with 23 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/src/sgml/libpq.sgml
View File

@ -5221,15 +5221,35 @@ typedef struct
<para> <para>
<function>PQfn</function> always returns a valid <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 checked before the result is used. The caller is responsible for
freeing the <structname>PGresult</structname> with freeing the <structname>PGresult</structname> with
<function>PQclear</function> when it is no longer needed. <function>PQclear</function> when it is no longer needed.
</para> </para>
<para> <para>
Note that it is not possible to handle null arguments, null results, To pass a NULL argument to the function, set
nor set-valued results when using this interface. 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> </para>
</sect1> </sect1>