Improve testlibpq3.c's example of PQexecParams() usage to include sending

a parameter in binary format.  Also, add a TIP explaining how to use casts
in the query text to avoid needing to specify parameter types by OID.
Also fix bogus spacing --- apparently somebody expanded the tabs in the
example programs to 8 spaces instead of 4 when transposing them into SGML.

doc/src/sgml/libpq.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.195 2005/10/20 21:04:14 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.196 2005/10/20 23:57:51 tgl Exp $
 -->
 
  <chapter id="libpq">
@@ -1187,6 +1187,26 @@ than one nonempty command.)  This is a limitation of the underlying protocol,
 but has some usefulness as an extra defense against SQL-injection attacks.
 </para>
 
+<tip>
+<para>
+Specifying parameter types via OIDs is tedious, particularly if you prefer
+not to hard-wire particular OID values into your program.  However, you can
+avoid doing so even in cases where the server by itself cannot determine the
+type of the parameter, or chooses a different type than you want.  In the
+SQL command text, attach an explicit cast to the parameter symbol to show what
+data type you will send.  For example,
+<programlisting>
+select * from mytable where x = $1::bigint;
+</programlisting>
+This forces parameter <literal>$1</> to be treated as <type>bigint</>, whereas
+by default it would be assigned the same type as <literal>x</>.  Forcing the
+parameter type decision, either this way or by specifying a numeric type OID,
+is strongly recommended when sending parameter values in binary format, because
+binary format has less redundancy than text format and so there is less chance
+that the server will detect a type mismatch mistake for you.
+</para>
+</tip>
+
 <para>
 <variablelist>
 <varlistentry>
@@ -4226,7 +4246,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage'
 /*
  * testlibpq.c
  *
- *              Test the C version of LIBPQ, the POSTGRES frontend library.
+ *      Test the C version of libpq, the PostgreSQL frontend library.
  */
 #include &lt;stdio.h&gt;
 #include &lt;stdlib.h&gt;
@@ -4250,10 +4270,9 @@ main(int argc, char **argv)
                 j;
 
     /*
-         * If the user supplies a parameter on the command line, use it as
-         * the conninfo string; otherwise default to setting dbname=postgres
-         * and using environment variables or defaults for all other connection
-         * parameters.
+     * If the user supplies a parameter on the command line, use it as the
+     * conninfo string; otherwise default to setting dbname=postgres and using
+     * environment variables or defaults for all other connection parameters.
      */
     if (argc &gt; 1)
         conninfo = argv[1];
@@ -4272,10 +4291,10 @@ main(int argc, char **argv)
     }
 
     /*
-         * Our test case here involves using a cursor, for which we must be
-         * inside a transaction block.  We could do the whole thing with a
-         * single PQexec() of "select * from pg_database", but that's too
-         * trivial to make a good example.
+     * Our test case here involves using a cursor, for which we must be inside
+     * a transaction block.  We could do the whole thing with a single
+     * PQexec() of "select * from pg_database", but that's too trivial to make
+     * a good example.
      */
 
     /* Start a transaction block */
@@ -4288,8 +4307,8 @@ main(int argc, char **argv)
     }
 
     /*
-         * Should PQclear PGresult whenever it is no longer needed to avoid
-         * memory leaks
+     * Should PQclear PGresult whenever it is no longer needed to avoid memory
+     * leaks
      */
     PQclear(res);
 
@@ -4396,10 +4415,9 @@ main(int argc, char **argv)
     int         nnotifies;
 
     /*
-         * If the user supplies a parameter on the command line, use it as
-         * the conninfo string; otherwise default to setting dbname=postgres
-         * and using environment variables or defaults for all other connection
-         * parameters.
+     * If the user supplies a parameter on the command line, use it as the
+     * conninfo string; otherwise default to setting dbname=postgres and using
+     * environment variables or defaults for all other connection parameters.
      */
     if (argc &gt; 1)
         conninfo = argv[1];
@@ -4429,8 +4447,8 @@ main(int argc, char **argv)
     }
 
     /*
-         * should PQclear PGresult whenever it is no longer needed to avoid
-         * memory leaks
+     * should PQclear PGresult whenever it is no longer needed to avoid memory
+     * leaks
      */
     PQclear(res);
 
@@ -4505,6 +4523,10 @@ main(int argc, char **argv)
  *  t = (11 bytes) 'joe's place'
  *  b = (5 bytes) \000\001\002\003\004
  *
+ * tuple 0: got
+ *  i = (4 bytes) 2
+ *  t = (8 bytes) 'ho there'
+ *  b = (5 bytes) \004\003\002\001\000
  */
 #include &lt;stdio.h&gt;
 #include &lt;stdlib.h&gt;
@@ -4524,6 +4546,66 @@ exit_nicely(PGconn *conn)
     exit(1);
 }
 
