Skip to content

Commit 9a8920e

Browse files
tglsfdctglsfdc
committed
Add PQdescribePrepared, PQdescribePortal, and related functions to libpq
to allow obtaining information about previously prepared statements and open cursors. Volkan Yazici
1 parent 46d61eb commit 9a8920e

File tree

6 files changed

+472
-24
lines changed

6 files changed

+472
-24
lines changed

‎doc/src/sgml/libpq.sgml‎

Lines changed: 162 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.214 2006/07/27 13:20:24 momjian Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.215 2006/08/18 19:52:39 tgl Exp $ -->
22

33
<chapter id="libpq">
44
<title><application>libpq</application> - C Library</title>
@@ -1244,7 +1244,8 @@ or any particular element in the array is zero, the server assigns a data type
12441244
to the parameter symbol in the same way it would do for an untyped literal
12451245
string. Also, the query may use parameter symbols with numbers higher than
12461246
<parameter>nParams</>; data types will be inferred for these symbols as
1247-
well.
1247+
well. (See <function>PQdescribePrepared</function> for a means to find out
1248+
what data types were inferred.)
12481249
</para>
12491250

12501251
<para>
@@ -1255,13 +1256,6 @@ send the command at all.
12551256
Use <function>PQerrorMessage</function> to get more information
12561257
about such errors.
12571258
</para>
1258-
1259-
<para>
1260-
At present, there is no way to determine the actual data type inferred for
1261-
any parameters whose types are not specified in <parameter>paramTypes[]</>.
1262-
This is a <application>libpq</> omission that will probably be rectified
1263-
in a future release.
1264-
</para>
12651259
</listitem>
12661260
</varlistentry>
12671261
</variablelist>
@@ -1315,6 +1309,72 @@ the prepared statement's parameter types were determined when it was created).
13151309
</para>
13161310
</listitem>
13171311
</varlistentry>
1312+
1313+
<varlistentry>
1314+
<term><function>PQdescribePrepared</function><indexterm><primary>PQdescribePrepared</></></term>
1315+
<listitem>
1316+
<para>
1317+
Submits a request to obtain information about the specified
1318+
prepared statement, and waits for completion.
1319+
<synopsis>
1320+
PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);
1321+
</synopsis>
1322+
</para>
1323+
1324+
<para>
1325+
<function>PQdescribePrepared</> allows an application to obtain information
1326+
about a previously prepared statement.
1327+
<function>PQdescribePrepared</> is supported only in protocol 3.0 and later
1328+
connections; it will fail when using protocol 2.0.
1329+
</para>
1330+
1331+
<para>
1332+
<parameter>stmtName</> may be <literal>""</> or NULL to reference the unnamed
1333+
statement, otherwise it must be the name of an existing prepared statement.
1334+
On success, a <structname>PGresult</> with status
1335+
<literal>PGRES_COMMAND_OK</literal> is returned. The functions
1336+
<function>PQnparams</function> and <function>PQparamtype</function>
1337+
may be applied to this <structname>PGresult</> to obtain information
1338+
about the parameters of the prepared statement, and the functions
1339+
<function>PQnfields</function>, <function>PQfname</function>,
1340+
<function>PQftype</function>, etc provide information about the result
1341+
columns (if any) of the statement.
1342+
</para>
1343+
</listitem>
1344+
</varlistentry>
1345+
1346+
<varlistentry>
1347+
<term><function>PQdescribePortal</function><indexterm><primary>PQdescribePortal</></></term>
1348+
<listitem>
1349+
<para>
1350+
Submits a request to obtain information about the specified
1351+
portal, and waits for completion.
1352+
<synopsis>
1353+
PGresult *PQdescribePortal(PGconn *conn, const char *portalName);
1354+
</synopsis>
1355+
</para>
1356+
1357+
<para>
1358+
<function>PQdescribePortal</> allows an application to obtain information
1359+
about a previously created portal. (<application>libpq</> does not provide
1360+
any direct access to portals, but you can use this function to inspect the
1361+
properties of a cursor created with a <command>DECLARE CURSOR</> SQL command.)
1362+
<function>PQdescribePortal</> is supported only in protocol 3.0 and later
1363+
connections; it will fail when using protocol 2.0.
1364+
</para>
1365+
1366+
<para>
1367+
<parameter>portalName</> may be <literal>""</> or NULL to reference the unnamed
1368+
portal, otherwise it must be the name of an existing portal.
1369+
On success, a <structname>PGresult</> with status
1370+
<literal>PGRES_COMMAND_OK</literal> is returned. The functions
1371+
<function>PQnfields</function>, <function>PQfname</function>,
1372+
<function>PQftype</function>, etc may be applied to the
1373+
<structname>PGresult</> to obtain information about the result
1374+
columns (if any) of the portal.
1375+
</para>
1376+
</listitem>
1377+
</varlistentry>
13181378
</variablelist>
13191379
</para>
13201380

@@ -1707,8 +1767,11 @@ object, just as with a <structname>PGresult</structname> returned by
17071767
These functions are used to extract information from a
17081768
<structname>PGresult</structname> object that represents a successful
17091769
query result (that is, one that has status
1710-
<literal>PGRES_TUPLES_OK</literal>). For objects with other status
1711-
values they will act as though the result has zero rows and zero columns.
1770+
<literal>PGRES_TUPLES_OK</literal>). They can also be used to extract
1771+
information from a successful Describe operation: a Describe's result
1772+
has all the same column information that actual execution of the query
1773+
would provide, but it has zero rows. For objects with other status values,
1774+
these functions will act as though the result has zero rows and zero columns.
17121775
</para>
17131776

