5e79f7228e
* BUG: Fix the GB_COMPONENT() macro so that it defines XXX_LDFLAGS and XXX_LIB variables as in the GB_COMPONENT_PKG_CONFIG() macro. The Makefile.am files of components were fixed accordingly. [GB.DB.FIREBIRD] * NEW: Switch to ibpp 2.5.3.1. * BUG: Link the driver to the fbclient library. [GB.GTK] * NEW: TreeView.Item.ParentKey and ColumnView.Item.ParentKey were implemented. [GB.QT] * NEW: TreeView.Item.ParentKey and ColumnView.Item.ParentKey were implemented. [GB.QT4] * NEW: TreeView.Item.ParentKey and ColumnView.Item.ParentKey were implemented. The previous change incorrectly talked about TreeView.ParentKey and ColumnView.ParentKey. git-svn-id: svn://localhost/gambas/trunk@2066 867c0c6c-44f3-4631-809d-bfa615b0a4ec
343 lines
16 KiB
Plaintext
343 lines
16 KiB
Plaintext
$Id: releasenotes.txt 75 2006-05-12 08:40:41Z epocman $
|
|
|
|
IBPP, A C++ Client API for Firebird (and Interbase)
|
|
Some general notes about the ibpp project
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
(C) Copyright 2000-2006 T.I.P. Group S.A. and the IBPP Team (www.ibpp.org)
|
|
|
|
The contents of this file are subject to the IBPP License (the "License");
|
|
you may not use this file except in compliance with the License. You may
|
|
obtain a copy of the License at http://www.ibpp.org or in the 'license.txt'
|
|
file which must have been distributed along with this file.
|
|
|
|
This software, distributed under the License, is distributed on an "AS IS"
|
|
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing rights and limitations
|
|
under the License.
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
CALL FOR CONTRIBUTORS
|
|
If you have an interest in using such a non-visual, C++ based interface to
|
|
Firebird or Interbase in your projects, and are willing to build on this,
|
|
contact me to get involved : om@tipgroup.com, or subscribe to and write to
|
|
the list :
|
|
|
|
ibpp-discuss@lists.sourceforge.net
|
|
|
|
To subscribe and later update your lists settings or unsubscribe, please
|
|
visit http://lists.sourceforge.net/mailman/listinfo/ibpp-discuss
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
DOCUMENTATION
|
|
The documentation is currently only available online on the project
|
|
website at http://www.ibpp.org.
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
Release Notes for Version 2.5 (May 12, 2006)
|
|
|
|
|
|
1/ Introduction
|
|
|
|
IBPP, where 'PP' stands for '++', is a C++ client interface for Firebird Server
|
|
versions 1.0, 1.5 and further. It also works with InterBase(r) 6.0, though it is
|
|
expected it might only support Firebird in the future. It is a class library,
|
|
free of any specific development tool dependancies. It is not tied to any
|
|
'visual' or 'RAD' tool. It was indeed developed to add Firebird access in any
|
|
C++ application. Those applications using IBPP can be non-visual (CORBA/COM
|
|
objects, other libraries of classes and functions, procedural 'legacy' code, for
|
|
instance). But it can of course also be used in visual or RAD environments. IBPP
|
|
is indeed purely a dynamic SQL interface to Firebird. In some easy to use C++
|
|
classes, you will find nearly all what is needed to access a Firebird database,
|
|
and manipulate the data. IBPP also offers access to most of the administrations
|
|
tasks : creating a database, modifying its structure, performing online backups,
|
|
administering user accounts on the server and so on.
|
|
|
|
More background information on http://www.ibpp.org website.
|
|
This website now holds full reference documentation.
|
|
|
|
|
|
2/ Installation
|
|
|
|
There is no 'installation' per se because IBPP Project does not release
|
|
binaries. It is much better / safer that you adjust your own programs build
|
|
procedures to integrate the 'core' files of IBPP straight into your own
|
|
productions. Please refer to the file howtobuild.txt from this distribution
|
|
for more complete instructions on how to do so.
|
|
|
|
|
|
3/ New or Updated Features since Version 2.4
|
|
|
|
- Completely reworked the concepts of how to build IBPP : embed it in your
|
|
own code and build procedure. See howtobuild.txt for details.
|
|
|
|
- Changed and enhanced the Service::AddUser, Service::ModifyUser and
|
|
Service::GetUsers to use the new IBPP::User helper class. This breaks the
|
|
backward compatibility of these 3 APIs. Though not the best thing to do, it was
|
|
considered an acceptable mistake because these APIs are typically not called
|
|
much from user code. The required update is easy and should not be too big.
|
|
|
|
- Added std::string& Statement::Sql() to return the last prepared/executed SQL
|
|
statement.
|
|
|
|
- When Statement Get() and Set() face an incompatible type situation, the
|
|
exception report has been enhanced to show the two conflicting types (the SQL
|
|
column type and the variable data type).
|
|
|
|
- Added exception class 'WrongType' derived from 'LogicException' to support
|
|
the above.
|
|
|
|
- Added comfort methods to classed Date and Time (Year(), ..., Hours(), ...)
|
|
|
|
- Removed all access to the naked interface pointers from the public interface
|
|
except through the Ptr<>::intf() method. Some methods overloads taking naked
|
|
pointers have been dropped, only their versions using managed pointers subsists.
|
|
This can break source code compatibility of *some* applications, but is a very
|
|
easy fix to do in those applications source code.
|
|
|
|
- Full MSVC6 compatibility which got partially lost in 2.4 versions has been
|
|
revived.
|
|
|
|
- Now, NUMERIC/DECIMAL (scaled columns) can be exchanged with integer data
|
|
types. The plain scaled value is returned / expected.
|
|
|
|
- Complete rewrite of all the events handling system.
|
|
There is new first class citizen IBPP::Events. Events holds a set of events
|
|
related to a specific instance of a connected Database.
|
|
An application can register multiple sets of events on a same Database
|
|
connection. Of course this change is completely source code incompatible
|
|
with previous versions. Essentially, the changes only involve obtaining
|
|
an Events object through EventsFactory(Database&, bool async).
|
|
Then to replace previous methods calls as such:
|
|
Database::DefineEvent --> Events::Add
|
|
Database::DropEvent --> Events::Drop
|
|
Database::ClearEvents --> Events::Clear
|
|
Database::DispatchEvents --> Events::Dispatch
|
|
The upgrade path is then nearly trivial.
|
|
|
|
- When IBPP attempts to load the FBCLIENT.DLL (Win32) from specific directories
|
|
(either as reported by the FB 1.5/2.0 registry keys or through the indirect
|
|
use of ClientLibSearchPaths), IBPP now alters the host process private PATH
|
|
environment variable to add the directory from where the load is attempted.
|
|
This helps windows find local copies of Microsoft runtime libraries when
|
|
those are installed locally along with the Firebird binaries but not
|
|
generally available in the system paths.
|
|
|
|
|
|
4/ Comments, Acknowledgments
|
|
|
|
This 2.5 version is considered the best IBPP version available to date and we
|
|
recommend all its users to upgrade at their earliest opportunity.
|
|
|
|
We have a lot of people to thank. The ibpp.h file cites some of them. But many
|
|
people suggested various kind of enhancements or were invaluable for their
|
|
mentoring or expertise in various fields.
|
|
|
|
|
|
5/ History section - What was New or Updated between Version 2.3 and 2.4
|
|
|
|
Version 2.4 was initially meant essentially as a maintenance version. We chose
|
|
to tag it 2.4 instead of 2.3.6 mostly because of the exception classes changes
|
|
and the blob interfaces extensions which both changed the public API
|
|
significantly in some areas.
|
|
|
|
Though, in a second stage, the source code received numerous additional fixes
|
|
and additions, not the least of them being that IBPP 2.4 is now ready for
|
|
64 bits environments, wether LP64 on many unixes or LLP64 on Windows64.
|
|
|
|
- Exception handling revision. There is now IBPP::Exception as a base class.
|
|
SQLException specialization is thrown as result of an engine reported runtime
|
|
error. LogicException specialization is thrown in all other cases.
|
|
|
|
std::exception
|
|
|
|
|
IBPP::Exception
|
|
/ \
|
|
IBPP::LogicException IBPP::SQLException
|
|
|
|
- Change in the interface definition of methods using or returning integers.
|
|
The ibpp.h now uses the C99 standard (section 7.18) exact precision types which
|
|
are defined by including the stdint.h header. This is perfectly fine using all
|
|
compilers on which IBPP is maintained, except for one. Guess which one? Yes,
|
|
MSVC does not supply that header nor those typedefs in any other file. The
|
|
solution is simple, ibpp.h does some typedef in case of the MSVC compilers.
|
|
|
|
- Extended the Statement::Set() and Statement::Get() in regards to blobs and
|
|
std::string. Now one can directly Get(3, str) where str is a std::string and
|
|
the column at hands is a blob. The blob is retrieved and stored to the string.
|
|
The reverse is true for Set(3, str) where str is a std::string. It will be
|
|
stored directly. For simple case useages, this allows to bypass the useage of
|
|
any IBPP::Blob intermediate objects and, unless finer control is required
|
|
(which Create/Open/Write/Read/Close offer), it it much simpler to use blobs
|
|
from application code. Also, remember that std::string can store arbitrary
|
|
binary data which might contain one or multiple values 0. So this std::string
|
|
interface for blobs really has some potential.
|
|
|
|
- Added methods Save(const std::string&) and Load(std::string) to class Blob.
|
|
Those methods allow to easily read and write a full blob using a std::string.
|
|
A Save(), is the equivalent of Create(), a loop of Write(), and Close().
|
|
A Load(), is the equivalent of Open(), a loop of Read(), and Close(). Adding
|
|
this interface on IBPP::Blob was logical now that IBPP::Statement had a direct
|
|
support for blobs and std:string.
|
|
|
|
- Added void ClientLibSearchPaths(const std::string&);
|
|
On Win32 platform, ClientLibSearchPaths() allows to setup one or multiple
|
|
additional paths (separated with a ';') where IBPP will look for the client
|
|
library (before the default implicit search locations). This is usefull for
|
|
applications distributed with a 'private' copy of Firebird, when the registry
|
|
is useless to identify the location from where to attempt loading the
|
|
fbclient.dll / gds32.dll. If called, this function must be called *early* by
|
|
the application, before *any* other function or object methods of IBPP. This
|
|
is currently a NO-OP on platforms other than Win32.
|
|
|
|
- Changed the date / time / timestamp support in order to get access to the sub-second
|
|
precision, which is defined in ten thousandths of seconds in IB and FB.
|
|
The operator int() has been dropped and replaced by methods GetDate() and GetTime().
|
|
The method GetTime() can take an optional fourth parameter to get the sub-seconds.
|
|
Same for method SetTime(). This is true for classes Time and Timestamp.
|
|
Be warned that the GetTime() method which replaces the dropped operator int()
|
|
returns the number of ten-thousandths of seconds elapsed since midnight instead
|
|
of the number of seconds as before. So that integer time value is now 10000
|
|
times larger than before. Existing code relying on the old operator int() will
|
|
have to be updated to divide the return value by 10000. Of course, the same
|
|
is true for SetTime(int) : if you used to pass a count of seconds there, you
|
|
need to multiply it by 10000.
|
|
|
|
- Added int Statement::GetSubtype(int) returning, for a Blob column only, the subtype
|
|
of the Blob as it is declared in the database metadata.
|
|
|
|
- Added Database::DropEvent(const std::string&) to drop interest in a previously
|
|
registered event (using Database::DefineEvent()).
|
|
|
|
- An IBPP::Row has been introduced and the code refactored around it. This is
|
|
perfectly functionnal but is still a concept in the works for this 2.4 release.
|
|
So we ask users of IBPP not to start using IBPP::Row as is, consider it already
|
|
deprecated in its current form. We will introduce something 'bigger' in the
|
|
next major version (3.0).
|
|
|
|
6/ History section - What was New or Updated between Version 2.2 and 2.3
|
|
|
|
- The Service interface now support sweep action. See ibpp.h for details:
|
|
virtual void Sweep(const std::string& dbfile) = 0;
|
|
|
|
- Added void Statement::Plan(std::string&) to retrieve the plan after a prepare.
|
|
|
|
- Added Service::ListUsers() to retrieve the full list of usernames defined in
|
|
the security database.
|
|
|
|
- Added 'bool Connected(void)' methods to Database and Service class.
|
|
|
|
- Added 'bool Started(void)' method to Transaction class.
|
|
|
|
- Firebird 1.5 is specifically supported. Further, on Win32, the way IBPP looks
|
|
for and loads the client library has been slightly updated:
|
|
|
|
1. Looks for fbembed.dll in host application directory.
|
|
2. Looks for fbclient.dll in host application directory.
|
|
3. Looks for fbclient.dll through 'DefaultInstance' registry key/value.
|
|
4. Looks for fbclient.dll in system defined locations.
|
|
5. Looks for gds32.dll in system defined locations.
|
|
The DLL loaded is the first one found folllowing above order.
|
|
|
|
- Added new overloads to the set of Statement::Get() methods. These overloads
|
|
use references to basic data types instead of pointers to such (bool, short,
|
|
int, long, int64_t, float, double). Of course, not only the previous interfaces
|
|
are maintained for compatibility, but we don't see any reason to deprecate them
|
|
in the future.
|
|
|
|
- Now can be compiled and used on 'Darwin'. Some very small fixups were required.
|
|
|
|
- There is a set of solution and project files for users of Microsoft Visual
|
|
Studio .NET 2003. All is required is to open the 'ibpp.sln' and then hit build.
|
|
|
|
|
|
7/ History section - What was New or Updated between Version 2.1 and 2.2
|
|
|
|
- Dates valid range has been extended, both in the Date and Timestamp classes.
|
|
IBPP now fully support the range extending from 1 JAN 0001 to 31 DEC 9999. The
|
|
utility functions dtoi and itod now return a bool to signal a date as valid or
|
|
invalid.
|
|
|
|
bool dtoi (int date, int *y, int *m, int *d);
|
|
bool itod (int* pdate, int year, int month, int day);
|
|
|
|
- The Transaction interface fully support special lock reservation options
|
|
through new optional flags. See ibpp.h for details :
|
|
|
|
enum TTR {trSharedWrite, trSharedRead,
|
|
trProtectedWrite, trProtectedRead};
|
|
|
|
enum TFF {tfIgnoreLimbo = 0x1, tfAutoCommit = 0x2, tfNoAutoUndo = 0x4};
|
|
|
|
ITransaction* TransactionFactory(IDatabase* db, TAM am = amWrite,
|
|
TIL il = ilConcurrency, TLR lr = lrWait, TFF flags = TFF(0));
|
|
|
|
virtual void AddReservation(IDatabase* db,
|
|
const std::string& table, TTR tr) = 0;
|
|
|
|
- The Service interface now fully support special backup/restore options through
|
|
new optional flags. See ibpp.h for details :
|
|
|
|
enum BRF {
|
|
brVerbose = 0x1,
|
|
// Backup flags
|
|
brIgnoreChecksums = 0x100, brIgnoreLimbo = 0x200,
|
|
brMetadataOnly = 0x400, brNoGarbageCollect = 0x800,
|
|
brNonTransportable = 0x1000, brConvertExtTables = 0x2000,
|
|
// Restore flags
|
|
brReplace = 0x10000, brDeactivateIdx = 0x20000,
|
|
brNoShadow = 0x40000, brNoValidity = 0x80000,
|
|
brPerTableCommit = 0x100000, brUseAllSpace = 0x200000
|
|
};
|
|
virtual void StartBackup(const std::string& dbfile,
|
|
const std::string& bkfile, BRF flags = BRF(0)) = 0;
|
|
virtual void StartRestore(const std::string& bkfile, const std::string& dbfile,
|
|
int pagesize = 0, BRF flags = BRF(0)) = 0;
|
|
|
|
- The Service interface now support repair actions, with a range of new optional
|
|
flags. See ibpp.h for details :
|
|
|
|
enum RPF
|
|
{
|
|
// Mandatory and mutually exclusives
|
|
rpMendRecords = 0x1, rpValidatePages = 0x2, rpValidateFull = 0x4,
|
|
// Options
|
|
rpReadOnly = 0x100, rpIgnoreChecksums = 0x200, rpKillShadows = 0x400
|
|
};
|
|
virtual void Repair(const std::string& dbfile, RPF flags) = 0;
|
|
|
|
- The Service interface has a new member to get the version string from the
|
|
server :
|
|
|
|
virtual void GetVersion(std::string& version) = 0;
|
|
|
|
- Some statistical and informational methods of Database interface have been fully
|
|
revised and now offer :
|
|
|
|
virtual void Info(int* ODS, int* ODSMinor, int* PageSize, int* Pages,
|
|
int* Buffers, int* Sweep, bool* Sync, bool* Reserve) = 0;
|
|
virtual void Statistics(int* Fetches, int* Marks,
|
|
int* Reads, int* Writes) = 0;
|
|
virtual void Counts(int* Insert, int* Update, int* Delete,
|
|
int* ReadIdx, int* ReadSeq) = 0;
|
|
|
|
- The Database interface method DropEvent() has been dropped. It was never
|
|
implemented since year 2000 and its implementation would have introduced
|
|
unnecessary complications to work around some silly race conditions.
|
|
|
|
- Build support has been added for the Digital Mars C++ Compiler
|
|
(http://www.digitalMars.com).
|
|
|
|
- NULL macro has been dropped from the source code as this is not actually part
|
|
of the C++ Standard.
|
|
|
|
- Useage of '_' (underscore) as a leading character in internal identifiers of
|
|
the library has been dropped. Such naming convention is reserved for
|
|
implementation and thus may clash with system defined identifiers.
|
|
|
|
>>> EOF <<<
|