Re: [PATCH] pgsql.xml

From: Date: Sun, 09 Dec 2001 22:45:21 +0000
Subject: Re: [PATCH] pgsql.xml
References: 1  Groups: php.doc 
Request: Send a blank email to phpdoc+get-969339640@lists.php.net to get a copy of this message
I got no feedbacks except from Markus. (I'll get rid of pg_loread() fix, since it's already fixed by Jim) I take it as no objection :) Please notify to if you object this patch. -- Yasuo Ohgaki Yasuo Ohgaki wrote:
Attached file is patch for pgsql.xml Changes: - Proto fix so that resource is used 
        Other modules are using resource for proto, I assumed it's
        ok to changed them. If I'm not suppose to do that, please
        let me know.
- pg_loexport() proto fix. 
        Second param is filename(string - it may include path)
        instead of int.
- pg_end_copy() proto fix. 
        It returns bool, not void. (Is this ok to change?)
- pg_getlastoid() may return FALSE. - pg_loclose() may return FALSE. Issues left: - pg_exec()'s first param is optinal, but proto is not. I would like to users to use connection resource always, so it may not need to change... Since this is first patch for phpdoc, I ask to list first. I build and verified html version. Please let me know if there is problem of if you want me to commit. ------------------------------------------------------------------------ Index: pgsql.xml =================================================================== RCS file: /repository/phpdoc/en/functions/pgsql.xml,v retrieving revision 1.50 diff -u -r1.50 pgsql.xml --- pgsql.xml 7 Dec 2001 21:32:40 -0000 1.50 +++ pgsql.xml 8 Dec 2001 02:19:28 -0000 @@ -117,13 +117,13 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>bool <function>pg_close</function></funcdef>
-      <paramdef>int <parameter>connection</parameter></paramdef>
+      <paramdef>resource <parameter>connection</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
-     Returns &false; if connection is not a valid connection index, &true;
+     Returns &false; if connection is not a valid connection resource, &true;
      otherwise.  Closes down the connection to a PostgreSQL database
-     associated with the given connection index.
+     associated with the given connection resource.
     </para>
     <note><para>       This isn't usually necessary, as non-persistent open
@@ -147,7 +147,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_cmdtuples</function></funcdef>
-      <paramdef>int <parameter>result_id</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
@@ -183,20 +183,20 @@ 
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>pg_connect</function></funcdef>
+      <funcdef>resource <function>pg_connect</function></funcdef>
       <paramdef>string <parameter>host</parameter></paramdef>
       <paramdef>string <parameter>port</parameter></paramdef>
       <paramdef>string <parameter>dbname</parameter></paramdef>
      </funcprototype>
      <funcprototype>
-      <funcdef>int <function>pg_connect</function></funcdef>
+      <funcdef>resource <function>pg_connect</function></funcdef>
       <paramdef>string <parameter>host</parameter></paramdef>
       <paramdef>string <parameter>port</parameter></paramdef>
       <paramdef>string <parameter>options</parameter></paramdef>
       <paramdef>string <parameter>dbname</parameter></paramdef>
      </funcprototype>
      <funcprototype>
-      <funcdef>int <function>pg_connect</function></funcdef>
+      <funcdef>resource <function>pg_connect</function></funcdef>
       <paramdef>string <parameter>host</parameter></paramdef>
       <paramdef>string <parameter>port</parameter></paramdef>
       <paramdef>string <parameter>options</parameter></paramdef>
@@ -204,14 +204,14 @@ 
       <paramdef>string <parameter>dbname</parameter></paramdef>
      </funcprototype>
      <funcprototype>
-      <funcdef>int <function>pg_connect</function></funcdef>
+      <funcdef>resource <function>pg_connect</function></funcdef>
       <paramdef>string <parameter>conn_string</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
-     Returns a connection index on success, or &false; if the connection
-     could not be made.  Opens a connection to a PostgreSQL database.
-     The arguments should be within a quoted string.
+     Returns a connection resource on success, or &false; if the
+     connection could not be made.  Opens a connection to a PostgreSQL
+     database.  The arguments should be within a quoted string.
      <example>
      <title>Using pg_connect arguments</title>
      <programlisting role="php">
@@ -235,11 +235,11 @@ 
     <para>
      If a second call is made to <function>pg_connect</function> with
      the same arguments, no new connection will be established, but
-     instead, the connection index of the already opened connection
+     instead, the connection resource of the already opened connection
      will be returned.
     </para>
     <para>
-     This function returns a connection index that is needed by other
+     This function returns a connection resource that is needed by other
      PostgreSQL functions. You can have multiple connections open at
      once.
     </para>
