From d25997f898dd8c36fc7acad3f22366f18b548200 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 30 Apr 2021 15:10:06 -0400 Subject: [PATCH] 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 238ceb04a41..fa7332a9039 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -5221,15 +5221,35 @@ typedef struct PQfn always returns a valid - PGresult pointer. The result status should be + PGresult pointer, with + status PGRES_COMMAND_OK for success + or PGRES_FATAL_ERROR if some problem was encountered. + The result status should be checked before the result is used. The caller is responsible for freeing the PGresult with PQclear when it is no longer needed. - 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 len field of that parameter structure + to -1; the isint + and u fields are then irrelevant. + (But this works only in protocol 3.0 and later connections.) + + + + If the function returns NULL, *result_len is set + to -1, and *result_buf is not + modified. (This works only in protocol 3.0 and later connections; in + protocol 2.0, neither *result_len + nor *result_buf are modified.) + + + + 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.