<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<sect1 id="breakages">
  <title>Incompatible Library Changes</title>

  <para>This chapter documents those library changes since the epochal
  1.7.9 release that break end-user programs. You can dig this stuff out
  of the ChangeLog, but the ChangeLog focuses more on explaining and
  justifying the facets of each change, while this section focuses on
  how to migrate your code between these library versions.</para>

  <para>Since pure additions do not break programs, those changes are
  still documented only in the ChangeLog.</para>


  <sect2 id="api-changes">
    <title>API Changes</title>

    <para>This section documents files, functions, methods and classes
    that were removed or changed in an incompatible way. If your program
    uses the changed item, you will have to change something in your
    program to get it to compile after upgrading to each of these
    versions.</para>

    <sect3 id="api-1.7.10">
      <title>v1.7.10</title>

      <para>Removed <methodname>Row::operator[]()</methodname> overloads
      except the one for <type>size_type</type>, and added
      <methodname>Row::lookup_by_name()</methodname> to provide the
      &#x201C;subscript by string&#x201D; functionality.  In practical
      terms, this change means that the <varname>row["field"]</varname>
      syntax no longer works; you must use the new
      <methodname>lookup_by_name</methodname> method instead.</para>

      <para>Renamed the generated library on POSIX systems from
      <filename>libsqlplus</filename> to
      <filename>libmysqlpp</filename>.</para>
    </sect3>


    <sect3 id="api-1.7.19">
      <title>v1.7.19</title>

      <para>Removed <methodname>SQLQuery::operator=()</methodname>, and
      the same for its <classname>Query</classname> subclass. Use the
      copy constructor instead, if you need to copy one query to another
      query object.</para>
    </sect3>


    <sect3 id="api-1.7.20">
      <title>v1.7.20</title>

      <para>The library used to have two names for many core classes: a
      short one, such as <classname>Row</classname> and a longer one,
      <classname>MysqlRow</classname>. The library now uses the shorter
      names exclusively.</para>

      <para>All symbols within MySQL++ are in the
      <filename>mysqlpp</filename> namespace now if you use the new
      <filename>mysql++.h</filename> header. If you use the older
      <filename>sqlplus.hh</filename> or <filename>mysql++.hh</filename>
      headers, these symbols are hoist up into the global namespace. The
      older headers cause the compiler to emit warnings if you use them,
      and they will go away someday.</para>
    </sect3>

 
    <sect3 id="api-2.0.0">
      <title>v2.0.0</title>

      <sect4 id="api-2.0.0-Connection">
        <title>Connection class changes</title>

        <itemizedlist>
          <listitem><para><methodname>Connection::create_db()</methodname>
          and <methodname>drop_db()</methodname> return
          <symbol>true</symbol> on success. They returned
          <symbol>false</symbol> in v1.7.<emphasis>x</emphasis>! This
          change will only affect your code if you have exceptions
          disabled.</para></listitem>

          <listitem><para>Renamed
          <methodname>Connection::real_connect()</methodname>
          to <methodname>connect()</methodname>, made several
          more of its parameters default, and removed the
          old <methodname>connect()</methodname> method, as
          it&#x2019;s now a strict subset of the new one. The
          only practical consequence is that if your program
          was using <methodname>real_connect()</methodname>,
          you will have to change it to
          <methodname>connect()</methodname>.</para></listitem>

          <listitem><para>Replaced
          <methodname>Connection::read_option()</methodname> with new
          <methodname>set_option()</methodname> mechanism. In addition
          to changing the name, programs using this function will have
          to use the new <classname>Connection::Option</classname>
          enumerated values, accept a <symbol>true</symbol>
          return value as meaning success instead of 0, and
          use the proper argument type. Regarding the latter,
          <methodname>read_option()</methodname> took a <type>const
          char*</type> argument, but because it was just a thin wrapper
          over the MySQL C API function <ulink url="mysql-options"
          type="mysqlapi"/>, the actual value being pointed to could
          be any of several types. This new mechanism is properly
          type-safe.</para></listitem>
        </itemizedlist>
      </sect4>


      <sect4 id="api-2.0.0-Exception">
        <title>Exception-related changes</title>

        <itemizedlist>
          <listitem><para>Classes <classname>Connection</classname>,
          <classname>Query</classname>, <classname>Result</classname>,
          <classname>ResUse</classname>, and <classname>Row</classname>
          now derive from <ulink type="classref"
          url="OptionalExceptions"/> which gives these classes a common
          interface for disabling exceptions. In addition, almost all
          of the per-method exception-disabling flags were removed. The
          preferred method for disabling exceptions on these objects
          is to create an instance of the new <ulink type="classref"
          url="NoExceptions"/> class on the stack, which disables
          exceptions on an <classname>OptionalExceptions</classname>
          subclass as long as the <classname>NoExceptions</classname>
          instance is in scope. You can instead call
          <methodname>disable_exceptions()</methodname> on any
          of these objects, but if you only want them disabled
          temporarily, it&#x2019;s easy to forget to re-enable them
          later.</para></listitem>

          <listitem><para>In the previous version of MySQL++,
          those classes that supported optional exceptions that
          could create instances of other such classes were
          supposed to pass this flag on to their children. That
          is, if you created a <classname>Connection</classname>
          object with exceptions enabled, and then asked it to
          create a <classname>Query</classname> object, the
          <classname>Query</classname> object also had exceptions
          disabled. The problem is, this didn&#x2019;t happen in all
          cases where it should have in v1.7. This bug is fixed in
          v2.0. If your program begins crashing due to uncaught
          exceptions after upgrading to v2.0, this is the most likely
          cause. The most expeditious fix in this situation is to
          use the new <classname>NoExceptions</classname> feature to
          return these code paths to the v1.7 behavior. A better fix
          is to rework your program to avoid or deal with the new
          exceptions.</para></listitem>

          <listitem><para>All custom MySQL++ exceptions now derive from
          the new <ulink type="classref" url="Exception"/> interface.
          The practical upshot of this is that the variability between
          the various exception types has been eliminated. For instance,
          to get the error string, the <classname>BadQuery</classname>
          exception had a string member called <varname>error</varname>
          plus a method called <methodname>what()</methodname>. Both
          did the same thing, and the <methodname>what()</methodname>
          method is more common, so the error string was dropped
          from the interface. None of the example programs had to be
          changed to work with the new exceptions, so if your program
          handles MySQL++ exceptions the same way they do, your program
          won&#x2019;t need to change, either.</para></listitem>

          <listitem><para>Renamed
          <classname>SQLQueryNEParams</classname> exception to
          <classname>BadParamCount</classname> to match style of other
          exception names.</para></listitem>

          <listitem><para>Added <ulink type="classref"
          url="BadOption"/>, <ulink type="classref"
          url="ConnectionFailed"/>, <ulink type="classref"
          url="DBSelectionFailed"/>, <ulink type="classref"
          url="EndOfResults"/>, <ulink type="classref"
          url="EndOfResultSets"/>, <ulink type="classref"
          url="LockFailed"/>, and <ulink type="classref"
          url="ObjectNotInitialized"/> exception types, to fix
          overuse of <classname>BadQuery</classname>. Now the
          latter is used only for errors on query execution. If
          your program has a &#x201C;catch-all&#x201D; block taking a
          <classname>std::exception</classname> for each try block
          containing MySQL++ statements, you probably won&#x2019;t
          need to change your program. Otherwise, the new exceptions
          will likely show up as program crashes due to unhandled
          exceptions.</para></listitem>
        </itemizedlist>
      </sect4>


      <sect4 id="api-2.0.0-Query">
        <title>Query class changes</title>

        <itemizedlist>

          <listitem><para>In previous versions,
          <classname>Connection</classname> had
          a querying interface similar to class
          <classname>Query</classname>&#x2019;s. These methods were
          intended only for <classname>Query</classname>&#x2019;s use; no
          example ever used this interface directly, so no end-user code
          is likely to be affected by this change.</para></listitem>

          <listitem><para>A more likely problem arising from
          the above change is code that tests for query success
          by calling the <classname>Connection</classname>
          object&#x2019;s <methodname>success()</methodname> method
          or by casting it to <type>bool</type>. This will now give
          misleading results, because queries no longer go through
          the <classname>Connection</classname> object. Class
          <classname>Query</classname> has the same success-testing
          interface, so use it instead.</para></listitem>

          <listitem><para><classname>Query</classname> now derives
          from <classname>std::ostream</classname> instead of
          <classname>std::stringstream</classname>.</para></listitem>

        </itemizedlist>
      </sect4>


      <sect4 id="api-2.0.0-Result">
        <title>Result/ResUse class changes</title>

        <itemizedlist>

          <listitem><para>Renamed
          <methodname>ResUse::mysql_result()</methodname> to
          <methodname>raw_result()</methodname> so it&#x2019;s database
          server neutral.</para></listitem>

          <listitem><para>Removed
          <methodname>ResUse::eof()</methodname>, as it wrapped
          the deprecated and unnecessary MySQL C API function
          <ulink url="mysql-eof" type="mysqlapi"/>. See the
          <filename>simple3</filename> and <filename>usequery</filename>
          examples to see the proper way to test for the end of a result
          set.</para></listitem>

        </itemizedlist>
      </sect4>


      <sect4 id="api-2.0.0-Row">
        <title>Row class changes</title>

        <itemizedlist>

          <listitem><para>Removed &#x201C;field name&#x201D; form
          of <methodname>Row::field_list()</methodname>. It was
          pointless.</para></listitem>

          <listitem><para><classname>Row</classname> subscripting
          works more like v1.7.9: one can subscript a
          <classname>Row</classname> with a string (e.g.
          <methodname>row["myfield"]</methodname>), or with
          an integer (e.g. <methodname>row[5]</methodname>).
          <methodname>lookup_by_name()</methodname> was
          removed. Because <methodname>row[0]</methodname> is
          ambiguous (0 could mean the first field, or be a null
          pointer to <type>const char*</type>), there is now
          <methodname>Row::at()</methodname>, which can look up any
          field by index.</para></listitem>

        </itemizedlist>
      </sect4>


      <sect4 id="api-2.0.0-misc">
        <title>Miscellaneous changes</title>

        <itemizedlist>

          <listitem><para>Where possible, all distributed Makefiles only
          build dynamic libraries. (Shared objects on most Unices, DLLs
          on Windows, etc.) Unless your program is licensed under the
          GPL or LGPL, you shouldn&#x2019;t have been using the static
          libraries from previous versions anyway.</para></listitem>

          <listitem><para>Removed the backwards-compatibility
          headers <filename>sqlplus.hh</filename> and
          <filename>mysql++.hh</filename>. If you were
          still using these, you will have to change to
          <filename>mysql++.h</filename>, which will put all symbols in
          <symbol>namespace mysqlpp</symbol>.</para></listitem>

          <listitem><para>Can no longer use arrow operator
          (<symbol>-></symbol>) on the iterators into the
          <classname>Fields</classname>, <classname>Result</classname>
          and <classname>Row</classname> containers.</para></listitem>

        </itemizedlist>
      </sect4>
    </sect3>

    <sect3 id="api-2.2.0">
      <title>v2.2.0</title>

      <para>Code like this will have to change:</para>

      <programlisting>
