PQparamExec(3)

💖 PQparamExec — bestie edition 💖

okay so this is PQparamExec(3) from the libpqtypes Manual, and it's literally about running your parameterized queries with the params you already stuffed into a PGparam. two functions, one vibe. let's go 🦋

---

✨ NAME ✨

PQparamExec, PQparamExecPrepared — executes a paramertized query using the parameters in a PGparam. 💅

yes bestie the word is spelled "paramertized" up there, we don't gatekeep, we just report 📋

---

🌸 SYNOPSIS 🌸

#include <libpqtypes.h>

PGresult *PQparamExec(PGconn *conn, PGparam *param,
                      const char *command, int resultFormat);
PGresult *PQparamExecPrepared(PGconn *conn, PGparam *param,
                              const char *stmtName, int resultFormat);

---

🎀 DESCRIPTION 🎀

so PQparamExec() and PQparamExecPrepared() both execute a parameterized query using the parameters sitting in a PGparam. the only difference between these two is:

• PQparamExec() wants a parameterized command string
• PQparamExecPrepared() wants a stmtName that you already prepared earlier via PQprepare()

both functions take a param argument, and bestie, that param must contain the same number of parameters as either the command string or the previously prepared stmtName. no extra, no missing, no "close enough" 🫶

internally, the param gets transformed into parallel arrays, and those arrays get handed off to a PQexecParams() or PQexecPrepared() call. like a lil relay race 🏃♀️

the resultFormat argument tells it whether you want text or binary results — a value of zero or one respectively. and PQgetf supports both text and binary result formats, with the exclusion of arrays and composites which only support binary. so if you're doing arrays or composites, binary or bust, no cap 💀

---

🔥 RETURN VALUE 🔥

on success, you get a pointer to a PGresult. slay. ✨

on error, NULL is returned and PQgeterror(3) will contain an error message. 📣

⚠️ IMPORTANT! ⚠️

okay this part is important, sit up bestie 👑

there's a behavior difference between PQparamExec() / PQparamExecPrepared() and the libpq functions they wrap, PQexecParams() and PQexecPrepared(). listen:

PQparamExec() and PQparamExecPrepared() only return a non-NULL PGresult when the result status is one of these three:

• PGRES_COMMAND_OK
• PGRES_TUPLES_OK
• PGRES_EMPTY_QUERY

if these functions detect any other result status, the PGresult is cleared and a NULL result is returned. gone. poof. 💨

but wait, they're not being shady about it — before clearing the PGresult and returning NULL, these functions first copy the result error message into the libpqtypes error system, which you can get at via PQgeterror(3). this lets applications get a result's error message without needing the result object. so thoughtful of them fr fr.

conn error messages are also copied to the libpqtypes error system. 🫶

this whole behavior difference exists to give you a single error indicator (a NULL return) and a single function that can get the error message, PQgeterror(). one stop shop, main character energy 👑

---

🌈 EXAMPLES 🌈

🍓 Using PQparamExec

this example uses PQparamExec() to execute a query using a PGparam. it also demonstrates how to detect a failed exec and output an error message. very demure, very mindful 🎀

PGparam *param = PQparamCreate(conn);

if(!PQputf(param, "%text %int4", "ACTIVE", CAT_CAR))
{
     fprintf(stderr, "PQputf: %s\n", PQgeterror());
}
else
{
     PGresult *res = PQparamExec(conn, param,
          "SELECT * FROM t WHERE status=$1 AND category=$2", 1);

     if(!res)
          fprintf(stderr, "PQparamExec: %s\n", PQgeterror());
     else
          print_results(res);

     PQclear(res);
}

PQparamClear(param);

🧚 Using PQparamExecPrepared

PQparamExecPrepared() behaves identically to PQparamExec(), except PQparamExecPrepared() requires that a statement has been previously prepared via PQprepare(). also, a stmtName is supplied rather than a parameterized command string. that's the whole tea ☕

---

👑 AUTHOR 👑

a contribution of eSilo, LLC. for the PostgreSQL Database Management System. written by Andrew Chernow and Merlin Moncure. icons only 💜

---

🙈 REPORTING BUGS 🙈

report bugs to <libpqtypes@esilo.com>. tell them everything, they can handle it 📬

---

📜 COPYRIGHT 📜

Copyright (c) 2011 eSilo, LLC. All rights reserved.

this is free software; see the source for copying conditions. there is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. so like, no promises bestie 😭

---

🌟 SEE ALSO 🌟

• PQparamCreate(3)
• PQparamSendQuery(3)
• PQparamSendQueryPrepared(3)

---

and that's the whole page!! 🦋 this one came from the libpqtypes manual, dated 2011 — mwah, kiss the docs, go run your parameterized queries responsibly, ily, bye 💖✨🎀