Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 1456c5b

Browse files
tglsfdctglsfdc
committed
Improve formatting of PQexecParams argument descriptions, per
Theo Kramer.
1 parent 2c2faa1 commit 1456c5b

File tree

1 file changed

+103
-28
lines changed

1 file changed

+103
-28
lines changed

‎doc/src/sgml/libpq.sgml

Lines changed: 103 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.219 2006/10/23 18:10:31 petere Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.220 2006/11/10 22:15:26 tgl Exp $ -->
22

33
<chapter id="libpq">
44
<title><application>libpq</application> - C Library</title>
@@ -956,7 +956,7 @@ Applications may use this to determine the version of the database server they
956956
are connected to. The number is formed by converting the major, minor, and
957957
revision numbers into two-decimal-digit numbers and appending them
958958
together. For example, version 8.1.5 will be returned as 80105, and version
959-
8.1 will be returned as 80100 (leading zeroes are not shown). Zero is
959+
8.2 will be returned as 80200 (leading zeroes are not shown). Zero is
960960
returned if the connection is bad.
961961
</para>
962962
</listitem>
@@ -1138,41 +1138,116 @@ connections; it will fail when using protocol 2.0.
11381138
</para>
11391139

11401140
<para>
1141-
If parameters are used, they are referred to in the command string
1142-
as <literal>$1</>, <literal>$2</>, etc.
1143-
<parameter>nParams</> is the number of parameters supplied; it is the length
1144-
of the arrays <parameter>paramTypes[]</>, <parameter>paramValues[]</>,
1145-
<parameter>paramLengths[]</>, and <parameter>paramFormats[]</>. (The
1146-
array pointers may be <symbol>NULL</symbol> when <parameter>nParams</> is zero.)
1147-
<parameter>paramTypes[]</> specifies, by OID, the data types to be assigned to
1148-
the parameter symbols. If <parameter>paramTypes</> is <symbol>NULL</symbol>, or any particular
1149-
element in the array is zero, the server assigns a data type to the parameter
1150-
symbol in the same way it would do for an untyped literal string.
1151-
<parameter>paramValues[]</> specifies the actual values of the parameters.
1152-
A null pointer in this array means the corresponding parameter is null;
1153-
otherwise the pointer points to a zero-terminated text string (for text
1154-
format) or binary data in the format expected by the server (for binary
1155-
format).
1156-
<parameter>paramLengths[]</> specifies the actual data lengths of
1157-
binary-format parameters. It is ignored for null parameters and text-format
1158-
parameters. The array pointer may be null when there are no binary
1159-
parameters.
1160-
<parameter>paramFormats[]</> specifies whether parameters are text (put a zero
1161-
in the array) or binary (put a one in the array). If the array pointer is
1162-
null then all parameters are presumed to be text.
1163-
<parameter>resultFormat</> is zero to obtain results in text format, or one to
1164-
obtain results in binary format. (There is not currently a provision to
1165-
obtain different result columns in different formats, although that is
1166-
possible in the underlying protocol.)
1141+
The function arguments are:
1142+
1143+
<variablelist>
1144+
<varlistentry>
1145+
<term><parameter>conn</parameter></term>
1146+
<listitem>
1147+
<para>
1148+
The connection object to send the command through.
1149+
</para>
1150+
</listitem>
1151+
</varlistentry>
1152+
1153+
<varlistentry>
1154+
<term><parameter>command</parameter></term>
1155+
<listitem>
1156+
<para>
1157+
The SQL command string to be executed. If parameters are used, they are
1158+
referred to in the command string as <literal>$1</>, <literal>$2</>,
1159+
etc.
1160+
</para>
1161+
</listitem>
1162+
</varlistentry>
1163+
1164+
<varlistentry>
1165+
<term><parameter>nParams</parameter></term>
1166+
<listitem>
1167+
<para>
1168+
The number of parameters supplied; it is the length of the arrays
1169+
<parameter>paramTypes[]</>, <parameter>paramValues[]</>,
1170+
<parameter>paramLengths[]</>, and <parameter>paramFormats[]</>. (The
1171+
array pointers may be <symbol>NULL</symbol> when <parameter>nParams</>
1172+
is zero.)
1173+
</para>
1174+
</listitem>
1175+
</varlistentry>
1176+
1177+
<varlistentry>
1178+
<term><parameter>paramTypes[]</parameter></term>
1179+
<listitem>
1180+
<para>
1181+
Specifies, by OID, the data types to be assigned to the parameter
1182+
symbols. If <parameter>paramTypes</> is <symbol>NULL</symbol>, or any
1183+
particular element in the array is zero, the server infers a data type
1184+
for the parameter symbol in the same way it would do for an untyped
1185+
literal string.
1186+
</para>
1187+
</listitem>
1188+
</varlistentry>
1189+
1190+
<varlistentry>
1191+
<term><parameter>paramValues[]</parameter></term>
1192+
<listitem>
1193+
<para>
1194+
Specifies the actual values of the parameters.
1195+
A null pointer in this array means the corresponding parameter is null;
1196+
otherwise the pointer points to a zero-terminated text string (for text
1197+
format) or binary data in the format expected by the server (for binary
1198+
format).
1199+
</para>
1200+
</listitem>
1201+
</varlistentry>
1202+
1203+
<varlistentry>
1204+
<term><parameter>paramLengths[]</parameter></term>
1205+
<listitem>
1206+
<para>
1207+
Specifies the actual data lengths of binary-format parameters.
1208+
It is ignored for null parameters and text-format parameters.
1209+
The array pointer may be null when there are no binary parameters.
1210+
</para>
1211+
</listitem>
1212+
</varlistentry>
1213+
1214+
<varlistentry>
1215+
<term><parameter>paramFormats[]</parameter></term>
1216+
<listitem>
1217+
<para>
1218+
Specifies whether parameters are text (put a zero in the array entry for
1219+
the corresponding parameter) or binary (put a one in the array entry for
1220+
the corresponding parameter). If the array pointer is null then all
1221+
parameters are presumed to be text strings.
1222+
</para>
1223+
</listitem>
1224+
</varlistentry>
1225+
1226+
<varlistentry>
1227+
<term><parameter>resultFormat</parameter></term>
1228+
<listitem>
1229+
<para>
1230+
Specify zero to obtain results in text format, or one to obtain results
1231+
in binary format. (There is not currently a provision to obtain
1232+
different result columns in different formats, although that is
1233+
possible in the underlying protocol.)
1234+
</para>
1235+
</listitem>
1236+
</varlistentry>
1237+
</variablelist>
11671238
</para>
11681239
</listitem>
11691240
</varlistentry>
11701241
</variablelist>
1242+
</para>
11711243

1244+
<para>
11721245
The primary advantage of <function>PQexecParams</> over <function>PQexec</>
11731246
is that parameter values may be separated from the command string, thus
11741247
avoiding the need for tedious and error-prone quoting and escaping.
1248+
</para>
11751249

1250+
<para>
11761251
Unlike <function>PQexec</>, <function>PQexecParams</> allows at most one SQL
11771252
command in the given string. (There can be semicolons in it, but not more
11781253
than one nonempty command.) This is a limitation of the underlying protocol,

0 commit comments

Comments
 (0)