query &lt;&lt; "delete from mytable where myfield=%0:myvalue";
query.parse();
query.def["myvalue"] = some_value;
query.execute();</programlisting>

      <para>...to something more like this:</para>

      <programlisting>
query &lt;&lt; "delete from mytable where myfield=%0";
query.parse();
query.execute(some_value);</programlisting>

      <para>The first code snippet abuses the default template query
      parameter mechanism (<varname>Query::def</varname>) to fill out
      the template instead of using one of the overloaded forms of
      <methodname>execute()</methodname>,
      <methodname>store()</methodname> or <methodname>use()</methodname>
      taking one or more <classname>SQLString</classname> parameters.
      The purpose of <varname>Query::def</varname> is to allow for
      default template parameters over multiple queries. In the first
      snippet above, there is only one parameter, so in order to justify
      the use of template queries in the first place, it must be
      changing with each query. Therefore, it isn&#x2019;t really a
      &#x201C;default&#x201D; parameter at all. We did not make this
      change maliciously, but you can understand why we are not in any
      hurry to restore this &#x201C;feature&#x201D;.</para>

      <para>(Incidentally, this change was made to allow better support
      for BLOB columns.)</para>
    </sect3>


    <sect3 id="api-2.3.0">
      <title>v2.3.0</title>

      <para><methodname>Connection::set_option()</methodname> calls now
      set the connection option immediately, instead of waiting until
      just before the connnection is actually established. Code that
      relied on the old behavior could see unhandled exceptions, since
      option setting errors are now thrown from a different part of the
      code. You want to wrap the actual
      <methodname>set_option()</methodname> call now, not
      <methodname>Connection::connect()</methodname></para>

      <para><classname>FieldNames</classname> and
      <classname>FieldTypes</classname> are no longer exported from the
      library. If you are using these classes directly from Visual C++
      or MinGW, your code won&#x2019;t be able to dynamically link to a
      DLL version of the library any more. These are internal classes,
      however, so no one should be using them directly.</para>
    </sect3>


    <sect3 id="api-3.0.0">
      <title>v3.0.0</title>

      <sect4 id="api-3.0.0-names">
        <title>Class name changes</title>

        <para>Several classes changed names in this
        release:</para>

        <itemizedlist>
          <listitem><para><classname>ColData</classname> is now
          <classname>String</classname>.</para></listitem>

          <listitem><para><classname>NullisBlank</classname>
          is now <classname>NullIsBlank</classname>. (Note
          the capital <emphasis>I</emphasis>.) Similar
          changes for <classname>NullisNull</classname> and
          <classname>NullisZero</classname>.</para></listitem>

          <listitem><para><classname>ResNSel</classname> is now
          <classname>SimpleResult</classname>.</para></listitem>

          <listitem><para><classname>Result</classname> is now
          <classname>StoreQueryResult</classname>.</para></listitem>

          <listitem><para><classname>ResUse</classname> is now
          <classname>UseQueryResult</classname>.</para></listitem>

          <listitem><para><classname>SQLString</classname> is now
          <classname>SQLTypeAdapter</classname>.</para></listitem>
        </itemizedlist>

        <para>When first building existing code against this version,
        you may find it helpful to define the macro
        <varname>MYSQLPP_OLD_CLASS_NAMES</varname> in your
        program&#x2019;s build options. This will turn on some macros
        that set up aliases for the new class names matching their
        corresponding old names. Then, when you&#x2019;ve fixed up any
        other issues that may prevent your program from building with
        the new MySQL++, you can turn it back off and fix up any class
        name differences.</para>

        <para>If you were only using <classname>ColData</classname> in a
        BLOB context, you should use <classname>sql_blob</classname> or
        one of the related typedefs defined in
        <filename>lib/sql_types.h</filename> instead, to insulate your
        code from changes like these.</para>

        <para>The <classname>SQLString</classname> change
        shouldn&#x2019;t affect you, as this class was not designed to be
        used by end user code. But, due to the old name and the fact
        that it used to derive from <classname>std::string</classname>,
        some might have been tempted to use it as an enhanced
        <classname>std::string</classname>. Such code will undoubtedly
        break, but can probably be fixed by just changing it to use
        <classname>std::string</classname> instead.</para>
      </sect4>


      <sect4 id="api-3.0.0-Connection">
        <title>Connection class changes</title>

        <para>The option setting mechanism has been redesigned. (Yes,
        again.) There used to be an enum in
        <classname>Connection</classname> with a value for each option
        we understood, and an overload of
        <methodname>Connection::set_option()</methodname> for each
        argument type we understood. It was possible to pass any option
        value to any <methodname>set_option()</methodname> overload, and
        the problem would only be detected at run time. Now each option
        is represented by a class derived from the new
        <classname>Option</classname> abstract base class, and
        <methodname>set_option()</methodname> simply takes a pointer to
        one of these objects. See
        <filename>examples/multiquery.cpp</filename> for the syntax.
        Since each <classname>Option</classname> subclass takes only the
        parameter types it actually understands, it&#x2019;s now
        completely type-safe at compile time.</para>

        <para>The new option setting mechanism also has the virtue of
        being more powerful so it let us replace several existing things
        within <classname>Connection</classname> with new
        options:</para>

        <itemizedlist>
          <listitem><para>Replaced
          <methodname>enable_ssl()</methodname> with
          <classname>SslOption</classname>.</para></listitem>

          <listitem><para>Replaced the <varname>compress</varname>
          parameter to the <classname>Connection</classname>
          create-and-connect constructor and
          <methodname>Connection::connect()</methodname> method with
          <classname>CompressOption</classname>.</para></listitem>

          <listitem><para>Replaced the
          <varname>connect_timeout</varname> parameter with
          <classname>ConnectTimeoutOption</classname>.</para></listitem>

          <listitem><para>Defined <classname>Option</classname>
          subclasses for each of the flags you would previously set
          using the <varname>client_flag</varname> parameter. There
          are about a dozen of these, so instead of listing them,
          look in <filename>lib/options.h</filename> for something
          with a similar name.</para></listitem>
        </itemizedlist>

        <para>Collapsed <classname>Connection</classname>&#x2019;s
        <varname>host</varname>, <varname>port</varname>, and
        <varname>socket_name</varname> parameters down into a new
        combined <varname>server</varname> parameter which is parsed to
        determine what kind of connection you mean. These interfaces are
        still compatible with v2.3 and earlier up through the port
        parameter.</para>

        <para>Moved
        <methodname>Connection::affected_rows()</methodname>,
        <methodname>info()</methodname> and
        <methodname>insert_id()</methodname> methods to class
        <classname>Query</classname>, as they relate to the most
        recently-executed query.</para>

        <para>Changed the return type of
        <methodname>Connection::ping()</methodname> from
        <type>int</type> to <type>bool</type>. If you were calling
        <methodname>ping()</methodname> in <type>bool</type> context
        or using its return value in <type>bool</type> context,
        you will need to reverse the sense of the test because the
        previous return code used zero to mean success. Now it returns
        <type>true</type> to indicate success.</para>

        <para>Renamed several methods:</para>

        <itemizedlist>
          <listitem><para>Use <methodname>client_version()</methodname>
          instead of <methodname>api_version()</methodname> or
          <methodname>client_info()</methodname>.</para></listitem>

          <listitem><para>Use
          <methodname>ipc_version()</methodname> instead of
          <methodname>host_info()</methodname>.</para></listitem>

          <listitem><para>Use
          <methodname>protocol_version()</methodname> instead of
          <methodname>proto_info()</methodname>.</para></listitem>

          <listitem><para>Use
          <methodname>server_version()</methodname> instead of
          <methodname>server_info()</methodname>.</para></listitem>

          <listitem><para>Use
          <methodname>status()</methodname> instead of
          <methodname>stat()</methodname>.</para></listitem>
        </itemizedlist>

        <para>Also, removed <methodname>close()</methodname> in favor
        of <methodname>disconnect()</methodname>, which has always
        done the same thing.</para>
      </sect4>


      <sect4 id="api-3.0.0-DateTime">
        <title>Date and Time class changes</title>
  
        <para>The <type>sql_timestamp</type> typedef is now
        an alias for <classname>DateTime</classname>, not
        <classname>Time</classname>.</para>

        <para>There used to be implicit conversion constructors from
        <classname>ColData</classname> (now
        <classname>String</classname>),
        <classname>std::string</classname> and <type>const char*</type>
        for the <classname>Date</classname>,
        <classname>DateTime</classname>, and <classname>Time</classname>
        classes. It&#x2019;s still possible to do these conversions, but
        only explicitly. (This had to be done to make
        <classname>Null&lt;T&gt;</classname> work in SSQLSes.)</para>

        <para>The most likely place to run into problems as a result
        of this change is in code like this:</para>

        <programlisting>
