Author: wyoung
Date: Thu Sep 18 19:09:31 2008
New Revision: 2360
URL: http://svn.gna.org/viewcvs/mysqlpp?rev=2360&view=rev
Log:
Reworked the v3 API breakages section to cover a corner case recently
discovered. It only happens if you were abusing SSQLS in v2 and blindly
convert to v3 without realizing that the changed mechanism fails to cope
with this abuse.
Modified:
trunk/doc/userman/breakages.dbx
Modified: trunk/doc/userman/breakages.dbx
URL:
http://svn.gna.org/viewcvs/mysqlpp/trunk/doc/userman/breakages.dbx?rev=2360&r1=2359&r2=2360&view=diff
==============================================================================
--- trunk/doc/userman/breakages.dbx (original)
+++ trunk/doc/userman/breakages.dbx Thu Sep 18 19:09:31 2008
@@ -841,17 +841,61 @@
<filename>ssqls.h</filename> for you, but it will go away in a
future version of MySQL++.</para>
- <para>The only supported macros for creating
- SSQLSes now are <function>sql_create_*</function>
- and <function>sql_create_complete_*</function>. The
- “basic” variants were removed because they’re
- less functional than <function>sql_create_*</function>, and
- haven’t been used in the examples or documentation for
- a long time now. The other two methods were removed because
- parameter ordering no longer matters so there’s
- no need for macros that let you have custom parameter
- ordering. (It’s more complicated than that, actually. See
- the ChangeLog for the detailed whys and wherefores.)</para>
+ <para>SSQLSes get populated by field name now, not by
+ field order. In v2, it was absolutely required that your
+ SSQLS had its fields declared in exactly the same order
+ as the fields in the database server, and there could be
+ no gaps. An <command>ALTER TABLE</command> command would
+ almost always necessitate redefining the corresponding SSQLS
+ and rebuilding your program. Some alterations actually made
+ using SSQLS impossible. For the most part, this change just
+ gives your program additional flexibility in the face of
+ future changes. However, code that was taking advantage of
+ this low-level fact will break when moving to v3. Before I
+ explain how, let’s go over the high-level functional
+ changes you’ll find in v3’s SSQLS mechanism.</para>
+
+ <para>Because MySQL++ no longer needs the
+ SSQLS field order to match the SQL field order,
+ the <function>sql_create_c_order_*</function>
+ SSQLS creation macro was dropped in v3. We were
+ also able to drop the ordering parameters from
+ <function>sql_create_complete_*</function>. That in turn
+ means there is no longer a difference between the way it and
+ <function>sql_create_c_names_*</function> work, so the latter
+ was also dropped. Thus, there are now only two groups of SSQLS
+ creation macros left: <function>sql_create_*</function>,
+ which works pretty much as it always has, and
+ <function>sql_create_complete_*</function>, which is the same
+ except for the lack of ordering parameters.</para>
+
+ <para>In general, you should be using
+ <function>sql_create_*</function> for all SSQLSes unless
+ you need to use different names for data members in C++ than
+ you use for the corresponding columns in SQL. In that case,
+ use <function>sql_create_complete_*</function> instead.</para>
+
+ <para>In v2, it was possible to have different SQL column
+ names than SSQLS data member names while still using
+ <function>sql_create_*</function> if you only used SSQLS
+ for data retrieval.<footnote><para>In MySQL++ v2, data
+ retreival (<methodname>Query::storein()</methodname>,
+ <methodname>SSQLS(const Row& other)</methodname>,
+ etc.) worked fine regardless of whether your SSQLS field names
+ matched those in the corresponding SQL table, because the
+ SSQLS was populated by position, not by field name. Thus,
+ if all you used SSQLS for was data retrieval, you could
+ define your structures with <function>sql_create_*</function>
+ in v2. This was never recommended, because such an SSQLS
+ wouldn’t work with other features of MySQL++ like
+ <methodname>Query::insert()</methodname> because they depend
+ on being able to map names from C++ to SQL and back. You
+ needed to use <function>sql_create_c_names_*</function>
+ to make these features work in v2 in the face of a naming
+ scheme difference between C++ and SQL.</para></footnote> In
+ v3, you must use <function>sql_create_complete_*</function>
+ for absolutely all uses of SSQLS when you want the C++ field
+ names to differ from the SQL column names.</para>
<para>The new <classname>Null<T></classname> support in
SSQLSes causes an internal compiler error in Visual C++ 2003.
_______________________________________________
Mysqlpp-commits mailing list
[email protected]
https://mail.gna.org/listinfo/mysqlpp-commits
