Thread: Documentation update for PQexecParams
Hi I have been using PQprepare() and PQexecPrepared(). This has led me to update libpq.sgml, in particular for PQexecParams(). The changes are to the formatting of the arguments for PQexecParams() (as shared by PQexecPrepared()) which make it easier to read, as well as creating a table giving a set of possible values for the various arguments with the associated SQL types. I would imagine the best place to submit the patch would be to psql-patches, however, before I do this I am wondering if this is the right forum for having the changes vetted before submitting the patch. Please advise. -- Regards Theo
On Wed, Nov 08, 2006 at 08:07:19PM +0200, Theo Kramer wrote: > Hi > > I have been using PQprepare() and PQexecPrepared(). This has led me to > update libpq.sgml, in particular for PQexecParams(). > > The changes are to the formatting of the arguments for PQexecParams() > (as shared by PQexecPrepared()) which make it easier to read, as well as > creating a table giving a set of possible values for the various arguments with > the associated SQL types. > > I would imagine the best place to submit the patch would be to > psql-patches, however, before I do this I am wondering if this is the right forum for > having the changes vetted before submitting the patch. > > Please advise. Send it to both lists, and thanks for doing this :) Cheers, D -- David Fetter <david@fetter.org> http://fetter.org/ phone: +1 415 235 3778 AIM: dfetter666 Skype: davidfetter Remember to vote!
On Thu, 2006-11-09 at 06:43 -0800, David Fetter wrote: > On Wed, Nov 08, 2006 at 08:07:19PM +0200, Theo Kramer wrote: > > Hi > > > > I have been using PQprepare() and PQexecPrepared(). This has led me to > > update libpq.sgml, in particular for PQexecParams(). > > > > The changes are to the formatting of the arguments for PQexecParams() > > (as shared by PQexecPrepared()) which make it easier to read, as well as > > creating a table giving a set of possible values for the various arguments with > > the associated SQL types. > > > > I would imagine the best place to submit the patch would be to > > psql-patches, however, before I do this I am wondering if this is the right forum for > > having the changes vetted before submitting the patch. > > > > Please advise. > > Send it to both lists, and thanks for doing this :) > Thanks - attached output of 'diff -c libpq.sgml libpq.sgml.org' where libpq.sgml contains my proposed changes and libpq.sgml.org originates from the 8.2 Beta 2 distribution for comment. -- Regards Theo
Attachment
Am Donnerstag, 9. November 2006 16:04 schrieb Theo Kramer: > Thanks - attached output of 'diff -c libpq.sgml libpq.sgml.org' where > libpq.sgml contains my proposed changes and libpq.sgml.org originates > from the 8.2 Beta 2 distribution for comment. The patch is backwards. -- Peter Eisentraut http://developer.postgresql.org/~petere/
On Fri, 2006-11-10 at 10:50 +0100, Peter Eisentraut wrote: > Am Donnerstag, 9. November 2006 16:04 schrieb Theo Kramer: > > Thanks - attached output of 'diff -c libpq.sgml libpq.sgml.org' where > > libpq.sgml contains my proposed changes and libpq.sgml.org originates > > from the 8.2 Beta 2 distribution for comment. > > The patch is backwards. > Thanks - re-done and re-attached -- Regards Theo
Attachment
Theo Kramer <theo@flame.co.za> writes:
> On Fri, 2006-11-10 at 10:50 +0100, Peter Eisentraut wrote:
>> The patch is backwards.
> Thanks - re-done and re-attached
I applied the part of this that reformats the PQexecParams argument
descriptions --- I agree that makes it more readable. I did not like
the proposed table of datatypes though. It strikes me as incomplete,
unhelpful, and in places downright misleading. For instance, I don't
see the point of listing ODBC type codes; they are irrelevant to libpq,
and the only likely outcome of listing them is that someone might think
he could use them for paramTypes[] entries. The description of the
binary formats was not helpful either, as it avoided any of the useful
details (endianness etc), as well as portability issues like whether
timestamps are int or float.
regards, tom lane
On Fri, 2006-11-10 at 17:24 -0500, Tom Lane wrote: > Theo Kramer <theo@flame.co.za> writes: > > On Fri, 2006-11-10 at 10:50 +0100, Peter Eisentraut wrote: > >> The patch is backwards. > > > Thanks - re-done and re-attached > > I applied the part of this that reformats the PQexecParams argument > descriptions --- I agree that makes it more readable. I did not like > the proposed table of datatypes though. It strikes me as incomplete, > unhelpful, and in places downright misleading. For instance, I don't > see the point of listing ODBC type codes; they are irrelevant to libpq, > and the only likely outcome of listing them is that someone might think > he could use them for paramTypes[] entries. The description of the > binary formats was not helpful either, as it avoided any of the useful > details (endianness etc), as well as portability issues like whether > timestamps are int or float. > Thanks for the input - I agree that the table is incomplete. My intention with the table is for it to be a start to something that is more useful than the incomplete examples regarding these functions. I suggest I redo it taking into consideration your input, unless you have other suggestions for improving the docs on the use with typical values for the arguments. On the ODBC types - I found these useful as my interface is based on that. I imagine that others who have used ODBC and who would like to use the libpq functions may also find it useful, but also agree that it may be misleading. Perhaps, with a couple of iterations, we can get to something that will make the documentation on these functions more useful. -- Regards Theo
Theo Kramer wrote: > > > On the ODBC types - I found these useful as my interface is based on > that. I imagine that others who have used ODBC and who would like to use > the libpq functions may also find it useful, but also agree that it may > be misleading. > > Perhaps, with a couple of iterations, we can get to something that will > make the documentation on these functions more useful. > Maybe add a new chapter discussing ODBC (even if it is *very* short), and include the datatype info in it?