void some_function(const mysqlpp::DateTime&amp; dt);

some_function("2007-12-22");</programlisting>

        <para>The function call needs to be changed to:</para>

        <programlisting>
some_function(mysqlpp::DateTime("2007-12-22"));</programlisting>
      </sect4>


      <sect4 id="api-3.0.0-Exception">
        <title>Exception changes</title>

        <para>If an error occurs during the processing of a
        &#x201C;use&#x201D; query (as opposed to the initial execution) we
        throw the new <classname>UseQueryError</classname> exception
        instead of <classname>BadQuery</classname>.</para>

        <para>If you pass bad values to the <classname>Row</classname>
        ctor so that it can&#x2019;t initialize itself properly, it
        throws the <classname>ObjectNotInitialized </classname>
        exception instead of <classname>BadQuery</classname>.</para>

        <para>Together, these two changes mean that
        <classname>BadQuery</classname> is now used solely to indicate
        a problem executing the actual SQL query statement.</para>
      </sect4>


      <sect4 id="api-3.0.0-Field">
        <title>Field and Fields class changes</title>

        <para><classname>Field</classname> is now a real C++ class,
        not just a typedef for the corresponding C API class. Major
        portability impacts are:</para>

        <itemizedlist>
          <listitem><para>It has no public data members. Where
          sensible, there is a public accessor function of the
          same name as the corresponding field in the C API
          structure.</para></listitem>

          <listitem><para>The main exception to this is the
          <varname>flags</varname> data member. This is a bitfield in
          the C API data structure and you had to use MySQL-specific
          constants to break values out of it. MySQL++&#x2019;s new
          <classname>Field</classname> class provides a public member
          function returning <type>bool</type> for each of these
          flags.</para></listitem>

          <listitem><para>The new class doesn&#x2019;t include all of the
          data members from the C API version. We left out those that
          aren&#x2019;t used within MySQL++ or its examples, or whose
          function we couldn&#x2019;t understand. Basically, if we
          couldn&#x2019;t document a reason to use it, we left it
          out.</para></listitem>
        </itemizedlist>

        <para><classname>Fields</classname> used to be a
        <classname>std::vector</classname> work-alike which
        worked with the C API to access fields and return them
        as though they were simply contained directly within the
        <classname>Fields</classname> object. Now that we have a
        real MySQL++ class to hold information about each field
        without reference to the C API, we were able to replace the
        <classname>Fields</classname> class with:</para>

        <programlisting>
