|
1 | 1 | <!-- |
2 | | -$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.130 2003/08/01 03:10:04 momjian Exp $ |
| 2 | +$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.131 2003/08/13 16:29:03 tgl Exp $ |
3 | 3 | --> |
4 | 4 |
|
5 | 5 | <chapter id="libpq"> |
@@ -1090,6 +1090,53 @@ than one nonempty command.) This is a limitation of the underlying protocol, |
1090 | 1090 | but has some usefulness as an extra defense against SQL-injection attacks. |
1091 | 1091 | </para> |
1092 | 1092 |
|
| 1093 | +<para> |
| 1094 | +<variablelist> |
| 1095 | +<varlistentry> |
| 1096 | +<term><function>PQexecPrepared</function></term> |
| 1097 | +<listitem> |
| 1098 | +<para> |
| 1099 | + Sends a request to execute a prepared statement with given |
| 1100 | + parameters, and waits for the result. |
| 1101 | +<synopsis> |
| 1102 | +PGresult *PQexecPrepared(PGconn *conn, |
| 1103 | + const char *stmtName, |
| 1104 | + int nParams, |
| 1105 | + const char * const *paramValues, |
| 1106 | + const int *paramLengths, |
| 1107 | + const int *paramFormats, |
| 1108 | + int resultFormat); |
| 1109 | +</synopsis> |
| 1110 | +</para> |
| 1111 | + |
| 1112 | +<para> |
| 1113 | +<function>PQexecPrepared</> is like <function>PQexecParams</>, but the |
| 1114 | +command to be executed is specified by naming a previously-prepared |
| 1115 | +statement, instead of giving a query string. This feature allows commands |
| 1116 | +that will be used repeatedly to be parsed and planned just once, rather |
| 1117 | +than each time they are executed. |
| 1118 | +<function>PQexecPrepared</> is supported only in protocol 3.0 and later |
| 1119 | +connections; it will fail when using protocol 2.0. |
| 1120 | +</para> |
| 1121 | + |
| 1122 | +<para> |
| 1123 | +The parameters are identical to <function>PQexecParams</>, except that the |
| 1124 | +name of a prepared statement is given instead of a query string, and the |
| 1125 | +<parameter>paramTypes[]</> parameter is not present (it is not needed since |
| 1126 | +the prepared statement's parameter types were determined when it was created). |
| 1127 | +</para> |
| 1128 | +</listitem> |
| 1129 | +</varlistentry> |
| 1130 | +</variablelist> |
| 1131 | + |
| 1132 | +Presently, prepared statements for use with <function>PQexecPrepared</> |
| 1133 | +must be set up by executing an SQL <command>PREPARE</> command, |
| 1134 | +which is typically sent with <function>PQexec</> (though any of |
| 1135 | +<application>libpq</>'s query-submission functions may be used). |
| 1136 | +A lower-level interface for preparing statements may be offered in a |
| 1137 | +future release. |
| 1138 | +</para> |
| 1139 | + |
1093 | 1140 | <para> |
1094 | 1141 | The <structname>PGresult</structname> structure encapsulates the result |
1095 | 1142 | returned by the server. |
@@ -1775,7 +1822,7 @@ SQL commands are fed to your database. |
1775 | 1822 | <para> |
1776 | 1823 | Note that it is not necessary nor correct to do escaping when a data |
1777 | 1824 | value is passed as a separate parameter in <function>PQexecParams</> or |
1778 | | -<function>PQsendQueryParams</>. |
| 1825 | +its sibling routines. |
1779 | 1826 |
|
1780 | 1827 | <synopsis> |
1781 | 1828 | size_t PQescapeString (char *to, const char *from, size_t length); |
@@ -1961,9 +2008,11 @@ discarded by <function>PQexec</function>. |
1961 | 2008 | Applications that do not like these limitations can instead use the |
1962 | 2009 | underlying functions that <function>PQexec</function> is built from: |
1963 | 2010 | <function>PQsendQuery</function> and <function>PQgetResult</function>. |
1964 | | -There is also <function>PQsendQueryParams</function>, which can be |
1965 | | -used with <function>PQgetResult</function> to duplicate the functionality |
1966 | | -of <function>PQexecParams</function>. |
| 2011 | +There are also <function>PQsendQueryParams</function> and |
| 2012 | +<function>PQsendQueryPrepared</function>, which can be used with |
| 2013 | +<function>PQgetResult</function> to duplicate the functionality of |
| 2014 | +<function>PQexecParams</function> and <function>PQexecPrepared</function> |
| 2015 | +respectively. |
1967 | 2016 |
|
1968 | 2017 | <variablelist> |
1969 | 2018 | <varlistentry> |
@@ -2014,13 +2063,41 @@ int PQsendQueryParams(PGconn *conn, |
2014 | 2063 | </listitem> |
2015 | 2064 | </varlistentry> |
2016 | 2065 |
|
| 2066 | +<varlistentry> |
| 2067 | +<term><function>PQsendQueryPrepared</function></term> |
| 2068 | +<listitem> |
| 2069 | +<para> |
| 2070 | + Sends a request to execute a prepared statement with given |
| 2071 | + parameters, without waiting for the result(s). |
| 2072 | +<synopsis> |
| 2073 | +int PQsendQueryPrepared(PGconn *conn, |
| 2074 | + const char *stmtName, |
| 2075 | + int nParams, |
| 2076 | + const char * const *paramValues, |
| 2077 | + const int *paramLengths, |
| 2078 | + const int *paramFormats, |
| 2079 | + int resultFormat); |
| 2080 | +</synopsis> |
| 2081 | + |
| 2082 | +This is similar to <function>PQsendQueryParams</function>, but the |
| 2083 | +command to be executed is specified by naming a previously-prepared |
| 2084 | +statement, instead of giving a query string. |
| 2085 | +The function's parameters are handled identically to |
| 2086 | +<function>PQexecPrepared</function>. Like |
| 2087 | +<function>PQexecPrepared</function>, it will not work on 2.0-protocol |
| 2088 | +connections. |
| 2089 | +</para> |
| 2090 | +</listitem> |
| 2091 | +</varlistentry> |
| 2092 | + |
2017 | 2093 | <varlistentry> |
2018 | 2094 | <term><function>PQgetResult</function></term> |
2019 | 2095 | <listitem> |
2020 | 2096 | <para> |
2021 | 2097 | Waits for the next result from a prior |
2022 | | - <function>PQsendQuery</function> or |
2023 | | - <function>PQsendQueryParams</function>, |
| 2098 | + <function>PQsendQuery</function>, |
| 2099 | + <function>PQsendQueryParams</function>, or |
| 2100 | + <function>PQsendQueryPrepared</function> call, |
2024 | 2101 | and returns it. A null pointer is returned when the command is complete |
2025 | 2102 | and there will be no more results. |
2026 | 2103 | <synopsis> |
|