database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-17 17:02:08 +03:00
Code Activity

Add PQdescribePrepared, PQdescribePortal, and related functions to libpq

Browse Source 
to allow obtaining information about previously prepared statements and
open cursors.  Volkan Yazici
This commit is contained in:
Tom Lane
2006-08-18 19:52:39 +00:00
parent 46d61eb218
commit 9a8920e1d7
6 changed files with 472 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.214 2006/07/27 13:20:24 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.215 2006/08/18 19:52:39 tgl Exp $ -->
<chapter id="libpq">
<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
to the parameter symbol in the same way it would do for an untyped literal
string. Also, the query may use parameter symbols with numbers higher than
<parameter>nParams</>; data types will be inferred for these symbols as
well.
well. (See <function>PQdescribePrepared</function> for a means to find out
what data types were inferred.)
</para>
<para>
@ -1255,13 +1256,6 @@ send the command at all.
Use <function>PQerrorMessage</function> to get more information
about such errors.
</para>
<para>
At present, there is no way to determine the actual data type inferred for
any parameters whose types are not specified in <parameter>paramTypes[]</>.
This is a <application>libpq</> omission that will probably be rectified
in a future release.
</para>
</listitem>
</varlistentry>
</variablelist>
@ -1315,6 +1309,72 @@ the prepared statement's parameter types were determined when it was created).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>PQdescribePrepared</function><indexterm><primary>PQdescribePrepared</></></term>
<listitem>
<para>
Submits a request to obtain information about the specified
prepared statement, and waits for completion.
<synopsis>
PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);
</synopsis>
</para>
<para>
<function>PQdescribePrepared</> allows an application to obtain information
about a previously prepared statement.
<function>PQdescribePrepared</> is supported only in protocol 3.0 and later
connections; it will fail when using protocol 2.0.
</para>
<para>
<parameter>stmtName</> may be <literal>""</> or NULL to reference the unnamed
statement, otherwise it must be the name of an existing prepared statement.
On success, a <structname>PGresult</> with status
<literal>PGRES_COMMAND_OK</literal> is returned. The functions
<function>PQnparams</function> and <function>PQparamtype</function>
may be applied to this <structname>PGresult</> to obtain information
about the parameters of the prepared statement, and the functions
<function>PQnfields</function>, <function>PQfname</function>,
<function>PQftype</function>, etc provide information about the result
columns (if any) of the statement.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>PQdescribePortal</function><indexterm><primary>PQdescribePortal</></></term>
<listitem>
<para>
Submits a request to obtain information about the specified
portal, and waits for completion.
<synopsis>
PGresult *PQdescribePortal(PGconn *conn, const char *portalName);
</synopsis>
</para>
<para>
<function>PQdescribePortal</> allows an application to obtain information
about a previously created portal. (<application>libpq</> does not provide
any direct access to portals, but you can use this function to inspect the
properties of a cursor created with a <command>DECLARE CURSOR</> SQL command.)
<function>PQdescribePortal</> is supported only in protocol 3.0 and later
connections; it will fail when using protocol 2.0.
</para>
<para>
<parameter>portalName</> may be <literal>""</> or NULL to reference the unnamed
portal, otherwise it must be the name of an existing portal.
On success, a <structname>PGresult</> with status
<literal>PGRES_COMMAND_OK</literal> is returned. The functions
<function>PQnfields</function>, <function>PQfname</function>,
<function>PQftype</function>, etc may be applied to the
<structname>PGresult</> to obtain information about the result
columns (if any) of the portal.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
@ -1707,8 +1767,11 @@ object, just as with a <structname>PGresult</structname> returned by
These functions are used to extract information from a
<structname>PGresult</structname> object that represents a successful
query result (that is, one that has status
<literal>PGRES_TUPLES_OK</literal>). For objects with other status
values they will act as though the result has zero rows and zero columns.
<literal>PGRES_TUPLES_OK</literal>). They can also be used to extract
information from a successful Describe operation: a Describe's result
has all the same column information that actual execution of the query
would provide, but it has zero rows. For objects with other status values,
these functions will act as though the result has zero rows and zero columns.
</para>
<variablelist>
@ -2040,6 +2103,43 @@ on <function>PQfsize</function> to obtain the actual data length.
</listitem>
</varlistentry>
<varlistentry>
<term><function>PQnparams</function><indexterm><primary>PQnparams</></></term>
<listitem>
<para>
Returns the number of parameters of a prepared statement.
<synopsis>
int PQnparams(const PGresult *res);
</synopsis>
</para>
<para>
This function is only useful when inspecting the result of
<function>PQdescribePrepared</>. For other types of queries it will
return zero.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>PQparamtype</function><indexterm><primary>PQparamtype</></></term>
<listitem>
<para>
Returns the data type of the indicated statement parameter.
Parameter numbers start at 0.
<synopsis>
Oid PQparamtype(const PGresult *res, int param_number);
</synopsis>
</para>
<para>
This function is only useful when inspecting the result of
<function>PQdescribePrepared</>. For other types of queries it will
return zero.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>PQprint</function><indexterm><primary>PQprint</></></term>
<listitem>
@ -2486,13 +2586,17 @@ underlying functions that <function>PQexec</function> is built from:
<function>PQsendQuery</function> and <function>PQgetResult</function>.
There are also
<function>PQsendQueryParams</function>,
<function>PQsendPrepare</function>, and
<function>PQsendPrepare</function>,
<function>PQsendQueryPrepared</function>,
<function>PQsendDescribePrepared</function>, and
<function>PQsendDescribePortal</function>,
which can be used with <function>PQgetResult</function> to duplicate the
functionality of
<function>PQexecParams</function>,
<function>PQprepare</function>, and
<function>PQexecPrepared</function>
<function>PQprepare</function>,
<function>PQexecPrepared</function>,
<function>PQdescribePrepared</function>, and
<function>PQdescribePortal</function>
respectively.
<variablelist>
@ -2598,6 +2702,50 @@ int PQsendQueryPrepared(PGconn *conn,
</listitem>
</varlistentry>
<varlistentry>
<term><function>PQsendDescribePrepared</><indexterm><primary>PQsendDescribePrepared</></></term>
<listitem>
<para>
Submits a request to obtain information about the specified
prepared statement, without waiting for completion.
<synopsis>
int PQsendDescribePrepared(PGconn *conn, const char *stmtName);
</synopsis>
This is an asynchronous version of <function>PQdescribePrepared</>: it
returns 1 if it was able to dispatch the request, and 0 if not.
After a successful call, call <function>PQgetResult</function>
to obtain the results.
The function's parameters are handled identically to
<function>PQdescribePrepared</function>. Like
<function>PQdescribePrepared</function>, it will not work on 2.0-protocol
connections.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>PQsendDescribePortal</><indexterm><primary>PQsendDescribePortal</></></term>
<listitem>
<para>
Submits a request to obtain information about the specified
portal, without waiting for completion.
<synopsis>
int PQsendDescribePortal(PGconn *conn, const char *portalName);
</synopsis>
This is an asynchronous version of <function>PQdescribePortal</>: it
returns 1 if it was able to dispatch the request, and 0 if not.
After a successful call, call <function>PQgetResult</function>
to obtain the results.
The function's parameters are handled identically to
<function>PQdescribePortal</function>. Like
<function>PQdescribePortal</function>, it will not work on 2.0-protocol
connections.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>PQgetResult</function><indexterm><primary>PQgetResult</></></term>
<listitem>