typedef std::vector&lt;Field&gt; Fields;</programlisting>

        <para>If anything, this should give a pure superset of the old
        functionality, but it&#x2019;s possible it could break end user
        code.</para>
      </sect4>


      <sect4 id="api-3.0.0-Query">
        <title>Query class changes</title>

        <para>If you were using <type>char</type> as an 8-bit integer
        in query building, there are several places in MySQL++ v3 where
        it will now be treated as a single-character string. MySQL++
        has had the <classname>tiny_int</classname> class for many
        years now specifically to provide a true 8-bit integer without
        the semantic confusion surrounding the old C <type>char</type>
        type. Either use <classname>tiny_int</classname>, or
        use the SQL type aliases <type>sql_tinyint</type> and
        <type>sql_tinyint_unsigned</type> instead.</para>

        <para>The &#x2018;r&#x2019; and &#x2018;R&#x2019; template query
        parameter modifiers were removed. They made the library do
        quoting and both quoting and escaping (respectively) regardless
        of the data type of the parameter. There are no corresponding
        <classname>Query</classname> stream manipulators, so for
        symmetery we had to decide whether to add such manipulators or
        remove the tquery modifiers. There should never be a reason to
        force quoting or escaping other than to work around a MySQL++
        bug, and it&#x2019;s better to just fix the bug than work around
        it, so removed the tquery modifiers.</para>

        <para><methodname>Query::store_next()</methodname>
        and <methodname>Result::fetch_row()</methodname> no
        longer throw the <classname>EndOfResults</classname> and
        <classname>EndOfResultSets</classname> exceptions; these
        are not exceptional conditions! These methods simply return
        <type>false</type> when you hit the end of the result set
        now.</para>

        <para>Renamed <varname>Query::def</varname> to
        <varname>Query::template_defaults</varname> to make its
        purpose clearer.</para>

        <para>Removed <methodname>Query::preview()</methodname>.  The
        most direct replacement for this set of overloaded methods is
        the parallel set of <methodname>str()</methodname> methods,
        which were just aliases before. (Chose
        <methodname>str()</methodname> over
        <methodname>preview()</methodname> because it&#x2019;s standard
        C++ nomenclature.) But if you&#x2019;re just looking to get a
        copy of a built query string and you aren&#x2019;t using template
        queries, you can now insert the <classname>Query</classname>
        into a stream and get the same result.</para>

        <para>For example, a lot of code in the examples that used to
        say things like:</para>

        <programlisting>