17141777
<variablelist>
@@ -2040,6 +2103,43 @@ on <function>PQfsize</function> to obtain the actual data length.
20402103
</listitem>
20412104
</varlistentry>
20422105

2106+
<varlistentry>
2107+
<term><function>PQnparams</function><indexterm><primary>PQnparams</></></term>
2108+
<listitem>
2109+
<para>
2110+
Returns the number of parameters of a prepared statement.
2111+
<synopsis>
2112+
int PQnparams(const PGresult *res);
2113+
</synopsis>
2114+
</para>
2115+
2116+
<para>
2117+
This function is only useful when inspecting the result of
2118+
<function>PQdescribePrepared</>. For other types of queries it will
2119+
return zero.
2120+
</para>
2121+
</listitem>
2122+
</varlistentry>
2123+
2124+
<varlistentry>
2125+
<term><function>PQparamtype</function><indexterm><primary>PQparamtype</></></term>
2126+
<listitem>
2127+
<para>
2128+
Returns the data type of the indicated statement parameter.
2129+
Parameter numbers start at 0.
2130+
<synopsis>
2131+
Oid PQparamtype(const PGresult *res, int param_number);
2132+
</synopsis>
2133+
</para>
2134+
2135+
<para>
2136+
This function is only useful when inspecting the result of
2137+
<function>PQdescribePrepared</>. For other types of queries it will
2138+
return zero.
2139+
</para>
2140+
</listitem>
2141+
</varlistentry>
2142+
20432143
<varlistentry>
20442144
<term><function>PQprint</function><indexterm><primary>PQprint</></></term>
20452145
<listitem>
@@ -2486,13 +2586,17 @@ underlying functions that <function>PQexec</function> is built from:
24862586
<function>PQsendQuery</function> and <function>PQgetResult</function>.
24872587
There are also
24882588
<function>PQsendQueryParams</function>,
2489-
<function>PQsendPrepare</function>, and
2589+
<function>PQsendPrepare</function>,
24902590
<function>PQsendQueryPrepared</function>,
2591+
<function>PQsendDescribePrepared</function>, and
2592+
<function>PQsendDescribePortal</function>,
24912593
which can be used with <function>PQgetResult</function> to duplicate the
24922594
functionality of
24932595
<function>PQexecParams</function>,
2494-
<function>PQprepare</function>, and
2495-
<function>PQexecPrepared</function>
2596+
<function>PQprepare</function>,
2597+
<function>PQexecPrepared</function>,
2598+
<function>PQdescribePrepared</function>, and
2599+
<function>PQdescribePortal</function>
24962600
respectively.
24972601

24982602
<variablelist>
@@ -2598,6 +2702,50 @@ int PQsendQueryPrepared(PGconn *conn,
25982702
</listitem>
25992703
</varlistentry>
26002704

2705+
<varlistentry>
2706+
<term><function>PQsendDescribePrepared</><indexterm><primary>PQsendDescribePrepared</></></term>
2707+
<listitem>
2708+
<para>
2709+
Submits a request to obtain information about the specified
2710+
prepared statement, without waiting for completion.
2711+
<synopsis>
2712+
int PQsendDescribePrepared(PGconn *conn, const char *stmtName);
2713+
</synopsis>
2714+
2715+
This is an asynchronous version of <function>PQdescribePrepared</>: it
2716+
returns 1 if it was able to dispatch the request, and 0 if not.
2717+
After a successful call, call <function>PQgetResult</function>
2718+
to obtain the results.
2719+
The function's parameters are handled identically to
2720+
<function>PQdescribePrepared</function>. Like
2721+
<function>PQdescribePrepared</function>, it will not work on 2.0-protocol
2722+
connections.
2723+
</para>
2724+
</listitem>
2725+
</varlistentry>
2726+
2727+
<varlistentry>
2728+
<term><function>PQsendDescribePortal</><indexterm><primary>PQsendDescribePortal</></></term>
2729+
<listitem>
2730+
<para>
2731+
Submits a request to obtain information about the specified
2732+
portal, without waiting for completion.
2733+
<synopsis>
2734+
int PQsendDescribePortal(PGconn *conn, const char *portalName);
2735+
</synopsis>
2736+
2737+
This is an asynchronous version of <function>PQdescribePortal</>: it
2738+
returns 1 if it was able to dispatch the request, and 0 if not.
2739+
After a successful call, call <function>PQgetResult</function>
2740+
to obtain the results.
2741+
The function's parameters are handled identically to
2742+
<function>PQdescribePortal</function>. Like
2743+
<function>PQdescribePortal</function>, it will not work on 2.0-protocol
2744+
connections.
2745+
</para>
2746+
</listitem>
2747+
</varlistentry>
2748+
26012749
<varlistentry>
26022750
<term><function>PQgetResult</function><indexterm><primary>PQgetResult</></></term>
26032751
<listitem>

‎src/interfaces/libpq/exports.txt‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.13 2006/07/04 13:22:15 momjian Exp $
1+
# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.14 2006/08/18 19:52:39 tgl Exp $
22
# Functions to be exported by libpq DLLs
33
PQconnectdb 1
44
PQsetdbLogin 2
@@ -130,3 +130,9 @@ PQescapeByteaConn 127
130130
PQencryptPassword 128
131131
PQisthreadsafe 129
132132
enlargePQExpBuffer 130
133+
PQnparams 131
134+
PQparamtype 132
135+
PQdescribePrepared 133
136+
PQdescribePortal 134
137+
PQsendDescribePrepared 135
138+
PQsendDescribePortal 136

0 commit comments

Comments
 (0)