@@ -266,13 +266,13 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>pg_dbname</function></funcdef>
-      <paramdef>int <parameter>connection</parameter></paramdef>
+      <paramdef>resource <parameter>connection</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      Returns the name of the database that the given PostgreSQL
-     connection index is connected to, or &false; if connection is not a
-     valid connection index.
+     connection resource is connected to, or &false; if connection is not a
+     valid connection resource.
     </para>
    </refsect1>
</refentry> @@ -315,7 +315,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>pg_errormessage</function></funcdef>
-      <paramdef>int <parameter>connection</parameter></paramdef>
+      <paramdef>resource <parameter>connection</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
@@ -338,21 +338,21 @@ 
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>pg_exec</function></funcdef>
-      <paramdef>int <parameter>connection</parameter></paramdef>
+      <funcdef>resource <function>pg_exec</function></funcdef>
+      <paramdef>resource<parameter>connection</parameter></paramdef>
       <paramdef>string <parameter>query</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
-     Returns a result index if query could be executed, &false; on
-     failure or if connection is not a valid connection index. Details
-     about the error can be retrieved using the
+     Returns a query result resource if query could be executed,
+     &false; on failure or if connection is not a valid connection
+     index. Details about the error can be retrieved using the
      <function>pg_ErrorMessage</function> function if connection is
      valid.  Sends an SQL statement to the PostgreSQL database
      specified by the connection index. The connection must be a valid
      index that was returned by <function>pg_Connect</function>.  The
      return value of this function is an index to be used to access
-     the results from other PostgreSQL functions.  +     the results from other PostgreSQL functions.
      <note>
       <simpara>
        PHP/FI returned 1 if the query was not expected to return data
@@ -375,7 +375,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>array <function>pg_fetch_array</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>row</parameter></paramdef>
       <paramdef>int         <parameter><optional>result_type</optional></parameter>
@@ -451,7 +451,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>object <function>pg_fetch_object</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>row</parameter></paramdef>
       <paramdef>int         <parameter><optional>result_type</optional></parameter>
@@ -546,7 +546,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>array <function>pg_fetch_row</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>row</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -612,7 +612,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_fieldisnull</function></funcdef>
-      <paramdef>int <parameter>result_id</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>row</parameter></paramdef>
       <paramdef>mixed <parameter>field</parameter></paramdef>
      </funcprototype>
@@ -636,7 +636,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>pg_fieldname</function></funcdef>
-      <paramdef>int <parameter>result_id</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>field_number</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -658,7 +658,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_fieldnum</function></funcdef>
-      <paramdef>int <parameter>result_id</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>string <parameter>field_name</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -681,7 +681,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_fieldprtlen</function></funcdef>
-      <paramdef>int <parameter>result_id</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>row_number</parameter></paramdef>
       <paramdef>string <parameter>field_name</parameter></paramdef>
      </funcprototype>
@@ -707,7 +707,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_fieldsize</function></funcdef>
-      <paramdef>int <parameter>result_id</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>field_number</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -733,7 +733,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>pg_fieldtype</function></funcdef>
-      <paramdef>int <parameter>result_id</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>field_number</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -754,8 +754,8 @@ 
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>pg_freeresult</function></funcdef>
-      <paramdef>int <parameter>result_id</parameter></paramdef>
+      <funcdef>bool <function>pg_freeresult</function></funcdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
@@ -780,16 +780,17 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_getlastoid</function></funcdef>
-      <paramdef>int <parameter>result_id</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      <function>pg_getlastoid</function> can be used to retrieve the
-     <varname>oid</varname> assigned to an inserted tuple if the result
-     identifier is used from the last command sent via
-     <function>pg_exec</function> and was an SQL INSERT.  Returns a positive
-     integer if there was a valid <varname>oid</varname>.  It returns &false;
-     if an error occurs or the last command sent via
+     <varname>oid</varname> assigned to an inserted tuple if the
+     result identifier is used from the last command sent via
+     <function>pg_exec</function> and was an SQL INSERT.  This
+     function will return a positive integer greater than 0 if there
+     was a valid <varname>oid</varname>.  It will return &false; or -1
+     if an error occured or the last command sent via
      <function>pg_exec</function> was not an INSERT.
     </para>
    </refsect1>