cout &lt;&lt; query.preview() &lt;&lt; endl;</programlisting>

        <para>now looks like this:</para>
        
        <programlisting>
cout &lt;&lt; query &lt;&lt; endl;</programlisting>
      </sect4>


      <sect4 id="api-3.0.0-Result">
        <title>Result, ResUse, and ResNSel class changes</title>

        <para>In addition to the class name changes described above,
        <classname>UseQueryResult</classname> is no longer
        <classname>StoreQueryResult</classname>&#x2019;s base class.
        There is a new abstract class called
        <classname>ResultBase</classname> containing much of what used
        to be in <classname>ResUse</classname>, and it is the base of
        both of these concrete result set types. This should only affect
        your code if you were using <classname>ResUse</classname>
        references to refer to <classname>Result</classname>
        objects.</para>

        <para>Removed a bunch of duplicate methods:</para>
        
        <itemizedlist>
          <listitem><para>Use
          <methodname>num_fields()</methodname> instead of
          <methodname>columns()</methodname>.</para></listitem>

          <listitem><para>Use
          <methodname>field_names()</methodname> instead of
          <methodname>names()</methodname>.</para></listitem>

          <listitem><para>Use
          <methodname>num_rows()</methodname> instead of
          <methodname>rows()</methodname>.</para></listitem>

          <listitem><para>Use
          <methodname>field_types()</methodname> instead of
          <methodname>types()</methodname>.</para></listitem>
        </itemizedlist>

        <para>Renamed several methods for &#x201C;grammar&#x201D; reasons.
        For example, some methods returned a single object but had a
        &#x201C;plural&#x201D; name, implying that it returned a container
        of objects. In cases like this, we changed the name to agree
        with the return value. Some of these also fall into the
        duplicate method category above:</para>

        <itemizedlist>
          <listitem><para>Use
          <methodname>field(unsigned int)</methodname>
          instead of <methodname>fields(unsigned
          int)</methodname>.</para></listitem>

          <listitem><para>Use <methodname>field_num(const
          std::string&amp;)</methodname>
          instead of <methodname>names(const
          std::string&amp;)</methodname>.</para></listitem>

          <listitem><para>Use
          <methodname>field_name(int)</methodname> instead of
          <methodname>names(int)</methodname>.</para></listitem>

          <listitem><para>Use
          <methodname>field_type(int)</methodname> instead of
          <methodname>types(int)</methodname>.</para></listitem>
        </itemizedlist>

        <para>Removed several &#x201C;smelly&#x201D; methods:</para>

        <itemizedlist>
          <listitem><para><methodname>purge()</methodname>: was an
          internal implementation detail, not something for end user
          code to call</para></listitem>

          <listitem><para><methodname>raw_result()</methodname>: end
          user code shouldn&#x2019;t be digging down to the C API data
          structures, but if you really need something like this, look
          at the implementation of
          <methodname>Query::storein()</methodname>. Its workings will
          probably be educational.</para></listitem>

          <listitem><para><methodname>reset_names()</methodname>:
          no reason to call this, especially now that the field
          name list is initialized once at startup and then never
          changed</para></listitem>

          <listitem><para><methodname>reset_field_names()</methodname>:
          just an alias for previous</para></listitem>

          <listitem><para><methodname>reset_types()</methodname>:
          same argument as for
          <methodname>reset_names()</methodname></para></listitem>

          <listitem><para><methodname>reset_field_types()</methodname>:
          just an alias for previous</para></listitem>
        </itemizedlist>

        <para><methodname>ResUse::field_num()</methodname> would
        unconditionally throw a <classname>BadFieldName</classname>
        exception when you asked for a field that doesn&#x2019;t exist.
        Now, if exceptions are disabled on the object, it just returns
        -1.</para>

        <para><classname>SimpleResult</classname>&#x2019;s member
        variables are all now private, and have read-only accessor
        functions of the same name.</para>

        <para>Code like this used to work:</para>

        <programlisting>
