On Mon, Mar 11, 2002 at 05:46:01PM +0100, Steffen Goeldner wrote:
> Tim Bunce wrote:
> >
> > Steffen (and anyone else interested),
> >
> > I think we need to mention SQL_ATTR_METADATA_ID in the DBI docs
> > somewhere (even though we don't include an API for it) because we're
> > assuming that (for ODBC drivers) it has a certain value.
> >
> > Also, I think we need to document the differences, where there are
> > any, between passing
> >
> > undef
> > ""
> > "%"
> >
> > to the various meta data methods.
>
> Attached is a short explanation of this topic.
Thanks!
> Tell me if some text passages should be extended.
>
>
> Steffen
> *** DBI-1.21-orig/DBI.pm Thu Feb 07 04:15:50 2002
> --- DBI.pm Sat Mar 09 23:32:09 2002
> ***************
> *** 4462,4467 ****
> --- 4462,4515 ----
>
> =head1 FURTHER INFORMATION
>
> + =head2 Catalog Functions
> +
> + All catalog functions accept arguments in order to restrict the result sets.
> + Passing C<undef> to an optional argument does not constrain the search for
> + that argument.
Let's spell it out for people:
+ (i.e., passing undef is equivalent to passing '%').
> + However, an empty string ('') is treated as a regular search criteria.
+ and will only match an empty value.
> + B<Caveat>: Some DBMS store empty strings as C<NULL>. Neither C<undef> nor
> + an empty string ('') may match these records!
While that's true in general, what _exact_ impact does it have on
catalog function parameters as per the standards? Shouldn't it have
no impact?
> + Most arguments in the catalog functions accept only B<ordinary values>, e.g.
I'd prefer I<> for introducing terminology.
> + the arguments of C<primary_key_info()>.
> + Such arguments are treated as a literal string, i.e. the case is significant
> + and quote characters are taken literally.
The case being significant raises some er, significant, issues for
portability.
> + Some arguments in the catalog functions accept B<search patterns> (strings
> + containing '_' and/or '%'), e.g. the C<$table> argument of C<column_info()>.
> + Passing '%' is equivalent to leaving the argument C<undef>.
Does the DBI spec for each catalog function make it clear enough
which params are 'ordinary values' and which are 'search patterns'?
They should also all have a 'See also' link to this 'Catalog
Functions' section (which should perhaps be called catalog methods :-)
> + B<Caveat>: The pattern '%' has a special meaning for C<table_info()>.
... for certain uses of ...
but it's probably not worth menting here. It should be made clear enough
in the table_info docs.
> + B<Caveat>: The underscore ('_') is valid and often used in SQL identifiers.
> + Passing such a value to a search pattern argument may return more rows than
> + expected!
Umm, I guess the fix is to escape literal underscores with the
appropriate escape character read from get_info (right?).
Probably worth mentioning that.
> + One argument in the catalog functions accepts a B<list of values>:
> + the C<$type> argument of C<table_info()>.
I'd skip that one (as per '%' for table_info() above).
> + The ODBC and SQL/CLI specifications define a way to change the default
> + behavior described above: All arguments (except list value arguments) are
> + treated as identifier if the C<SQL_ATTR_METADATA_ID> attribute is set to
> + C<SQL_TRUE>.
So is 'identifier' here the same as 'ordinary values' above?
Best to use consistent terminology.
> + The DBI (currently) does not support the C<SQL_ATTR_METADATA_ID> attribute,
> + i.e. it behaves like an ODBC driver where C<SQL_ATTR_METADATA_ID> is set to
> + C<SQL_FALSE>.
Tim [who'snot had time to read the ODBC spec recently to answer some of the
questions for himself, sorry]
