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 (April 4, 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.


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.