+/*
+ * This function prints a query result that is a binary-format fetch from
+ * a table defined as in the comment above.  We split it out because the
+ * main() function uses it twice.
+ */
+static void
+show_binary_results(PGresult *res)
+{
+    int         i,
+                j;
+    int         i_fnum,
+                t_fnum,
+                b_fnum;
+
+    /* Use PQfnumber to avoid assumptions about field order in result */
+    i_fnum = PQfnumber(res, "i");
+    t_fnum = PQfnumber(res, "t");
+    b_fnum = PQfnumber(res, "b");
+
+    for (i = 0; i &lt; PQntuples(res); i++)
+    {
+        char       *iptr;
+        char       *tptr;
+        char       *bptr;
+        int         blen;
+        int         ival;
+
+        /* Get the field values (we ignore possibility they are null!) */
+        iptr = PQgetvalue(res, i, i_fnum);
+        tptr = PQgetvalue(res, i, t_fnum);
+        bptr = PQgetvalue(res, i, b_fnum);
+
+        /*
+         * The binary representation of INT4 is in network byte order, which
+         * we'd better coerce to the local byte order.
+         */
+        ival = ntohl(*((uint32_t *) iptr));
+
+        /*
+         * The binary representation of TEXT is, well, text, and since libpq
+         * was nice enough to append a zero byte to it, it'll work just fine
+         * as a C string.
+         *
+         * The binary representation of BYTEA is a bunch of bytes, which could
+         * include embedded nulls so we have to pay attention to field length.
+         */
+        blen = PQgetlength(res, i, b_fnum);
+
+        printf("tuple %d: got\n", i);
+        printf(" i = (%d bytes) %d\n",
+               PQgetlength(res, i, i_fnum), ival);
+        printf(" t = (%d bytes) '%s'\n",
+               PQgetlength(res, i, t_fnum), tptr);
+        printf(" b = (%d bytes) ", blen);
+        for (j = 0; j &lt; blen; j++)
+            printf("\\%03o", bptr[j]);
+        printf("\n\n");
+    }
+}
+
 int
 main(int argc, char **argv)
 {
@@ -4531,17 +4613,14 @@ main(int argc, char **argv)
     PGconn     *conn;
     PGresult   *res;
     const char *paramValues[1];
-        int                     i,
-                                j;
-        int                     i_fnum,
-                                t_fnum,
-                                b_fnum;
+    int         paramLengths[1];
+    int         paramFormats[1];
+    uint32_t    binaryIntVal;
 
     /*
-         * If the user supplies a parameter on the command line, use it as
-         * the conninfo string; otherwise default to setting dbname=postgres
-         * and using environment variables or defaults for all other connection
-         * parameters.
+     * If the user supplies a parameter on the command line, use it as the
+     * conninfo string; otherwise default to setting dbname=postgres and using
+     * environment variables or defaults for all other connection parameters.
      */
     if (argc &gt; 1)
         conninfo = argv[1];
@@ -4560,12 +4639,14 @@ main(int argc, char **argv)
     }
 
     /*
-         * The point of this program is to illustrate use of PQexecParams()
-         * with out-of-line parameters, as well as binary transmission of
-         * results.  By using out-of-line parameters we can avoid a lot of
-         * tedious mucking about with quoting and escaping.  Notice how we
-         * don't have to do anything special with the quote mark in the
-         * parameter value.
+     * The point of this program is to illustrate use of PQexecParams() with
+     * out-of-line parameters, as well as binary transmission of data.
+     *
+     * This first example transmits the parameters as text, but receives the
+     * results in binary format.  By using out-of-line parameters we can
+     * avoid a lot of tedious mucking about with quoting and escaping, even
+     * though the data is text.  Notice how we don't have to do anything
+     * special with the quote mark in the parameter value.
      */
 
     /* Here is our out-of-line parameter value */
@@ -4587,52 +4668,46 @@ main(int argc, char **argv)
         exit_nicely(conn);
     }
 
-        /* Use PQfnumber to avoid assumptions about field order in result */
-        i_fnum = PQfnumber(res, "i");
-        t_fnum = PQfnumber(res, "t");
-        b_fnum = PQfnumber(res, "b");
+    show_binary_results(res);
 