@@ -807,7 +808,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>pg_host</function></funcdef>
-      <paramdef>int <parameter>connection_id</parameter></paramdef>
+      <paramdef>resource <parameter>connection</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
@@ -826,13 +827,13 @@ 
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>void <function>pg_loclose</function></funcdef>
-      <paramdef>int <parameter>fd</parameter></paramdef>
+      <funcdef>bool <function>pg_loclose</function></funcdef>
+      <paramdef>resource <parameter>large_object</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      <function>pg_loclose</function> closes an Inversion Large
-     Object. <parameter>Fd</parameter> is a file descriptor for the
+     Object. <parameter>large_object</parameter> is a resource for the
      large object from <function>pg_loopen</function>.
     </para>
    </refsect1>
@@ -848,13 +849,13 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_locreate</function></funcdef>
-      <paramdef>int <parameter>conn</parameter></paramdef>
+      <paramdef>resource <parameter>connection</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      <function>pg_locreate</function> creates an Inversion Large
      Object and returns the <varname>oid</varname> of the large
-     object.  <parameter>conn</parameter> specifies a valid database
+     object.  <parameter>connection</parameter> specifies a valid database
      connection.  PostgreSQL access modes INV_READ, INV_WRITE, and
      INV_ARCHIVE are not supported, the object is created always with
      both read and write access. INV_ARCHIVE has been removed from
@@ -876,11 +877,11 @@ 
       <paramdef>int
        <parameter>oid</parameter>
       </paramdef>
-      <paramdef>int
-       <parameter>file</parameter>
+      <paramdef>string
+       <parameter>filename</parameter>
       </paramdef>
-      <paramdef>int
-       <parameter><optional>connection_id</optional></parameter>
+      <paramdef>resource
+       <parameter><optional>connection</optional></parameter>
       </paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -905,8 +906,8 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_loimport</function></funcdef>
-      <paramdef>int
-       <parameter>file</parameter>
+      <paramdef>string
+       <parameter>filename</parameter>
       </paramdef>
       <paramdef>int
        <parameter><optional>connection_id</optional></parameter>
@@ -933,8 +934,8 @@ 
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>pg_loopen</function></funcdef>
-      <paramdef>int <parameter>conn</parameter></paramdef>
+      <funcdef>bool <function>pg_loopen</function></funcdef>
+      <paramdef>resource <parameter>connection</parameter></paramdef>
       <paramdef>int <parameter>objoid</parameter></paramdef>
       <paramdef>string <parameter>mode</parameter></paramdef>
      </funcprototype>
@@ -945,7 +946,8 @@ 
      encapsulates information about the connection. Do not close the
      connection before closing the large object file descriptor.
      <parameter>objoid</parameter> specifies a valid large object oid
-     and <parameter>mode</parameter> can be either "r", "w", or "rw".
+     and <parameter>mode</parameter> can be either "r", "w", or
+     "rw". It returns &false; if there is error.
     </para>
    </refsect1>
</refentry> @@ -960,17 +962,16 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>pg_loread</function></funcdef>
-      <paramdef>int <parameter>fd</parameter></paramdef>
+      <paramdef>resource <parameter>large_object</parameter></paramdef>
       <paramdef>int <parameter>len</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      <function>pg_loread</function> reads at most
-     <parameter>len</parameter> bytes from a large object and
-     returns it as a string.
-     <parameter>fd</parameter> specifies a valid large object file
-     descriptor and<parameter>len</parameter> specifies the maximum
-     allowable size of the large object segment.
+     <parameter>len</parameter> bytes from a large object and returns
+     it as a string.  <parameter>large_object</parameter> specifies a
+     valid large object resource and<parameter>len</parameter>
+     specifies the maximum allowable size of the large object segment.
     </para>
    </refsect1>
</refentry> @@ -987,7 +988,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>void <function>pg_loreadall</function></funcdef>
-      <paramdef>int <parameter>fd</parameter></paramdef>
+      <paramdef>resource <parameter>large_object</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
@@ -1008,13 +1009,13 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>void <function>pg_lounlink</function></funcdef>
-      <paramdef>int <parameter>conn</parameter></paramdef>
-      <paramdef>int <parameter>lobjid</parameter></paramdef>
+      <paramdef>resource <parameter>connection</parameter></paramdef>
+      <paramdef>resource <parameter>large_object</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      <function>pg_lounlink</function> deletes a large object with the
-     <parameter>lobjid</parameter> identifier for that large object.
+     <parameter>large_object</parameter> identifier for that large object.
     </para>
    </refsect1>
</refentry> @@ -1029,7 +1030,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_lowrite</function></funcdef>
-      <paramdef>int <parameter>fd</parameter></paramdef>
+      <paramdef>resource <parameter>large_object</parameter></paramdef>
       <paramdef>string <parameter>buf</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -1037,8 +1038,9 @@ 
      <function>pg_lowrite</function> writes at most to a large object
      from a variable <parameter>buf</parameter> and returns the number
      of bytes actually written, or &false; in the case of an error.
