ECPG connection target formats

ECPG has several discrepancies between the documented connection
target formats and actual behavior. I'm preparing a documentation
patch as I previously mentioned in the recent "Connection string"
thread in pgsql-general, but before doing so I'd like to distinguish
documentation bugs from code bugs. Here are some differences I've
found:

1. dbname[(at)hostname][:port]

This suggests that dbname:port should work but ECPG interprets the
entire "dbname:port" string as the database name. I'm thinking
this is a documentation bug and the format should be shown as

dbname[(at)hostname[:port]]

Does anybody disagree?

2. tcp:postgresql://hostname[:port][/dbname][?options]

This suggests that tcp:postgresql://hostname[:port] should work
without specifying /dbname, and indeed it does work when the
connection target is a variable reference or a double-quoted string
literal. However, the connection name is then set to NULL, causing
segmentation faults on some systems (e.g., Solaris 9) if ECPG
debugging is enabled. When the target is an unquoted literal the
ECPG preprocessor fails with a syntax error. Is the latter case a
grammar bug or should the former case not be allowed?

The documentation doesn't mention anything about the options component
but the source code shows that this value is used as the third
argument to PQsetdbLogin(), which passes command-line options to
the postmaster. I suppose this should be documented, if only via
an example, although I wonder if anybody actually uses it.

3. unix:postgresql://hostname[:port][/dbname][?options]

Same as (2). Also, hostname must be "localhost" or "127.0.0.1"
else the ECPG preprocessor fails if the target is an unquoted
literal, and if the target is double-quoted or a variable reference
then the connection attempt raises a segmentation fault at runtime.
One of the examples is "unix:postgresql://sql.mydomain.com/...",
which I'll fix.

Incidentally, would anybody object to using example.com as the
domain name in examples? RFC 2606 "Reserved Top Level DNS Names"
reserves example.com and several other top- and second-level domains
for "private testing, as examples in documentation, and the like."

4. "an SQL string literal containing one of the above forms"

Michael Meskes recently fixed ECPG to accept double-quoted C strings
but it currently doesn't accept single-quoted SQL strings. My reading
of the standard is that CONNECT TO should allow single-quoted strings,
as I mention here:

http://archives.postgresql.org/pgsql-general/2006-08/msg00838.php

Does anybody interpret the standard differently?

5. "If you specify the connection target literally (that is, not through
a variable reference) and you don't quote the value, then the case-
insensitivity rules of normal SQL are applied."

ECPG's debugging mode and a packet sniff show that unquoted database
and user names are passed as written, so I'm not seeing how the
case-insensitivity rules are being applied. Should this be reworded
or omitted altogether? Or is there something I'm missing?

Other comments? Thanks.

--
Michael Fuhr