-        for (i = 0; i &lt; PQntuples(res); i++)
-        {
-                char       *iptr;
-                char       *tptr;
-                char       *bptr;
-                int                     blen;
-                int                     ival;
-
-                /* Get the field values (we ignore possibility they are null!) */
-                iptr = PQgetvalue(res, i, i_fnum);
-                tptr = PQgetvalue(res, i, t_fnum);
-                bptr = PQgetvalue(res, i, b_fnum);
-
-                /*
-                 * The binary representation of INT4 is in network byte order,
-                 * which we'd better coerce to the local byte order.
-                 */
-                ival = ntohl(*((uint32_t *) iptr));
+    PQclear(res);
 
     /*
-                 * The binary representation of TEXT is, well, text, and since
-                 * libpq was nice enough to append a zero byte to it, it'll work
-                 * just fine as a C string.
+     * In this second example we transmit an integer parameter in binary
+     * form, and again retrieve the results in binary form.
      *
-                 * The binary representation of BYTEA is a bunch of bytes, which
-                 * could include embedded nulls so we have to pay attention to
-                 * field length.
+     * Although we tell PQexecParams we are letting the backend deduce
+     * parameter type, we really force the decision by casting the parameter
+     * symbol in the query text.  This is a good safety measure when sending
+     * binary parameters.
      */
-                blen = PQgetlength(res, i, b_fnum);
 
-                printf("tuple %d: got\n", i);
-                printf(" i = (%d bytes) %d\n",
-                           PQgetlength(res, i, i_fnum), ival);
-                printf(" t = (%d bytes) '%s'\n",
-                           PQgetlength(res, i, t_fnum), tptr);
-                printf(" b = (%d bytes) ", blen);
-                for (j = 0; j &lt; blen; j++)
-                        printf("\\%03o", bptr[j]);
-                printf("\n\n");
+    /* Convert integer value "2" to network byte order */
+    binaryIntVal = htonl((uint32_t) 2);
+
+    /* Set up parameter arrays for PQexecParams */
+    paramValues[0] = (char *) &amp;binaryIntVal;
+    paramLengths[0] = sizeof(binaryIntVal);
+    paramFormats[0] = 1;        /* binary */
+
+    res = PQexecParams(conn,
+                       "SELECT * FROM test1 WHERE i = $1::int4",
+                       1,       /* one param */
+                       NULL,    /* let the backend deduce param type */
+                       paramValues,
+                       paramLengths,
+                       paramFormats,
+                       1);      /* ask for binary results */
+
+    if (PQresultStatus(res) != PGRES_TUPLES_OK)
+    {
+        fprintf(stderr, "SELECT failed: %s", PQerrorMessage(conn));
+        PQclear(res);
+        exit_nicely(conn);
     }
 
+    show_binary_results(res);
+
     PQclear(res);
 
     /* close the connection to the database and cleanup */

src/test/examples/testlibpq3.c

@@ -17,6 +17,10 @@
  *	t = (11 bytes) 'joe's place'
  *	b = (5 bytes) \000\001\002\003\004
  *
+ * tuple 0: got
+ *  i = (4 bytes) 2
+ *  t = (8 bytes) 'ho there'
+ *  b = (5 bytes) \004\003\002\001\000
  */
 #include <stdio.h>
 #include <stdlib.h>
@@ -36,6 +40,66 @@ exit_nicely(PGconn *conn)
 	exit(1);
 }
 
+/*
+ * This function prints a query result that is a binary-format fetch from
+ * a table defined as in the comment above.  We split it out because the
+ * main() function uses it twice.
+ */
+static void
+show_binary_results(PGresult *res)
+{
+	int			i,
+				j;
+	int			i_fnum,
+				t_fnum,
+				b_fnum;
+
+	/* Use PQfnumber to avoid assumptions about field order in result */
+	i_fnum = PQfnumber(res, "i");
+	t_fnum = PQfnumber(res, "t");
+	b_fnum = PQfnumber(res, "b");
+
+	for (i = 0; i < PQntuples(res); i++)
+	{
+		char	   *iptr;
+		char	   *tptr;
+		char	   *bptr;
+		int			blen;
+		int			ival;
+
+		/* Get the field values (we ignore possibility they are null!) */
+		iptr = PQgetvalue(res, i, i_fnum);
+		tptr = PQgetvalue(res, i, t_fnum);
+		bptr = PQgetvalue(res, i, b_fnum);
+
+		/*
+		 * The binary representation of INT4 is in network byte order, which
+		 * we'd better coerce to the local byte order.
+		 */
+		ival = ntohl(*((uint32_t *) iptr));
+
+		/*
+		 * The binary representation of TEXT is, well, text, and since libpq
+		 * was nice enough to append a zero byte to it, it'll work just fine
+		 * as a C string.
+		 *
+		 * The binary representation of BYTEA is a bunch of bytes, which could
+		 * include embedded nulls so we have to pay attention to field length.
+		 */
+		blen = PQgetlength(res, i, b_fnum);
+
+		printf("tuple %d: got\n", i);
+		printf(" i = (%d bytes) %d\n",
+			   PQgetlength(res, i, i_fnum), ival);
+		printf(" t = (%d bytes) '%s'\n",
+			   PQgetlength(res, i, t_fnum), tptr);
+		printf(" b = (%d bytes) ", blen);
+		for (j = 0; j < blen; j++)
+			printf("\\%03o", bptr[j]);
+		printf("\n\n");
+	}
+}
+
 int
 main(int argc, char **argv)
 {
@@ -43,11 +107,9 @@ main(int argc, char **argv)
 	PGconn	   *conn;
 	PGresult   *res;
 	const char *paramValues[1];
-	int			i,
-				j;
-	int			i_fnum,
-				t_fnum,
-				b_fnum;
+	int			paramLengths[1];
+	int			paramFormats[1];
+	uint32_t	binaryIntVal;
 
 	/*
 	 * If the user supplies a parameter on the command line, use it as the
@@ -72,10 +134,13 @@ main(int argc, char **argv)
 
 	/*
 	 * The point of this program is to illustrate use of PQexecParams() with
-	 * out-of-line parameters, as well as binary transmission of results.  By
-	 * using out-of-line parameters we can avoid a lot of tedious mucking
-	 * about with quoting and escaping.  Notice how we don't have to do
-	 * anything special with the quote mark in the parameter value.
+	 * out-of-line parameters, as well as binary transmission of data.
+	 *
+	 * This first example transmits the parameters as text, but receives the
+	 * results in binary format.  By using out-of-line parameters we can
+	 * avoid a lot of tedious mucking about with quoting and escaping, even
+	 * though the data is text.  Notice how we don't have to do anything
+	 * special with the quote mark in the parameter value.
 	 */
 
 	/* Here is our out-of-line parameter value */
@@ -97,51 +162,46 @@ main(int argc, char **argv)
 		exit_nicely(conn);
 	}
 
