From 9a8920e1d7291e41b3d0d9f15f735f68c2ad987c Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 18 Aug 2006 19:52:39 +0000 Subject: Add PQdescribePrepared, PQdescribePortal, and related functions to libpq to allow obtaining information about previously prepared statements and open cursors. Volkan Yazici --- doc/src/sgml/libpq.sgml | 176 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 162 insertions(+), 14 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 7ffd15a0388..db6525e0c88 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,4 +1,4 @@ - + <application>libpq</application> - C Library @@ -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 nParams; data types will be inferred for these symbols as -well. +well. (See PQdescribePrepared for a means to find out +what data types were inferred.) @@ -1255,13 +1256,6 @@ send the command at all. Use PQerrorMessage to get more information about such errors. - - -At present, there is no way to determine the actual data type inferred for -any parameters whose types are not specified in paramTypes[]. -This is a libpq omission that will probably be rectified -in a future release. - @@ -1315,6 +1309,72 @@ the prepared statement's parameter types were determined when it was created). + + +PQdescribePreparedPQdescribePrepared + + + Submits a request to obtain information about the specified + prepared statement, and waits for completion. + +PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); + + + + +PQdescribePrepared allows an application to obtain information +about a previously prepared statement. +PQdescribePrepared is supported only in protocol 3.0 and later +connections; it will fail when using protocol 2.0. + + + +stmtName may be "" or NULL to reference the unnamed +statement, otherwise it must be the name of an existing prepared statement. +On success, a PGresult with status +PGRES_COMMAND_OK is returned. The functions +PQnparams and PQparamtype +may be applied to this PGresult to obtain information +about the parameters of the prepared statement, and the functions +PQnfields, PQfname, +PQftype, etc provide information about the result +columns (if any) of the statement. + + + + + +PQdescribePortalPQdescribePortal + + + Submits a request to obtain information about the specified + portal, and waits for completion. + +PGresult *PQdescribePortal(PGconn *conn, const char *portalName); + + + + +PQdescribePortal allows an application to obtain information +about a previously created portal. (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 DECLARE CURSOR SQL command.) +PQdescribePortal is supported only in protocol 3.0 and later +connections; it will fail when using protocol 2.0. + + + +portalName may be "" or NULL to reference the unnamed +portal, otherwise it must be the name of an existing portal. +On success, a PGresult with status +PGRES_COMMAND_OK is returned. The functions +PQnfields, PQfname, +PQftype, etc may be applied to the +PGresult to obtain information about the result +columns (if any) of the portal. + + + @@ -1707,8 +1767,11 @@ object, just as with a PGresult returned by These functions are used to extract information from a PGresult object that represents a successful query result (that is, one that has status -PGRES_TUPLES_OK). For objects with other status -values they will act as though the result has zero rows and zero columns. +PGRES_TUPLES_OK). 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. @@ -2040,6 +2103,43 @@ on PQfsize to obtain the actual data length. + +PQnparamsPQnparams + + + Returns the number of parameters of a prepared statement. + +int PQnparams(const PGresult *res); + + + + +This function is only useful when inspecting the result of +PQdescribePrepared. For other types of queries it will +return zero. + + + + + +PQparamtypePQparamtype + + + Returns the data type of the indicated statement parameter. + Parameter numbers start at 0. + +Oid PQparamtype(const PGresult *res, int param_number); + + + + +This function is only useful when inspecting the result of +PQdescribePrepared. For other types of queries it will +return zero. + + + + PQprintPQprint @@ -2486,13 +2586,17 @@ underlying functions that PQexec is built from: PQsendQuery and PQgetResult. There are also PQsendQueryParams, -PQsendPrepare, and +PQsendPrepare, PQsendQueryPrepared, +PQsendDescribePrepared, and +PQsendDescribePortal, which can be used with PQgetResult to duplicate the functionality of PQexecParams, -PQprepare, and -PQexecPrepared +PQprepare, +PQexecPrepared, +PQdescribePrepared, and +PQdescribePortal respectively. @@ -2598,6 +2702,50 @@ int PQsendQueryPrepared(PGconn *conn, + +PQsendDescribePreparedPQsendDescribePrepared + + + Submits a request to obtain information about the specified + prepared statement, without waiting for completion. + +int PQsendDescribePrepared(PGconn *conn, const char *stmtName); + + + This is an asynchronous version of PQdescribePrepared: it + returns 1 if it was able to dispatch the request, and 0 if not. + After a successful call, call PQgetResult + to obtain the results. + The function's parameters are handled identically to + PQdescribePrepared. Like + PQdescribePrepared, it will not work on 2.0-protocol + connections. + + + + + +PQsendDescribePortalPQsendDescribePortal + + + Submits a request to obtain information about the specified + portal, without waiting for completion. + +int PQsendDescribePortal(PGconn *conn, const char *portalName); + + + This is an asynchronous version of PQdescribePortal: it + returns 1 if it was able to dispatch the request, and 0 if not. + After a successful call, call PQgetResult + to obtain the results. + The function's parameters are handled identically to + PQdescribePortal. Like + PQdescribePortal, it will not work on 2.0-protocol + connections. + + + + PQgetResultPQgetResult -- cgit v1.2.3