mysqlpp::Row row;
mysqlpp::Result::size_type i;
for (i = 0; row = res[i]; ++i) {
  // Do something with row here
}</programlisting>

        <para>That is, indexing past the end of a &#x201C;store&#x201D;
        result set would just return an empty row object, which tests as
        false in <type>bool</type> context, so it ends the loop. Now
        that <classname>StoreQueryResult</classname> is a
        <classname>std::vector</classname> derivative, this either
        crashes your program or causes the standard library to throw an
        exception, depending on what debugging features your version of
        STL has. The proper technique is:</para>

        <programlisting>
mysqlpp::Row row;
mysqlpp::StoreQueryResult::size_type i;
for (i = 0; i &lt; res.num_rows(); ++i) {
  row = res[i];
  // Do something with row here
}</programlisting>

        <para>...or, in a more C++ish idiom:</para>

        <programlisting>
mysqlpp::Row row;
mysqlpp::StoreQueryResult::const_iterator it;
for (it = res.begin(); it != res.end(); ++it) {
  row = *it;
  // Do something with row here
}</programlisting>
      </sect4>


      <sect4 id="api-3.0.0-Row">
        <title>Row class changes</title>

        <para>Removed <methodname>Row::raw_data()</methodname>,
        <methodname>raw_size()</methodname> and
        <methodname>raw_string()</methodname>. These were useful with
        BLOB data back when MySQL++ didn&#x2019;t handle embedded null
        characters very well, and when copies of
        <classname>ColData</classname> objects were expensive. Neither
        is true now, so they have no value any more. Equivalent calls
        are:</para>

        <programlisting>
mysqlpp::String s = row[0];
s.data();                          // raw_data() equivalent
s.length();                        // raw_size() equivalent
std::string(s.data(), s.length()); // raw_string() equivalent</programlisting>

        <para><methodname>Row::operator[](const char*)</methodname>
        would unconditionally throw a
        <classname>BadFieldName</classname> exception when you asked for
        a field that doesn&#x2019;t exist. Now, if exceptions are
        disabled on the <classname>Row</classname> object, it just
        returns a reference to an empty <classname>String</classname>
        object.  You can tell when this happens because such an object
        tests as false in <type>bool</type> context.</para>
      </sect4>


      <sect4 id="api-3.0.0-SSQLS">
        <title>Specialized SQL Structure (SSQLS) changes</title>

        <para>Renamed <filename>custom*</filename> to
        <filename>ssqls*</filename>. There is a backwards-compatibility
        header <filename>custom.h</filename> which includes
        <filename>ssqls.h</filename> for you, but it will go away in a
        future version of MySQL++.</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&#x2019;s go over the high-level functional
        changes you&#x2019;ll find in v3&#x2019;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&amp; 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&#x2019;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&lt;T&gt;</classname> support in
        SSQLSes causes an internal compiler error in Visual C++ 2003.
        (VC++ 2005 and newer have no trobule with it.) A poll on the
        mailing list says there aren&#x2019;t many people still stuck on
        this version, so we just ifdef&#x2019;d out the SSQLS mechanism
        and all the examples that use it when built with VC++ 2003.  If
        this affects you, see <xref linkend="ssqls-vc2003"/> for
        suggestions on ways to cope.</para>

        <para>If you are using types other than MySQL++&#x2019;s
        <type>sql_*</type> ones <footnote><para>These typedefs
        have been available since MySQL++ v2.1.</para></footnote>
        in your SSQLSes, code that previously worked may now see
        <classname>TypeLookupFailed</classname> exceptions. (This
        can be thrown even if exceptions are otherwise disabled in
        MySQL++.) This version of MySQL++ is stricter about mapping
        SQL to C++ type information, and vice versa. If the library
        can&#x2019;t find a suitable mapping from one type system
        to the other, it throws this exception, because its only
        other option would be to crash or raise an assertion. This
        typically happens when building SQL queries, so you can
        probably handle it the same way as if the subsequent
        query excecution failed. If you&#x2019;re catching the
        generic <classname>mysqlpp::Exception</classname>, your
        error handling code might not need to change. If you see
        this exception, it does mean you need to look into your
        use of data types, though. The table that controls this is
        <varname>mysql_type_info::types</varname>, defined at the top
        of <filename>lib/type_info.cpp</filename>. Every data type in
        <filename>lib/sql_types.h</filename> has a corresponding record
        in this table, so if you stick to those types, you&#x2019;ll
        be fine. It&#x2019;s also okay to use types your C++ compiler
        can convert directly to these predefined types.</para>

        <para>The <varname>_table</varname> static member variable
        for each SSQLS is now private. The recommended way to access
        this remains unchanged: the <function>table()</function>
        static member function.</para>

        <para><function>table()</function> used to return a modifiable
        reference to the table name. Now there are two overloads,
        one which returns an unmodifiable pointer to the table name,
        and the other which takes <type>const char*</type> so you
        can override the default table name. So, the code we used to
        recommend for changing the SSQLS&#x2019;s table name:</para>

        <programlisting>
