====== IBPP::Database ======
The IBPP::Database Interface represents a single connection to a database. Along with IBPP::[[Transaction]] and IBPP::[[Statement]], it is the core of IBPP. You need at least one instance of each to do anything against the data stored in a database.

===== Definition ======

See the file ibpp.h for an up-to-date definition of the interface. Lookup the IDatabase class.

Like the other building blocks of IBPP, the actual interface class is a pure virtual class (here named IBPP::IDatabase). This is the closest thing in C++ to a pure interface concept. The real working object 'behind' (IBPP internals) is derived from this 'contract' class. As long as the signature of this IDatabase class does not change, your code is binary compatible with IBPP, even if internal details of the real work-class behind have changed.

As with other IBPP building blocks, you cannot instantiate this class by yourself (due to its pure virtual methods). You also can't derive your own class from this one, due to the protected constructor and destructor. You have to get an instance from IBPP through the corresponding Factory function call.

===== DatabaseFactory =====

The DatabaseFactory is used to build and get access to a Database object.

<code>
Database DatabaseFactory(const std::string& ServerName,
	const std::string& DatabaseName, const std::string& UserName,
		const std::string& UserPassword, const std::string& RoleName,
			const std::string& CharSet, const std::string& CreateParams);

Database DatabaseFactory(const std::string& ServerName,
	const std::string& DatabaseName, const std::string& UserName,
		const std::string& UserPassword);
</code>

===== Database members =====

==== void Connect() ====

Connects to the database, using the strings provided on the DatabaseFactory call.

==== bool Connected() ====

Returns true if the Database object is currently attached to a database.

==== void Inactivate() ====

Rollback any uncommitted [[transaction]]. Detach from any related object. But does not disconnect the attachment to the database. The connection is now exactly in the same state as when it was first instantiated then connected (before it was used with any [[transaction]] or [[statement]]). This is rarely used and was only provided for handling special cases. There is no activate counterpart to this method. All you need to do to continue using this connection, is to instantiate new transactions and statements.

==== void Disconnect() ====

Rollback any uncommitted [[transaction]] and completely disconnects from the database. Disconnect() does the same thing as Inactivate() plus it actually disconnects from the database.

==== void Create(int dialect) ====

Creates a database. It will fail if there are active connections to an existing database of the same name. It will also fail if one of the physical files meant to contain the database already exists. The dialect should be 1 or 3, typically 3 for the current dialect of Firebird. The value 1 is meant only to provide a special compatibility mode for InterBase 5 databases. Please refer to Firebird and InterBase documentation.

==== void Drop() ====

Drops (delete) a database. Fails if there are other active connections, else will forcibly remove the database from the server. The database is destroyed (its files are actually deleted) and of course unrecoverable (unless you can restore a backup). Use with care.

==== void Info(int* ODS, int* ODSMinor, int* PageSize, int* Pages, int* Buffers, int* Sweep, bool* Sync, bool* Reserve) ====

Queries and returns some information about the connected database. ODS & ODSMinor are the On Disk Structure version major and minor numbers. PageSize is the database page size. Pages is the current of pages allocated. Buffers is the number of page buffers allocated. Sweep is the current sweep interval. Sync is a bool showing if this database is currently using the Forced Writes mode (true) or not. Reserve is a bool telling you if the space reservation mechanism is turned on or not. All these parameters are pointers which can be passed NULL if the corresponding value is not needed. See Firebird documentation for more information on all these counters.

==== void Statistics(int* Fetches, int* Marks, int* Reads, int* Writes) ====

Queries and returns some statistical information about the current connection. Fetches, Marks, Reads and Writes are statistical counters interesting in benchmarks and tests procedures. All these parameters are pointers which can be passed NULL if the corresponding value is not needed. See Firebird documentation for more information on all these counters.

==== void Counts(int* Insert, int* Update, int* Delete, int* ReadIdx, int* ReadSeq) ====

Queries and returns some statistical information about the current connection. Insert, Update, Delete are the count of such operations done through this Database attachment, since it was connected. ReadIdx and ReadSeq are the count of reads through indexes or direct that happened since the connection. All these parameters are pointers which can be passed NULL if the corresponding value is not needed. See Firebird documentation for more information on all these counters.

==== void Users(std::vector<std::string>& Users) ====

The user supplied vector of strings is filled with the list of user names currently connected to this database. At least the current user will get listed.

==== int Dialect() ====

Returns the dialect level of the database. Typical values are 1 and 3.

==== const char* ServerName() ====

Read access to the server name set by calling DatabaseFactory.

==== const char* DatabaseName() ====

Read access to the database name set by calling DatabaseFactory.

==== const char* Username() ====

Read access to the username set by calling DatabaseFactory.

==== const char* UserPassword() ====

Read access to the user password set by calling DatabaseFactory.

==== const char* RoleName() ====

Read access to the role name set by calling DatabaseFactory.

==== const char* CharSet() ====

Read access to the character set string set by calling DatabaseFactory.

==== const char* CreateParams() ====

Read access to the create parameters set by calling DatabaseFactory.

====== Some Examples ======

===== Creating a database =====

<code>
IBPP::Database db;
db = IBPP::DatabaseFactory(ServerName, DbName, UserName, Password,
        "", "", "PAGE_SIZE = 4096");
db->Create();
// Here, the db is created but not connected.
db->Connect();
...
</code>

===== Dropping (deleting) a database =====

<code>
IBPP::Database db;
db = IBPP::DatabaseFactory(ServerName, DbName, UserName, Password);
db->Connect();
db->Drop();
// Here the db is disconnected (of course as it is deleted!)
...
</code>