Author: mysqlpp
Date: Wed Jan 30 12:02:52 2008
New Revision: 2141
URL: http://svn.gna.org/viewcvs/mysqlpp?rev=2141&view=rev
Log:
Rewrote the userman section on customizing ssqls.pl. Covers new
fp_min_delta stuff, changes in compiler limits w.r.t. macro counts,
makes official the advice about refactoring before changing the max
column count, and describes in more detail how you rebuild ssqls.h
Modified:
trunk/doc/userman/ssqls.dbx
Modified: trunk/doc/userman/ssqls.dbx
URL:
http://svn.gna.org/viewcvs/mysqlpp/trunk/doc/userman/ssqls.dbx?rev=2141&r1=2140&r2=2141&view=diff
==============================================================================
--- trunk/doc/userman/ssqls.dbx (original)
+++ trunk/doc/userman/ssqls.dbx Wed Jan 30 12:02:52 2008
@@ -312,7 +312,7 @@
*this << "INSERT INTO " << v.table() << " (" <<
v.field_list() <<
") VALUES (" << v.value_list() << ")";</programlisting>
- <para>where ’v’ is the SSQLS you’re asking the
+ <para>where ‘v’ is the SSQLS you’re asking the
Query object to insert into the database.</para>
<para>Now let’s look at a complete example, which uses one of
@@ -429,32 +429,76 @@
MySQL++ headers are in their default location,
<filename>/usr/include/mysql++</filename>. If you want to use
headers in some other location, you’ll need to change the
- directory name in <command>-I</command> flag at the top of the
+ directory name in the <command>-I</command> flag at the top of the
script.</para>
</sect2>
- <sect2 id="ssqls-extension">
- <title>Extending the SSQLS Mechanism</title>
+ <sect2 id="ssqls-customization">
+ <title>Customizing the SSQLS Mechanism</title>
<para>The SSQLS header <filename>ssqls.h</filename> is automatically
generated by the Perl script <filename>ssqls.pl</filename>. Although
it is possible to change this script to get additional
- functionality, it’s usually better to do that through
- inheritance.</para>
-
- <para>A regular user may find it helpful to change the the limit on
- the maximum number of SSQLS data members allowed. It’s 25 out
- of the box. A smaller value may speed up compile time, or you may
- require a higher value because you have more complex tables than
- that. Simply change the <varname>max_data_members</varname> variable
- at the top of <filename>ssqls.pl</filename> and say
- <command>make</command>. The limit for Visual C++ is 31, according
- to one report. There doesn’t seem to be a practical limit with
- GCC 3.3 at least: I set the limit to 100 and the only thing that
- happened is that ssqls.h went from 1.3 MB to 18 MB and the build
- time for <filename>examples/ssqls*</filename> got a lot
- longer.</para>
+ functionality, most of the time it’s better to just derive a
+ custom class from the stock SSQLS and add your additional
+ functionality that way.</para>
+
+ <para>That said, <filename>ssqls.pl</filename> does have a few
+ configurables you might want to tweak.</para>
+
+ <para>The first configurable value sets the maximum number of data
+ members allowed in an SSQLS. It’s 25 out of the box, set by
+ the <varname>$max_data_members</varname> variable at the top of
+ <filename>ssqls.pl</filename>. Beware, making this value larger
+ increases the size of <filename>ssqls.h</filename> exponentially;
+ this will increase compile time, and can even expose limits in your
+ compiler. Before you increase this value, take a good, hard look at
+ your database schema and ask if it’s really the best design.
+ Almost always, having so many columns is a sign that you need to
+ refactor the table.</para>
+
+ <para>The second configurable is the default floating point
+ precision used for comparison. As described above (<xref
+ linkend="ssqls-compare-init"/>) SSQLSes can be compared for
+ equality. The only place this is tricky is with floating-point
+ numbers, since rounding errors can make two “equal”
+ values compare as distinct. Since exact comparison makes no sense
+ with floating-point values, MySQL++ lets you specify the precision
+ you want it to use. If the difference between two values is under a
+ given threshold, MySQL++ considers the values equal. The default
+ threshold is 0.00001. This threshold works well for
+ “human” scale values, but because of the way
+ floating-point numbers work, it can be wildly inappropriate for very
+ large or very small quantities like those used in scientific
+ applications.</para>
+
+ <para>There are actually two ways to change this threshold. If you
+ need a different system-wide default, edit
+ <filename>ssqls.pl</filename> and change the
+ <varname>$fp_min_delta</varname> variable at the top of the file,
+ then rebuild <filename>ssqls.h</filename> as described below. If you
+ need different thresholds per file or per project, it’s better
+ to set the C macro <varname>MYSQLPP_FP_MIN_DELTA</varname> instead.
+ The Perl variable sets this macro’s default; if you give a
+ different value before #including <filename>ssqls.h</filename>, it
+ will use that instead.</para>
+
+ <para>To rebuild <filename>ssqls.h</filename> after changing
+ <filename>ssqls.pl</filename>, you’ll need a Perl interpreter.
+ The only modern Unixy system I’m aware of where Perl
+ isn’t installed by default is Cygwin, and it’s just a
+ <filename>setup.exe</filename> choice away there. You’ll
+ probably only have to download and install a Perl interpreter if
+ you’re on Windows and don’t want to use Cygwin.</para>
+
+ <para>If you’re on a system that uses autoconf, building
+ MySQL++ automatically updates <filename>ssqls.h</filename> any time
+ <filename>ssqls.pl</filename> changes. Otherwise, you’ll need
+ to run the Perl interpreter by hand:</para>
+
+ <screen>c:\mysql++> cd lib
+c:\lib> perl ssqls.pl</screen>
</sect2>
_______________________________________________
Mysqlpp-commits mailing list
[email protected]
https://mail.gna.org/listinfo/mysqlpp-commits