my_ssqls_type::table() = "MyTableName";</programlisting>

        <para>now needs to be:</para>

        <programlisting>
my_ssqls_type::table("MyTableName");</programlisting>
      </sect4>


      <sect4 id="api-3.0.0-misc">
        <title>Miscellaneous changes</title>

        <para>MySQL++ does quoting and escaping much more selectively
        now. Basically, if the library can tell you&#x2019;re not
        building a SQL query using one of the standard methods, it
        assumes you&#x2019;re outputting values for human consumption, so
        it disables quoting and SQL escaping. If you need to build your
        own mechanism to replace this, quoting is easy to do, and
        <methodname>Query::escape_string()</methodname> can do SQL
        escaping for you.</para>

        <para>Removed <methodname>success()</methodname> in
        <classname>Connection</classname>, <classname>Query</classname>
        and <classname>SimpleResult</classname> (neé
        <classname>ResNSel</classname>) and simply made these classes
        testable in <type>bool</type> context to get the same
        information. An additional change in
        <classname>Connection</classname> is that it used to be
        considered &#x201C;unsuccessful&#x201D; when the connection was
        down. Since the sense of this test is now whether the object is
        in a good state, it only returns <type>false</type> when the
        connection attempt fails. Call
        <methodname>Connection::is_connected()</methodname> if you just
        want to test whether the connection is up.</para>

        <para>The debug mode build of the library now has a "_d" suffix
        for Visual C++, and Xcode. This lets you have both versions
        installed without conflict. The release build uses the current
        naming scheme. If you have an existing program building against
        MySQL++ on these platforms, you&#x2019;ll need to change your
        build options to use the new name in debug mode.</para>

        <para>Renamed <varname>NO_LONG_LONGS</varname> to
        <varname>MYSQLPP_NO_LONG_LONGS</varname> to avoid a risk of
        collision in the global macro namespace.</para>
      </sect4>
    </sect3>


    <sect3 id="api-3.0.7">
      <title>v3.0.7</title>

      <para>Most MySQL++ classes with <methodname>at()</methodname>
      or <methodname>operator []()</methodname> methods now
      throw the new <ulink type="structref" url="BadIndex"/>
      exception when you pass an out-of-range index. These
      methods variously either did not check their indices,
      or threw <classname>std::out_of_range</classname> when
      passed a bad index.</para>
      
      <para>I say &ldquo;most&rdquo; because there is at
      least one MySQL++ class that doesn&rsquo;t follow this
      rule. <classname>Fields</classname> is just a typedef for a
      specialization of <classname>std::vector</classname>, and the
      Standard has its own rules for index checking.</para>
    </sect3>
  </sect2>


  <sect2 id="abi-changes">
    <title>ABI Changes</title>

    <para>This section documents those library changes that require you
    to rebuild your program so that it will link with the new library.
    Most of the items in the previous section are also ABI changes, but
    this section is only for those items that shouldn&#x2019;t require
    any code changes in your program.</para>

    <para>If you were going to rebuild your program after
    installing the new library anyway, you can probably ignore this
    section.</para>


    <sect3 id="abi-1.7.18">
      <title>v1.7.18</title>

      <para>The <classname>Query</classname> classes now subclass from
      <classname>stringstream</classname> instead of the deprecated
      <classname>strstream</classname>.</para>
    </sect3>


    <sect3 id="abi-1.7.19">
      <title>v1.7.19</title>

      <para>Fixed several <type>const</type>-incorrectnesses in the
      <classname>Query</classname> classes.</para>
    </sect3>


    <sect3 id="abi-1.7.22">
      <title>v1.7.22</title>

      <para>Removed &#x201C;reset query&#x201D; parameters from several
      <classname>Query</classname> class members. This is not an API
      change, because the parameters were given default values, and the
      library would ignore any value other than the default. So, any
      program that tried to make them take another value wouldn&#x2019;t
      have worked anyway.</para>
    </sect3>


    <sect3 id="abi-1.7.24">
      <title>v1.7.24</title>

      <para>Some freestanding functions didn&#x2019;t get moved into
      <symbol>namespace mysqlpp</symbol> when that namespace was
      created. This release fixed that. It doesn&#x2019;t affect the API
      if your program&#x2019;s C++ source files say <symbol>using
      namespace mysqlpp</symbol> within them.</para>
    </sect3>


    <sect3 id="abi-2.0.0">
      <title>v2.0.0</title>

      <para>Removed <methodname>Connection::infoo()</methodname>.
      (I&#x2019;d call this an API change if I thought there were any
      programs out there actually using this...)</para>

      <para>Collapsed the <classname>Connection</classname> constructor
      taking a bool (for setting the throw_exceptions flag) and the
      default constructor into a single constructor using a default for
      the parameter.</para>

      <para>Classes <classname>Connection</classname> and
      <classname>Query</classname> are now derived from the
      <classname>Lockable</classname> interface, instead of implementing
      their own lock/unlock functions.</para>

      <para>In several instances, functions that took objects by
      value now take them by const reference, for efficiency.</para>

      <para>Merged <classname>SQLQuery</classname> class&#x2019;s members
      into class <classname>Query</classname>.</para>

      <para>Merged <classname>RowTemplate</classname> class&#x2019;s
      members into class <classname>Row</classname>.</para>

      <para>Reordered member variable declarations in some classes. The
      most common instance is when the private section was declared
      before the public section; it is now the opposite way. This
      can change the object&#x2019;s layout in memory, so a program
      linking to the library must be rebuilt.</para>

      <para>Simplified the date and time class hierarchy.
      <ulink type="structref" url="Date"/> used to
      derive from <classname>mysql_date</classname>,
      <ulink type="structref" url="Time"/> used to derive
      from <classname>mysql_time</classname>, and <ulink
      type="structref" url="DateTime"/> used to derive from
      both of those.  All three of these classes used to derive
      from <classname>mysql_dt_base</classname>.  All of the
      <classname>mysql_*</classname> classes&#x2019; functionality
      and data has been folded into the leaf classes, and now the
      only thing shared between them is their dependence on the
      <ulink type="structref" url="DTbase"/> template. Since the
      leaf classes&#x2019; interface has not changed and end-user
      code shouldn&#x2019;t have been using the other classes, this
      shouldn&#x2019;t affect the API in any practical way.</para>

      <para><classname>mysql_type_info</classname> now always
      initializes its private <varname>num</varname> member.
      Previously, this would go uninitialized if you used the default
      constructor. Now there is no default ctor, but the ctor taking one
      argument (which sets <varname>num</varname>) has a default.</para>
    </sect3>


    <sect3 id="abi-3.0.0">
      <title>v3.0.0</title>

      <para>Removed <varname>reset_query</varname> parameters from
      <classname>Query</classname> member functions. None of these have
      been honored at least going back to v1.7.9, so this is not an API
      change. As of this version, <classname>Query</classname> now
      automatically detects when it can safely reset itself after
      executing a query, so it&#x2019;s not necessary to ask for a reset
      except when using template queries.</para>

      <para>Removed overloads of
      <methodname>Query::execute()</methodname>,
      <methodname>store()</methodname>, and
      <methodname>use()</methodname> that take only a <type>const
      char*</type>. This is not an API change because there was an
      equivalent call chain for this already. This change just snaps
      a layer of indirection.</para>

      <para><methodname>Query::error()</methodname> is now
      <type>const</type> and returns <type>const char*</type> instead
      of a <classname>std::string</classname> by value.</para>

      <para>Removed <classname>Lockable</classname> mechanism as it was
      conceptually flawed. <classname>Connection</classname> and
      <classname>Query</classname> consequently no longer derive from
      <classname>Lockable</classname>. Since it was basically useless in
      prior versions, it can&#x2019;t be construed as an API
      change.</para>
    </sect3>


    <sect3 id="abi-3.0.1">
      <title>v3.0.1</title>

      <para><methodname>Connection::thread_aware()</methodname>,
      <methodname>thread_start()</methodname> and
      <methodname>thread_end()</methodname> are now static methods, so
      a program can call them before creating a connection. Ditto for
      <classname>DBDriver</classname> methods of the same name.</para>

      <para><methodname>ConnectionPool::release()</methodname> is now
      virtual, so a subclass can override it.</para>
    </sect3>


    <sect3 id="abi-3.0.2">
      <title>v3.0.2</title>

      <para><methodname>ConnectionPool::grab()</methodname> is now
      virtual; same reason as above.</para>

      <para><classname>Query</classname> can now be tested in
      <type>bool</type> context, as was intended for v3.0.0. Had to
      change the &#x201C;safe bool&#x201D; method signature to make it
      happen, so technically it&#x2019;s an API change, but it&#x2019;s
      still used the same way.</para>
    </sect3>


    <sect3 id="abi-3.1.0">
      <title>v3.1.0</title>

      <para>The addition of a few new virtual methods to
      <classname>ConnectionPool</classname> inadvertently changed
      the library ABI. I knew adding fields changed the ABI, but
      erroneously assumed that the inverse of that truth &mdash; that
      adding <emphasis>methods</emphasis> was always safe &mdash;
      was also true. Adding normal methods <emphasis>is</emphasis>
      safe, but adding <emphasis>virtual</emphasis> methods breaks
      the ABI because it changes the class&rsquo;s vtable size.</para>

      <para>That left us with two bad choices: either we could come
      out with a 3.1.1 that removed these methods to restore the prior
      ABI, or we could just declare this the &ldquo;new ABI&rdquo;
      and move on, resolving not to fall into this trap again.
      We&rsquo;ve chosen the latter path.</para>
    </sect3>
  </sect2>
</sect1>