Home • Explore • Blog • CI
☰



postgresql
48th chunk of `doc/src/sgml/libpq.sgml`
01f72eec8760168a6c5e75ec59026cd61991d9c1be6121be0000000100000fa5
 <para>
            The number of parameters supplied; it is the length of the arrays
            <parameter>paramTypes[]</parameter>, <parameter>paramValues[]</parameter>,
            <parameter>paramLengths[]</parameter>, and <parameter>paramFormats[]</parameter>. (The
            array pointers can be <symbol>NULL</symbol> when <parameter>nParams</parameter>
            is zero.)
           </para>
          </listitem>
         </varlistentry>

         <varlistentry>
          <term><parameter>paramTypes[]</parameter></term>
          <listitem>
           <para>
            Specifies, by OID, the data types to be assigned to the
            parameter symbols.  If <parameter>paramTypes</parameter> is
            <symbol>NULL</symbol>, 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.
           </para>
          </listitem>
         </varlistentry>

         <varlistentry>
          <term><parameter>paramValues[]</parameter></term>
          <listitem>
           <para>
            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).
           </para>
          </listitem>
         </varlistentry>

         <varlistentry>
          <term><parameter>paramLengths[]</parameter></term>
          <listitem>
           <para>
            Specifies the actual data lengths of binary-format parameters.
            It is ignored for null parameters and text-format parameters.
            The array pointer can be null when there are no binary parameters.
           </para>
          </listitem>
         </varlistentry>

         <varlistentry>
          <term><parameter>paramFormats[]</parameter></term>
          <listitem>
           <para>
            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.
           </para>
           <para>
            Values passed in binary format require knowledge of
            the internal representation expected by the backend.
            For example, integers must be passed in network byte
            order.  Passing <type>numeric</type> values requires
            knowledge of the server storage format, as implemented
            in
            <filename>src/backend/utils/adt/numeric.c::numeric_send()</filename> and
            <filename>src/backend/utils/adt/numeric.c::numeric_recv()</filename>.
           </para>
          </listitem>
         </varlistentry>

         <varlistentry>
          <term><parameter>resultFormat</parameter></term>
          <listitem>
           <para>
            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.)
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    The primary advantage of <xref linkend="libpq-PQexecParams"/> over
    <xref linkend="libpq-PQexec"/> is that parameter values can be separated from the
    command string, thus avoiding the need for tedious and error-prone
    quoting and escaping.
   </para>

   <para>
    Unlike <xref linkend="libpq-PQexec"/>, <xref linkend="libpq-PQexecParams"/> allows at most
    one SQL command in the given string.
Title: Detailed Argument Descriptions for PQexecParams Function
Summary
This section details the remaining arguments for the PQexecParams function. It describes paramValues as the actual parameter values (either null pointers or pointers to text strings/binary data), paramLengths as the data lengths of binary-format parameters, paramFormats as the indicator for text (0) or binary (1) format, and resultFormat as the format for the query results (0 for text, 1 for binary). It highlights that binary format requires understanding of the server's internal data representation, such as network byte order for integers. It concludes by mentioning the advantage of PQexecParams over PQexec by allowing parameter values to be separated from the command string, and that PQexecParams only allows one SQL command in the given string.