From: Tom Lane Date: Fri, 10 Nov 2006 22:15:26 +0000 (+0000) Subject: Improve formatting of PQexecParams argument descriptions, per X-Git-Tag: REL9_0_0~6728 X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=1456c5b5073b40fcbcb8737fbb80fd6e42188e91;p=pg-rex%2Fsyncrep.git Improve formatting of PQexecParams argument descriptions, per Theo Kramer. --- diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index f648843689..40d0bcb1fb 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,4 +1,4 @@ - + <application>libpq</application> - C Library @@ -956,7 +956,7 @@ Applications may use this to determine the version of the database server they are connected to. The number is formed by converting the major, minor, and revision numbers into two-decimal-digit numbers and appending them together. For example, version 8.1.5 will be returned as 80105, and version -8.1 will be returned as 80100 (leading zeroes are not shown). Zero is +8.2 will be returned as 80200 (leading zeroes are not shown). Zero is returned if the connection is bad. @@ -1138,41 +1138,116 @@ connections; it will fail when using protocol 2.0. -If parameters are used, they are referred to in the command string -as $1, $2, etc. -nParams is the number of parameters supplied; it is the length -of the arrays paramTypes[], paramValues[], -paramLengths[], and paramFormats[]. (The -array pointers 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. -paramValues[] specifies the actual values of the parameters. -A null pointer in this array means the corresponding parameter is null; -otherwise the pointer points to a zero-terminated text string (for text -format) or binary data in the format expected by the server (for binary -format). -paramLengths[] specifies the actual data lengths of -binary-format parameters. It is ignored for null parameters and text-format -parameters. The array pointer may be null when there are no binary -parameters. -paramFormats[] specifies whether parameters are text (put a zero -in the array) or binary (put a one in the array). If the array pointer is -null then all parameters are presumed to be text. -resultFormat is zero to obtain results in text format, or one to -obtain results in binary format. (There is not currently a provision to -obtain different result columns in different formats, although that is -possible in the underlying protocol.) +The function arguments are: + + + + conn + + + The connection object to send the command through. + + + + + + command + + + The SQL command string to be executed. If parameters are used, they are + referred to in the command string as $1, $2, + etc. + + + + + + nParams + + + The number of parameters supplied; it is the length of the arrays + paramTypes[], paramValues[], + paramLengths[], and paramFormats[]. (The + array pointers 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 infers a data type + for the parameter symbol in the same way it would do for an untyped + literal string. + + + + + + paramValues[] + + + Specifies the actual values of the parameters. + A null pointer in this array means the corresponding parameter is null; + otherwise the pointer points to a zero-terminated text string (for text + format) or binary data in the format expected by the server (for binary + format). + + + + + + paramLengths[] + + + Specifies the actual data lengths of binary-format parameters. + It is ignored for null parameters and text-format parameters. + The array pointer may be null when there are no binary parameters. + + + + + + paramFormats[] + + + Specifies whether parameters are text (put a zero in the array entry for + the corresponding parameter) or binary (put a one in the array entry for + the corresponding parameter). If the array pointer is null then all + parameters are presumed to be text strings. + + + + + + resultFormat + + + Specify zero to obtain results in text format, or one to obtain results + in binary format. (There is not currently a provision to obtain + different result columns in different formats, although that is + possible in the underlying protocol.) + + + + + + The primary advantage of PQexecParams over PQexec is that parameter values may be separated from the command string, thus avoiding the need for tedious and error-prone quoting and escaping. + + Unlike PQexec, PQexecParams allows at most one SQL command in the given string. (There can be semicolons in it, but not more than one nonempty command.) This is a limitation of the underlying protocol,