statements without necessarily specifying the datatypes of their parameters.
Abhijit Menon-Sen with some help from Tom Lane.
out-of-memory conditions or serious errors such as inability
to send the command to the server.
If a null pointer is returned, it
- should be treated like a PGRES_FATAL_ERROR result. Use
- PQerrorMessage to get more information about the error.
+ should be treated like a PGRES_FATAL_ERROR result.
+ Use PQerrorMessage to get more information
+ about such errors.
but has some usefulness as an extra defense against SQL-injection attacks.
+
+
+
+ Submits a request to create a prepared statement with the
+ given parameters, and waits for completion.
+
+PGresult *PQprepare(PGconn *conn,
+ const char *stmtName,
+ const char *query,
+ int nParams,
+ const Oid *paramTypes);
+
+
+
+PQprepare creates a prepared statement for later execution with
+PQexecPrepared.
+This feature allows commands
+that will be used repeatedly to be parsed and planned just once, rather
+than each time they are executed.
+PQprepare is supported only in protocol 3.0 and later
+connections; it will fail when using protocol 2.0.
+
+
+The function creates a prepared statement named
stmtName+from the
query string, which must contain a single SQL command.+
stmtName may be "" to create an unnamed statement,+in which case any pre-existing unnamed statement is automatically replaced;
+otherwise it is an error if the statement name is already defined in the
+current session.
+If any parameters are used, they are referred
+to in the query as $1, $2, etc.
+
nParams is the number of parameters for which types are+pre-specified in the array
paramTypes[]. (The array pointer+may be
NULL when
nParams is zero.)+
paramTypes[] specifies, by OID, the data types to be assigned to+the parameter symbols. If
paramTypes is NULL,+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.
+
+
+As with PQexec, the result is normally a
+PGresult object whose contents indicate server-side
+success or failure. A null result indicates out-of-memory or inability to
+send the command at all.
+Use PQerrorMessage to get more information
+about such errors.
+
+
+At present, there is no way to determine the actual datatype 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.
+
+
+
+
+
+Prepared statements for use with PQexecPrepared can also be
+created by executing SQL PREPARE statements. (But
+PQprepare is more flexible since it does not require
+parameter types to be pre-specified.) Also, although there is no
+
libpq function for deleting a prepared statement,+the SQL DEALLOCATE statement can be used for that purpose.
+
+
PQexecPrepared is like PQexecParams, but the
command to be executed is specified by naming a previously-prepared
-statement, instead of giving a query string. This feature allows commands
+statement, instead of giving a query string.
+This feature allows commands
that will be used repeatedly to be parsed and planned just once, rather
than each time they are executed.
PQexecPrepared is supported only in protocol 3.0 and later
-
-Presently, prepared statements for use with PQexecPrepared
-must be set up by executing an SQL PREPARE command,
-which is typically sent with PQexec (though any of
-
libpq's query-submission functions may be used).-A lower-level interface for preparing statements may be offered in a
-future release.
Applications that do not like these limitations can instead use the
underlying functions that PQexec is built from:
PQsendQuery and PQgetResult.
-There are also PQsendQueryParams and
-PQsendQueryPrepared, which can be used with
-PQgetResult to duplicate the functionality of
-PQexecParams and PQexecPrepared
+There are also
+PQsendQueryParams,
+PQsendPrepare, and
+PQsendQueryPrepared,
+which can be used with PQgetResult to duplicate the
+functionality of
+PQexecParams,
+PQprepare, and
+PQexecPrepared
respectively.
+
+
PQsendPreparePQsendPrepare+
+ Sends a request to create a prepared statement with the given
+ parameters, without waiting for completion.
+
+int PQsendPrepare(PGconn *conn,
+ const char *stmtName,
+ const char *query,
+ int nParams,
+ const Oid *paramTypes);
+
+
+ This is an asynchronous version of PQprepare: it
+ returns 1 if it was able to dispatch the request, and 0 if not.
+ After a successful call, call PQgetResult
+ to determine whether the server successfully created the prepared
+ statement.
+ The function's parameters are handled identically to
+ PQprepare. Like
+ PQprepare, it will not work on 2.0-protocol
+ connections.
+
+
+
+
PQsendQueryPreparedPQsendQueryPrepared
Waits for the next result from a prior
PQsendQuery,
- PQsendQueryParams, or
+ PQsendQueryParams,
+ PQsendPrepare, or
PQsendQueryPrepared call,
and returns it. A null pointer is returned when the command is complete
and there will be no more results.
+# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.2 2004/10/18 22:00:42 tgl Exp $
# Functions to be exported by libpq DLLs
PQconnectdb 1
PQsetdbLogin 2
pg_char_to_encoding 115
pg_valid_server_encoding 116
pqsignal 117
+PQprepare 118
+PQsendPrepare 119
*
*
* IDENTIFICATION
- * $PostgreSQL: pgsql/src/interfaces/libpq/fe-exec.c,v 1.163 2004/10/16 22:52:53 tgl Exp $
+ * $PostgreSQL: pgsql/src/interfaces/libpq/fe-exec.c,v 1.164 2004/10/18 22:00:42 tgl Exp $
*
*-------------------------------------------------------------------------
*/
}
/* remember we are using simple query protocol */
- conn->ext_query = false;
+ conn->queryclass = PGQUERY_SIMPLE;
/*
* Give the data a push. In nonblock mode, don't complain if we're
resultFormat);
}
+/*
+ * PQsendPrepare
+ * Submit a Parse message, but don't wait for it to finish
+ *
+ * Returns: 1 if successfully submitted
+ * 0 if error (conn->errorMessage is set)
+ */
+int
+PQsendPrepare(PGconn *conn,
+ const char *stmtName, const char *query,
+ int nParams, const Oid *paramTypes)
+{
+ if (!PQsendQueryStart(conn))
+ return 0;
+
+ if (!stmtName)
+ {
+ printfPQExpBuffer(&conn->errorMessage,
+ libpq_gettext("statement name is a null pointer\n"));
+ return 0;
+ }
+
+ if (!query)
+ {
+ printfPQExpBuffer(&conn->errorMessage,
+ libpq_gettext("command string is a null pointer\n"));
+ return 0;
+ }
+
+ /* This isn't gonna work on a 2.0 server */
+ if (PG_PROTOCOL_MAJOR(conn->pversion) < 3)
+ {
+ printfPQExpBuffer(&conn->errorMessage,
+ libpq_gettext("function requires at least protocol version 3.0\n"));
+ return 0;
+ }
+
+ /* construct the Parse message */
+ if (pqPutMsgStart('P', false, conn) < 0 ||
+ pqPuts(stmtName, conn) < 0 ||
+ pqPuts(query, conn) < 0)
+ goto sendFailed;
+
+ if (nParams > 0 && paramTypes)
+ {
+ int i;
+
+ if (pqPutInt(nParams, 2, conn) < 0)
+ goto sendFailed;
+ for (i = 0; i < nParams; i++)
+ {
+ if (pqPutInt(paramTypes[i], 4, conn) < 0)
+ goto sendFailed;
+ }
+ }
+ else
+ {
+ if (pqPutInt(0, 2, conn) < 0)
+ goto sendFailed;
+ }
+ if (pqPutMsgEnd(conn) < 0)
+ goto sendFailed;
+
+ /* construct the Sync message */
+ if (pqPutMsgStart('S', false, conn) < 0 ||
+ pqPutMsgEnd(conn) < 0)
+ goto sendFailed;
+
+ /* remember we are doing just a Parse */
+ conn->queryclass = PGQUERY_PREPARE;
+
+ /*
+ * Give the data a push. In nonblock mode, don't complain if we're
+ * unable to send it all; PQgetResult() will do any additional
+ * flushing needed.
+ */
+ if (pqFlush(conn) < 0)
+ goto sendFailed;
+
+ /* OK, it's launched! */
+ conn->asyncStatus = PGASYNC_BUSY;
+ return 1;
+
+sendFailed:
+ pqHandleSendFailure(conn);
+ return 0;
+}
+
/*
* PQsendQueryPrepared
* Like PQsendQuery, but execute a previously prepared statement,
goto sendFailed;
/* remember we are using extended query protocol */
- conn->ext_query = true;
+ conn->queryclass = PGQUERY_EXTENDED;
/*
* Give the data a push. In nonblock mode, don't complain if we're
* The user is responsible for freeing the PGresult via PQclear()
* when done with it.
*/
-
PGresult *
PQexec(PGconn *conn, const char *query)
{
return PQexecFinish(conn);
}
+/*
+ * PQprepare
+ * Creates a prepared statement by issuing a v3.0 parse message.
+ *
+ * If the query was not even sent, return NULL; conn->errorMessage is set to
+ * a relevant message.
+ * If the query was sent, a new PGresult is returned (which could indicate
+ * either success or failure).
+ * The user is responsible for freeing the PGresult via PQclear()
+ * when done with it.
+ */
+PGresult *
+PQprepare(PGconn *conn,
+ const char *stmtName, const char *query,
+ int nParams, const Oid *paramTypes)
+{
+ if (!PQexecStart(conn))
+ return NULL;
+ if (!PQsendPrepare(conn, stmtName, query, nParams, paramTypes))
+ return NULL;
+ return PQexecFinish(conn);
+}
+
/*
* PQexecPrepared
* Like PQexec, but execute a previously prepared statement,
* If we sent the COPY command in extended-query mode, we must
* issue a Sync as well.
*/
- if (conn->ext_query)
+ if (conn->queryclass != PGQUERY_SIMPLE)
{
if (pqPutMsgStart('S', false, conn) < 0 ||
pqPutMsgEnd(conn) < 0)
*
*
* IDENTIFICATION
- * $PostgreSQL: pgsql/src/interfaces/libpq/fe-protocol3.c,v 1.18 2004/10/16 22:52:54 tgl Exp $
+ * $PostgreSQL: pgsql/src/interfaces/libpq/fe-protocol3.c,v 1.19 2004/10/18 22:00:42 tgl Exp $
*
*-------------------------------------------------------------------------
*/
conn->asyncStatus = PGASYNC_READY;
break;
case '1': /* Parse Complete */
+ /* If we're doing PQprepare, we're done; else ignore */
+ if (conn->queryclass == PGQUERY_PREPARE)
+ {
+ if (conn->result == NULL)
+ conn->result = PQmakeEmptyPGresult(conn,
+ PGRES_COMMAND_OK);
+ conn->asyncStatus = PGASYNC_READY;
+ }
+ break;
case '2': /* Bind Complete */
case '3': /* Close Complete */
/* Nothing to do for these message types */
* If we sent the COPY command in extended-query mode, we must
* issue a Sync as well.
*/
- if (conn->ext_query)
+ if (conn->queryclass != PGQUERY_SIMPLE)
{
if (pqPutMsgStart('S', false, conn) < 0 ||
pqPutMsgEnd(conn) < 0)
* Portions Copyright (c) 1996-2004, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
- * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-fe.h,v 1.111 2004/10/16 22:52:55 tgl Exp $
+ * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-fe.h,v 1.112 2004/10/18 22:00:42 tgl Exp $
*
*-------------------------------------------------------------------------
*/
const int *paramLengths,
const int *paramFormats,
int resultFormat);
+extern PGresult *PQprepare(PGconn *conn, const char *stmtName,
+ const char *query, int nParams,
+ const Oid *paramTypes);
extern PGresult *PQexecPrepared(PGconn *conn,
const char *stmtName,
int nParams,
const int *paramLengths,
const int *paramFormats,
int resultFormat);
+extern int PQsendPrepare(PGconn *conn, const char *stmtName,
+ const char *query, int nParams,
+ const Oid *paramTypes);
extern int PQsendQueryPrepared(PGconn *conn,
const char *stmtName,
int nParams,
* Portions Copyright (c) 1996-2004, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
- * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-int.h,v 1.94 2004/10/16 22:52:55 tgl Exp $
+ * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-int.h,v 1.95 2004/10/18 22:00:42 tgl Exp $
*
*-------------------------------------------------------------------------
*/
PGASYNC_COPY_OUT /* Copy Out data transfer in progress */
} PGAsyncStatusType;
+/* PGQueryClass tracks which query protocol we are now executing */
+typedef enum
+{
+ PGQUERY_SIMPLE, /* simple Query protocol (PQexec) */
+ PGQUERY_EXTENDED, /* full Extended protocol (PQexecParams) */
+ PGQUERY_PREPARE /* Parse only (PQprepare) */
+} PGQueryClass;
+
/* PGSetenvStatusType defines the state of the PQSetenv state machine */
/* (this is used only for 2.0-protocol connections) */
typedef enum
PGAsyncStatusType asyncStatus;
PGTransactionStatusType xactStatus;
/* note: xactStatus never changes to ACTIVE */
+ PGQueryClass queryclass;
bool nonblocking; /* whether this connection is using
* nonblock sending semantics */
- bool ext_query; /* was our last query sent with extended
- * query protocol? */
char copy_is_binary; /* 1 = copy binary, 0 = copy text */
int copy_already_done; /* # bytes already returned in
* COPY OUT */
projects / postgresql.git / commitdiff