-	/* Use PQfnumber to avoid assumptions about field order in result */
-	i_fnum = PQfnumber(res, "i");
-	t_fnum = PQfnumber(res, "t");
-	b_fnum = PQfnumber(res, "b");
+	show_binary_results(res);
 
-	for (i = 0; i < PQntuples(res); i++)
-	{
-		char	   *iptr;
-		char	   *tptr;
-		char	   *bptr;
-		int			blen;
-		int			ival;
-
-		/* Get the field values (we ignore possibility they are null!) */
-		iptr = PQgetvalue(res, i, i_fnum);
-		tptr = PQgetvalue(res, i, t_fnum);
-		bptr = PQgetvalue(res, i, b_fnum);
-
-		/*
-		 * The binary representation of INT4 is in network byte order, which
-		 * we'd better coerce to the local byte order.
-		 */
-		ival = ntohl(*((uint32_t *) iptr));
+	PQclear(res);
 
 	/*
-		 * The binary representation of TEXT is, well, text, and since libpq
-		 * was nice enough to append a zero byte to it, it'll work just fine
-		 * as a C string.
+	 * In this second example we transmit an integer parameter in binary
+	 * form, and again retrieve the results in binary form.
 	 *
-		 * The binary representation of BYTEA is a bunch of bytes, which could
-		 * include embedded nulls so we have to pay attention to field length.
+	 * Although we tell PQexecParams we are letting the backend deduce
+	 * parameter type, we really force the decision by casting the parameter
+	 * symbol in the query text.  This is a good safety measure when sending
+	 * binary parameters.
 	 */
-		blen = PQgetlength(res, i, b_fnum);
 
-		printf("tuple %d: got\n", i);
-		printf(" i = (%d bytes) %d\n",
-			   PQgetlength(res, i, i_fnum), ival);
-		printf(" t = (%d bytes) '%s'\n",
-			   PQgetlength(res, i, t_fnum), tptr);
-		printf(" b = (%d bytes) ", blen);
-		for (j = 0; j < blen; j++)
-			printf("\\%03o", bptr[j]);
-		printf("\n\n");
+	/* Convert integer value "2" to network byte order */
+	binaryIntVal = htonl((uint32_t) 2);
+
+	/* Set up parameter arrays for PQexecParams */
+	paramValues[0] = (char *) &binaryIntVal;
+	paramLengths[0] = sizeof(binaryIntVal);
+	paramFormats[0] = 1;		/* binary */
+
+	res = PQexecParams(conn,
+					   "SELECT * FROM test1 WHERE i = $1::int4",
+					   1,		/* one param */
+					   NULL,	/* let the backend deduce param type */
+					   paramValues,
+					   paramLengths,
+					   paramFormats,
+					   1);		/* ask for binary results */
+
+	if (PQresultStatus(res) != PGRES_TUPLES_OK)
+	{
+		fprintf(stderr, "SELECT failed: %s", PQerrorMessage(conn));
+		PQclear(res);
+		exit_nicely(conn);
 	}
 
+	show_binary_results(res);
+
 	PQclear(res);
 
 	/* close the connection to the database and cleanup */