PQparamSendQuery(3)

📦 version 1.5.1, in debian bookworm, ubuntu jammy, ubuntu noble

✨ PQparamSendQuery ✨

okay so bestie, welcome to the libpqtypes manual 💖 you're about to meet PQparamSendQuery and PQparamSendQueryPrepared, two lil functions that fire off an asynchronous parameterized query using the parameters sitting in a PGparam. they're basically the group chat of "send it now, deal with the replies later". 🫶

🌸 NAME 🌸

PQparamSendQuery, PQparamSendQueryPrepared — Executes an asynchronous paramertized query using the parameters in a PGparam.

🎀 SYNOPSIS 🎀

#include <libpqtypes.h>

int PQparamSendQuery(PGconn *conn, PGparam *param,
                     const char *command, int resultFormat);
int PQparamSendQueryPrepared(PGconn *conn, PGparam *param,
                             const char *stmtName, int resultFormat);

🦋 DESCRIPTION 🦋

so PQparamSendQuery() and PQparamSendQueryPrepared() execute an asynchronous paramertized query using the parameters in a PGparam. and like, the only difference between them? PQparamSendQuery() wants a parameterized command string, while PQparamSendQueryPrepared() wants a stmtName that you already prepared earlier via PQprepare(). that's it. that's the whole plot twist. 💅

both functions take a param argument, and bestie, it must contain the same number of parameters as either the command string or the previously prepared stmtName. no extra, no missing, no "oops I forgot one". internally, the param gets transformed into parallel arrays that get handed off to a PQsendQueryParams() or PQsendQueryPrepared() call. very demure, very mindful, very array-shaped. ✨

the resultFormat argument tells it whether you want text or binary results — a value of zero or one respectively. PQgetf supports both text and binary result formats, with the exclusion of arrays and composites which only support binary. so if you're out here wanting a text array, that's a no from the codebase. 😭

after successfully calling PQparamSendQuery() or PQparamSendQueryPrepared(), you gotta call libpq's PQgetResult() one or more times to actually obtain the results. it's giving "sent the text, now wait for the reply". 📱

👑 RETURN VALUE 👑

  • On success, a non-zero value is returned. slay. ✅
  • On error, zero is returned, and PQgeterror(3) will contain an error message. 💀

🌈 EXAMPLES 🌈

🍓 Using PQparamSendQuery

this example uses PQparamSendQuery() to execute a query using a PGparam.

PGparam *param = PQparamCreate(conn);

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

     if(!success)
          fprintf(stderr, "PQparamSendQuery: %s\n", PQgeterror());
     else
          get_and_print_results(conn); /* calls PQgetResult() */
}

PQparamClear(param);

🧚 Using PQparamSendQueryPrepared

PQparamSendQueryPrepared() is behaves identically to PQparamSendQuery(), except PQparamSendQueryPrepared() requires that a statement has been previously prepared via PQprepare(). also, a stmtName is supplied rather than a parameterized command string. same energy, different entrance. 🚪✨

💜 AUTHOR 💜

A contribution of eSilo, LLC. for the PostgreSQL Database Management System. Written by Andrew Chernow and Merlin Moncure. kings, honestly. 👑

🙈 REPORTING BUGS 🙈

Report bugs to <libpqtypes@esilo.com>. don't be shy, they want to know fr fr. 📬

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.

no warranty bestie, like none, not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. read the source if you need the tea. ☕

⭐ SEE ALSO ⭐

and that's the whole page, periodt. this was the libpqtypes manual, from the 2011 era, and you're officially caught up. go send some queries, bestie, you're the main character now. 💅🦋💖

📦 where this page comes from