KInterbasDB Changelog

-----------------------------------------------------------------------------
3.0.1 versus 3.0.1_pre3
-----------------------------------------------------------------------------
  BUG FIXES:
    - Adjusted input handling of NULL values.  The new scheme raises an
      exception immediately when it detects that a Python None value has
      arrived for storage in a database field or parameter that disallows
      NULL values.
        The old scheme simply accepted the Python None value and then tried
      to execute the query, relying on the database API to detect the error.
      With certain data types, the database API would silently insert a bogus
      value rather than detecting the error.

    - Scrutinized the datetime input/output facilities, found some
      incompatibilities with the DB API, and corrected them.  These changes
      are backward-incompatible, but are warranted because the previous
      behavior was in defiance of the specification.  See further notes about
      the nature of these changes in the backward-incompatibilities section.

    - Fixed a memory leak that affected the storage of Python string input
      parameters in BLOB fields.

    - Fixed a rollback-related bug that arose if a connection to a database
      was established, but a transaction was never started on that connection.
      In such a case, a spurious exception was raised when the connection was
      garbage collected.
        Normal code would not have invoked this bug, but it was still a bug.

  BACKWARD-INCOMPATIBILITIES:
    - Datetime input/output has changed to better comply with the DB API (see
      datetime bugfix discussion above).
        Code that uses the mx.DateTime module directly (rather than the
      kintebasdb DB API datetime constructors) should not be affected.
        For details, see the comments in the code block in __init__.py tagged
      with "DSR:2002.07.19".

-----------------------------------------------------------------------------
3.0.1_pre3 versus 3.0.1_pre2
-----------------------------------------------------------------------------
  BUG FIXES:
    - Bug #572326 (which was not present in kinterbasdb 3.0 and never affected
      Python 2.2+) caused several numeric types to not be transferred from
      Python to the database engine when they were passed as query parameters.
        This was a serious bug; it caused even such fundamental operations as:
      cursor.execute("insert into the_table values (?)", (1,))
      to not work correctly.

-----------------------------------------------------------------------------
3.0.1_pre2 versus 3.0.1_pre1
-----------------------------------------------------------------------------
  BUG FIXES:
    - CHAR output now doesn't have such problems with multibyte character sets
      and values shorter than the maximum declared length of the field.
        CHARs are no longer returned with their trailing blanks intact.  The
      trailing blanks have been abandoned because they were in fact NULL
      characters, not spaces.  kinterbasdb would fill in the spaces manually,
      except for the problems that approach causes with multibyte character
      sets.

    - Fixed a potential buffer overflow, but the fix only applies when compiled
      against Python 2.2 or later.

  BACKWARD-INCOMPATIBILITIES:
    - See coverage of CHAR output changes in the 'BUG FIXES' section.  In a
      nutshell:  CHAR output values no longer have trailing NULL bytes.

-----------------------------------------------------------------------------
3.0.1_pre1 versus 3.0
-----------------------------------------------------------------------------
  NEW FEATURES:
    - It is now possible to connect to a database under a specific role by using
      the 'role' keyword argument of the kinterbasdb.connect function.

    - The following methods now accept any sequence except a string for their
      'parameter' argument, rather than demanding a tuple:  Cursor.execute,
      Cursor.executemany and Cursor.callproc.


  BUG FIXES:
    - kinterbasdb supports IB 5.x again.
        Various identifiers specific to IB 6.x/Firebird had crept into unguarded
      areas of __init__.py and _kinterbasdb.c, but this has been changed so
      that kinterbasdb compiles gracefully with IB 5.x.
        See:
      http://sourceforge.net/tracker/index.php?func=detail&aid=553184&group_id=9913&atid=209913

    - The distutils setup script no longer raises a ValueError on Windows 2000
      or XP.

    - The precision slot in Cursor.description was always zero.  It now contains
      the correct value if that value can reasonably be determined.
        Note that the database engine records the precision of some fields as
      zero (e.g., FLOAT), and the slot will also be zero in cases where the
      database engine does not expose the precision of the field (e.g., dynamic
      fields such as "SELECT 33.5 FROM RDB$DATABASE").
        Since the database API does not provide the field's precision figure in
      the XSQLVAR structure, it is necessary to query the system tables.  In
      order to minimize the performance hit, precision figures are cached per
      Connection; the determination of a given field's precision figure in the
      context of a given Connection will require only dictionary lookups after
      it is determined the first time with a system table query.
        An unfortunate side effect of this caching is that if a field's
      precision is altered after the figure has been cached in by a Connection,
      cursors based on that Connection will still show the old precision figure.
      In practice, this situation will almost never arise.
        See:
      http://sourceforge.net/tracker/index.php?func=detail&aid=549982&group_id=9913&atid=109913

    - On Linux, attempting to fetch immediately after having executed a
      non-query statement resulted in a segfault.  An exception is now raised
      instead.  The problem did not afflict Windows, which always raised the
      exception.
        See:
      http://sourceforge.net/tracker/index.php?func=detail&aid=551098&group_id=9913&atid=109913

      - The message carried by this exception grew without bound in on both
        Windows and Linux.  It no longer does.

    - Under some circumstances, the fetched values of CHAR fields were
      incorrect.  CHAR values now appear as expected (they are left-padded with
      spaces and always of length equal to their field's designated maximum
      length).

    - Cursor.fetchmany raised an error if there were no remaining values to
      fetch.  It now returns an empty sequence instead, as required by the DB
      API Specification.

    - Field domains are checked more strictly.  It is now impossible to (for
      example) issue a statement that attempts to insert a 12-character string
      into a 10-character CHAR field without encountering an exception.
        This checking is not perfect, since it validates against the field's
      internal storage type rather than the field's declared type.  For example,
      a NUMERIC(1,1), which is stored internally as a short, will erroneously
      accept the value 12.5 because 125 fits in a short.

    - When operating in imprecise mode (connection.precision_mode == 0),
      kinterbasdb 3.0 sometimes interpreted integer values as though it were
      operating in precise mode.