-     <parameter>fd</parameter> is a file descriptor for the large
-     object from <function>pg_loopen</function>.
+     <parameter>large_object</parameter> is a large object resource
+     from <function>pg_loopen</function>. It returns &false; if there
+     is error.
     </para>
    </refsect1>
</refentry> @@ -1053,7 +1055,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_numfields</function></funcdef>
-      <paramdef>int <parameter>result_id</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
@@ -1079,7 +1081,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_numrows</function></funcdef>
-      <paramdef>int <parameter>result_id</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
@@ -1105,7 +1107,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>pg_options</function></funcdef>
-      <paramdef>int <parameter>connection_id</parameter></paramdef>
+      <paramdef>resource <parameter>connection</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
@@ -1130,18 +1132,18 @@ 
      </funcprototype>
     </funcsynopsis>
     <para>
-     Returns a connection index on success, or &false; if the connection
-     could not be made.  Opens a connection to a PostgreSQL database.
-     The arguments should be within a quoted string.
-     The arguments available include <parameter>host</parameter>,
+     Returns a connection resource on success, or &false; if the
+     connection could not be made.  Opens a connection to a PostgreSQL
+     database.  The arguments should be within a quoted string.  The
+     arguments available include <parameter>host</parameter>,
      <parameter>port</parameter>, <parameter>tty</parameter>,
      <parameter>options</parameter>, <parameter>dbname</parameter>,
      <parameter>user</parameter>, and <parameter>password</parameter>.
     </para>
     <para>
-     This function returns a connection index that is needed by other
-     PostgreSQL functions. You can have multiple connections open at
-     once.
+     This function returns a connection resource that is needed by
+     other PostgreSQL functions. You can have multiple connections
+     open at once.
     </para>
     <para>
      The previous syntax of:
@@ -1168,12 +1170,12 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_port</function></funcdef>
-      <paramdef>int <parameter>connection_id</parameter></paramdef>
+      <paramdef>resource <parameter>connection</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      <function>pg_port</function> will return the port number that the
-     given PostgreSQL connection identifier is connected to.
+     given PostgreSQL connection resource is connected to.
     </para>
    </refsect1>
</refentry> @@ -1189,7 +1191,7 @@ 
      <funcprototype>
       <funcdef>bool <function>pg_put_line</function></funcdef>
       <paramdef>resource
-       <parameter><optional>connection_id</optional></parameter>
+       <parameter><optional>connection</optional></parameter>
       </paramdef>
       <paramdef>string <parameter>data</parameter></paramdef>
      </funcprototype>
@@ -1241,7 +1243,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>mixed <function>pg_result</function></funcdef>
-      <paramdef>int <parameter>result_id</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>row_number</parameter></paramdef>
       <paramdef>mixed <parameter>fieldname</parameter></paramdef>
      </funcprototype>
@@ -1282,7 +1284,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>pg_set_client_encoding</function></funcdef>
-      <paramdef>int +      <paramdef>resource         <parameter><optional>connection</optional></parameter>
       </paramdef>
       <paramdef>string <parameter>encoding</parameter></paramdef>
@@ -1327,7 +1329,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>pg_client_encoding</function></funcdef>
-      <paramdef>int +      <paramdef>resource         <parameter><optional>connection</optional></parameter>
       </paramdef>
      </funcprototype>
@@ -1371,7 +1373,7 @@ 
       <paramdef>string
        <parameter><optional>mode</optional></parameter>
       </paramdef>
-      <paramdef>int
+      <paramdef>resource
        <parameter><optional>connection</optional></parameter>
       </paramdef>
      </funcprototype>
@@ -1415,13 +1417,13 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>pg_tty</function></funcdef>
-      <paramdef>int <parameter>connection_id</parameter></paramdef>
+      <paramdef>resource <parameter>connection</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      <function>pg_tty</function> will return the tty name that server
      side debugging output is sent to on the given PostgreSQL
-     connection identifier.
+     connection resource.
     </para>
    </refsect1>
</refentry> @@ -1436,7 +1438,7 @@ 
     <funcsynopsis>
      <funcprototype>
       <funcdef>bool <function>pg_untrace</function></funcdef>
-      <paramdef>int
+      <paramdef>resource
        <parameter><optional>connection</optional></parameter>
       </paramdef>
      </funcprototype>
-- Yasuo Ohgaki

« previous php.doc (#969339640) next »