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