-----------------------------------------------------------------------------
3.0 versus 2.0-0.3.1
-----------------------------------------------------------------------------
  NEW FEATURES:
    The new features are thoroughly documented in the KInterbasDB Usage Guide
  (usage.html); they need not be reiterated here.
    However, backward-incompatible changes *have* been documented in this
  changelog (see the BACKWARD-INCOMPATIBILITIES section).

  BUG FIXES:
    Many bugs have been fixed, including (but not limited to) the following,
    which were registered with the KInterbasDB bug tracker at SourceForge
    ( http://sourceforge.net/tracker/index.php?group_id=9913&atid=109913 ):

      - 433090  cannot connect to firebird server
      - 438130  cursor.callproc not adding param code
      - 468304  fetchmany return all record
      - 498086  ignores column aliases in select
      - 498403  fetching after a callproc hangs program
      - 498414  execute procedure message length error
      - 505950  inconsistent fetch* return types
      - 515974  Wrong decoding of FB isc_version
      - 517093  broken fixed-point handling in 3.0
      - 517840  C function normalize_double inf. loop
      - 517842  fetch bug - program hangs
      - 520793  poor DB API compliance
        ^ a *BIG* fix that entailed many changes
      - 522230  error with blobs larger than (2^16) - 1
      - 522774  inconsistent fixed-point conv in 3.0-rc2
      - 523348  memory leak in Blob2PyObject

      - immediate execution facilities unreliable in 2.x

  BACKWARD-INCOMPATIBILITIES:
      As a result of the changes required for some of the bugfixes (especially
    #520793 - "poor DB API compliance") and general reengineering, several
    areas of backward-incompatibility have arisen:

      - fetch* return types
          The standard fetch(one|many|all) methods now return just a sequence,
        not a combined sequence/mapping.  If you want a mapping, use one of
        the fetch(one|many|all)map methods.
          Note the "'absolutely no guarantees' except..." caveats in the
        KInterbasDB Usage Guide regarding the return types of the
        Cursor.fetch* methods and the contents of the Cursor.description
        attribute.
          This is a significant backward-incompatibility, and was not
        undertaken without serious consideration (for evidence see
        http://sourceforge.net/forum/forum.php?thread_id=622782&forum_id=30919
        ).

      - Fixed point number handling
          Fixed point number handling has been remodelled.  By default, fixed
        point numbers (NUMERIC/DECIMAL field values) are now represented
        (with a potential loss of precision) as Python floats.
          A Connection.precision_mode attribute has been added so that precise
        representation of fixed point values as scaled Python integers (as in
        KInterbasDB 2.x) can be used at will.
          For more information, see the KInterbasDB Usage Guide.

      - Connection.dialect
          In KInterbasDB 2.x, the default connection dialect was 1 (the
        backward-compatibility dialect for use with Interbase 5.5 and earlier).
          KInterbasDB 3.0 is being released into quite a different climate.
        Interbase 6.0 was released nearly two years ago, and Firebird 1.0 has
        recently been released.  Because it is expected that KInterbasDB 3.0
        will be used most frequently with Interbase 6.0+ and Firebird, the
        default connection dialect is 3.
          Using KInterbasDB 3.0 with Interbase 5.5 and earlier is still
        possible, though untested by the developers of KInterbasDB 3.0.  See
        the Connection.dialect documentation in the KInterbasDB Usage Guide
        for an explanation of how to initialize a connection with a dialect
        other than 3.

      - Connection.server_version
          The Connection.server_version attribute is now a string rather than
        an integer.  An integer simply was not expressive enough to represent
        the numerous Interbase variants that exist today (including Firebird,
        which does not fit neatly into the Interbase version progression).
          For more information, see the KInterbasDB Usage Guide.

      - kinterbasdb.execute_immediate
          The kinterbasdb.execute_immediate function has been removed.  A
        similar function named kinterbasdb.create_database has been added.
        The primary differences between kinterbasdb.execute_immediate and
        kinterbasdb.create_database are:
          - kinterbasdb.create_database is not as general
          - kinterbasdb.create_database actually works

          The execute_immediate method of the Connection class has been
        retained.
          For more information, see the KInterbasDB Usage Guide.
-----------------------------------------------------------------------------