[docs] xmldocs - jon modified 3 files

docs at icdevgroup.org docs at icdevgroup.org
Tue Oct 4 15:59:43 EDT 2005

User:      jon
Date:      2005-10-04 19:59:43 GMT
Modified:  refs     sql.filter
Added:     refs     dbi_quote.filter filter_sql_no_backslash
Document latest commits.

Davor, sorry about the tons of DocBook mistakes that are likely here.

Revision  Changes    Path
1.2       +5 -2      xmldocs/refs/sql.filter

rev 1.2, prev_rev 1.1
Index: sql.filter
RCS file: /var/cvs/xmldocs/refs/sql.filter,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -u -r1.1 -r1.2
--- sql.filter	29 May 2005 15:01:39 -0000	1.1
+++ sql.filter	4 Oct 2005 19:59:43 -0000	1.2
@@ -1,5 +1,5 @@
 __NAME__ purpose
-replace quoting with SQL quoting
+quote strings for use in SQL statements, without reference to a specific database
 __NAME__ see also
@@ -8,7 +8,10 @@
 __NAME__ description
 The filter replaces single quotes (<literal>'</literal>) with 
-"double" single quotes (<literal>''</literal>).
+"double" single quotes (<literal>''</literal>). By default it will also
+replace a backslash (<literal>\</literal>) with two backslashes
+(<literal>\\</literal>) (as is needed to escape PostgreSQL and MySQL
+strings) but that can be disabled by setting the filter_sql_no_backslash pragma.

1.1                  xmldocs/refs/dbi_quote.filter

rev 1.1, prev_rev 1.0
Index: dbi_quote.filter
__NAME__ purpose
safely quote strings for use in SQL statements using DBI's quote method

__NAME__ see also
the sql filter
the query tag and [PREFIX-quote] sub-tag

__NAME__ description

This filter uses DBI's quote method (or the DBD's, if it overrides)
to make a string safe to use in SQL. It takes into account any
database-specific quoting needs, such as <literal>\</literal> for
PostgreSQL or MySQL, truncating at the first ASCII NUL for PostgreSQL,
turning a newline into a literal two-character <literal>\n</literal> for
MySQL, etc.

The default database handle is used (the first ProductFiles database),
unless another is specified. (See the example.)

Note the containing quotes, which is different than Interchange's native
"sql" filter. See also the DBI man page details about the quote method.

Since this uses database handles, Safe must be considered if it's being
used via the $Tag object in a Perl block.

__NAME__ notes
For more information see
and the DBD documentation for your database.

_NAME__ online: Filter example
To use the filter to safely quote the example CGI variable "code",
with the value "that's all":

    [cgi name=code filter=dbi_quote keep=1]

If the default products database is a typical SQL database, that returns:

<literal>'that''s all'</literal>

To quote a literal string, specifying the desired database handle's quote method:

    [filter dbi_quote.inventory]some string \ or other[/filter]

If "inventory" is a MySQL database, this returns:

<literal>'some string \\ or other'</literal>

Whereas if it were an Oracle database, it would return:

<literal>'some string \ or other'</literal>

1.1                  xmldocs/refs/filter_sql_no_backslash

rev 1.1, prev_rev 1.0
Index: filter_sql_no_backslash
__NAME__ purpose
do not escape backslashes in "sql" filter

__NAME__ synopsis
<group choice='req'>
	<arg choice='plain'>0</arg>
	<arg choice='plain'>1</arg>

__NAME__ default

__NAME__ description
This &glos-pragma; disables default doubling of backslashes by the "sql" filter.
You may want to set this pragma if using a database other than PostgreSQL and MySQL.
(SQL standard strings do not treat <literal>\</literal> specially, so it normally
doesn't need to be escaped.)

__NAME__ example: Enable filter_sql_no_backslash pragma catalog-wide
Put the following in catalog.cfg:
Pragma filter_sql_no_backslash

More information about the docs mailing list