While drafting my usual read the fine manual response to the original email I noticed that the pertinent information about placeholders was in the section on bind_param(). Even someone reasonably contientious about reading up on placeholders would probably miss it.
The attached patch moves the discussion about placeholders not being able to substitute for SQL elements needed to parse the statement from the section on bind_param() to the section that discusses placeholders. -- Mac :}) ** I normally forward private questions to the appropriate mail list. ** Ask Smarter: http://www.catb.org/~esr/faqs/smart-questions.html Give a hobbit a fish and he eats fish for a day. Give a hobbit a ring and he eats fish for an age.
# Move placeholder information from bind_param() # # To apply this patch: # STEP 1: Chdir to the source directory. # STEP 2: Run the 'applypatch' program with this patch file as input. # # If you do not have 'applypatch', it is part of the 'makepatch' package # that you can fetch from the Comprehensive Perl Archive Network: # http://www.perl.com/CPAN/authors/Johan_Vromans/makepatch-x.y.tar.gz # In the above URL, 'x' should be 2 or higher. # # To apply this patch without the use of 'applypatch': # STEP 1: Chdir to the source directory. # STEP 2: Run the 'patch' program with this file as input. # #### End of Preamble #### #### Patch data follows #### diff -up 'DBI-1.37/DBI.pm' 'DBI-1.37-mac/DBI.pm' Index: ./DBI.pm Prereq: 11.32 --- ./DBI.pm Thu May 15 10:48:56 2003 +++ ./DBI.pm Tue Jul 1 15:52:14 2003 @@ -2047,6 +2047,25 @@ The C<?> characters are the placeholders values with placeholders is known as I<binding>, and the values are referred to as I<bind values>. +Note that the C<?> is not enclosed in quotation marks, even when the +placeholder represents a string. Some drivers also allow placeholders +like C<:>I<name> and C<:>I<n> (e.g., C<:1>, C<:2>, and so on) +in addition to C<?>, but their use is not portable. + +With most drivers, placeholders can't be used for any element of a +statement that would prevent the database server from validating the +statement and creating a query execution plan for it. For example: + + "SELECT name, age FROM ?" # wrong (will probably fail) + "SELECT name, ? FROM people" # wrong (but may not 'fail') + +Also, placeholders can only represent single scalar values. +For example, the following +statement won't work as expected for more than one value: + + "SELECT name, age FROM people WHERE name IN (?)" # wrong + "SELECT name, age FROM people WHERE name IN (?,?)" # two names + When using placeholders with the SQL C<LIKE> qualifier, you must remember that the placeholder substitutes for the whole string. So you should use "C<... LIKE ? ...>" and include any wildcard @@ -4333,27 +4352,8 @@ are indicated with question mark charact $sth->execute; DBI::dump_results($sth); -Note that the C<?> is not enclosed in quotation marks, even when the -placeholder represents a string. Some drivers also allow placeholders -like C<:>I<name> and C<:>I<n> (e.g., C<:1>, C<:2>, and so on) -in addition to C<?>, but their use -is not portable. Undefined bind values or C<undef> can be used to -indicate null values. - -Some drivers do not support placeholders. - -With most drivers, placeholders can't be used for any element of a -statement that would prevent the database server from validating the -statement and creating a query execution plan for it. For example: +See L</"Placeholders and Bind Values"> for more information. - "SELECT name, age FROM ?" # wrong (will probably fail) - "SELECT name, ? FROM people" # wrong (but may not 'fail') - -Also, placeholders can only represent single scalar values. -For example, the following -statement won't work as expected for more than one value: - - "SELECT name, age FROM people WHERE name IN (?)" # wrong B<Data Types for Placeholders> #### End of Patch data #### #### ApplyPatch data follows #### # Data version : 1.0 # Date generated : Tue Jul 1 15:56:26 2003 # Generated by : makepatch 2.00_09* # Recurse directories : Yes # Excluded files : (\A|/).*\~\Z # (\A|/).*\.a\Z # (\A|/).*\.bak\Z # (\A|/).*\.BAK\Z # (\A|/).*\.elc\Z # (\A|/).*\.exe\Z # (\A|/).*\.gz\Z # (\A|/).*\.ln\Z # (\A|/).*\.o\Z # (\A|/).*\.obj\Z # (\A|/).*\.olb\Z # (\A|/).*\.old\Z # (\A|/).*\.orig\Z # (\A|/).*\.rej\Z # (\A|/).*\.so\Z # (\A|/).*\.Z\Z # (\A|/)\.del\-.*\Z # (\A|/)\.make\.state\Z # (\A|/)\.nse_depinfo\Z # (\A|/)core\Z # (\A|/)tags\Z # (\A|/)TAGS\Z # (\A|/)\.\#.*\Z # (\A|/)\#.*\Z # (\A|/)_\$.*\Z # (\A|/).*\$\Z # (\A|/)CVS\Z # (\A|/)CVS\.adm\Z # (\A|/)cvslog\..*\Z # (\A|/)\,.*\Z # (\A|/).*\,v\Z # (\A|/)RCS\Z # (\A|/)RCSLOG\Z # (\A|/)p\..*\Z # (\A|/)s\..*\Z # (\A|/)SCCS\Z # p 'DBI.pm' 222766 1057099934 0100664 #### End of ApplyPatch data #### #### End of Patch kit [created: Tue Jul 1 15:56:26 2003] #### #### Patch checksum: 108 4331 41928 #### #### Checksum: 126 5002 32402 ####
