ppl7::db::Database Klassenreferenz

Basisklasse für verschiedene Datenbanken. Mehr ...

Basisklasse für ppl7::db::MySQL, ppl7::db::PostgreSQL und ppl7::db::SQLite.

Öffentliche Methoden
	Database ()
	Konstruktor der Klasse. Mehr ...
virtual	~Database ()
	Destruktor der Klasse. Mehr ...
virtual void	cancelTransaction ()
	Letzte Transaktion abbrechen. Mehr ...
virtual void	cancelTransactionComplete ()
	Transaktion vollständig abbrechen. Mehr ...
virtual void	close ()
	Verbindung zu Datenbank trennen. Mehr ...
virtual void	connect ()
	Connect auf eine Datenbank erstellen. Mehr ...
virtual void	connect (const AssocArray &params)
	Connect auf eine Datenbank erstellen. Mehr ...
virtual void	connectCreate (const AssocArray &params)
	Connect zum Server aufbauen und Datenbank anlegen. Mehr ...
ppluint64	count (const String &table, const String &where=String())
virtual void	createDatabase (const String &name)
	Datenbank erstellen. Mehr ...
virtual String	databaseType () const
	Typ der Datenbank. Mehr ...
virtual void	endTransaction ()
	Transaktion beenden. Mehr ...
virtual String	escape (const String &str) const
	String escapen. Mehr ...
virtual void	exec (const String &query)
	SQL-Query ohne Ergebnis ausführen. Mehr ...
AssocArray	execArray (const String &query)
	SQL-Query ausführen und ersten Datensatz als Array zurückgeben. Mehr ...
void	execArray (AssocArray &result, const String &query)
	SQL-Query ausführen und ersten Datensatz in Array speichern. Mehr ...
AssocArray	execArrayAll (const String &query)
	SQL-Query ausführen und alle Datensätze in Array speichern. Mehr ...
void	execArrayAll (AssocArray &result, const String &query)
	SQL-Query ausführen und alle Datensätze in Array speichern. Mehr ...
AssocArray	execArrayAllf (const char *query,...)
	SQL-Query bauen, ausführen und alle Datensätze in Array speichern. Mehr ...
void	execArrayAllf (AssocArray &result, const char *query,...)
	SQL-Query bauen, ausführen und alle Datensätze in Array speichern. Mehr ...
AssocArray	execArrayf (const char *query,...)
	SQL-Query bauen, ausführen und ersten Datensatz als Array zurückgeben. Mehr ...
void	execArrayf (AssocArray &result, const char *query,...)
	SQL-Query bauen, ausführen und ersten Datensatz in Array speichern. Mehr ...
void	execf (const char *query,...)
	Ergebnislosen SQL-Query anhand eines Formatierungsstrings bauen und ausführen. Mehr ...
virtual ppluint64	getAffectedRows ()
	Betroffene Zeilen. Mehr ...
Logger *	getLogger ()
	Pointer auf den konfigurierten Logger zurückgeben. Mehr ...
virtual String	getQuoted (const String &value, const String &type=String()) const
	Wert Datenbank-konform quoten. Mehr ...
virtual bool	ping ()
	Erreichbarkeit der Datenbank prüfen. Mehr ...
virtual ResultSet *	query (const String &query)
	SQL-Query mit Ergebnis ausführen. Mehr ...
ResultSet *	queryf (const char *query,...)
	SQL-Query mit Ergebnis ausführen. Mehr ...
virtual void	reconnect ()
	Verlorene Datenbank-Verbindung wieder herstellen. Mehr ...
void	removeLogger ()
	Querylog deaktivieren. Mehr ...
virtual void	selectDB (const String &databasename)
	Aktive Datenbank auswählen. Mehr ...
void	setLogger (Logger &logger)
	Querylog aktivieren. Mehr ...
void	setParam (const String &name, const String &value)
	Parameter für den Connect setzen. Mehr ...
void	setParam (const String &name, int value)
	Parameter für den Connect setzen. Mehr ...
void	setParam (const AssocArray &params)
	Parameter für den Connect setzen. Mehr ...
virtual void	startTransaction ()
	Transaktion starten. Mehr ...

Geschützte Methoden
void	clearLastUse ()
	Timestamps auf 0 setzen. Mehr ...
void	logQuery (const String &query, float duration)
	Interne Funktion zum Loggen von Queries. Mehr ...
void	updateLastPing ()
	Uhrzeit der letzten Datenbank-Kommunikation aktualisieren. Mehr ...
void	updateLastUse ()
	Uhrzeit der letzten Datenbank-Verwendung aktualisieren. Mehr ...

Private Attribute
AssocArray	ConnectParam
ppluint64	lastping
ppluint64	lastuse
Logger *	Log

Freundbeziehungen
class	MultiPool
class	SinglePool

Ausführliche Beschreibung

Include:

#include <ppl7-db.h>

Beschreibung:

Die Klasse Database ist eine abstrakte Basisklasse, von der die eigentliche Datenbank-spezifische Implementierung abgeleitet wird. Sie enthält neben rein virtuellen Funktionen, deren Implementierung in der abgeleiteten Klasse erfolgen muss, auch Funktionen, die Datenbank-unabhängig sind.

Die Klasse kann nicht direkt instanziiert werden, stattdessen sollte immer die jeweilige Datenbank-Klasse (siehe MySQL, SQLite, Postgres) oder die Funktion ppl7::db::Connect verwendet werden.

Beispiel: Verwendung der Funktion "ConnectDatabase"

int DB_Example1() {
    ppl6::CAssocArray param;
    param.Set("type","mysql");
    param.Set("host","db.pfp.de");
    param.Set("port","3306");
    param.Set("user","patrick");
    param.Set("password","xxxxxxx");
    param.Set("dbname","test");

    ppl6::db::Database *db=ppl6::db::Connect(param);
    if (!db) {
        ppl6::PrintError();
        return 0;
    }
} // EOF

Beispiel: Verwendung der Klasse "MySQL"

int DB_Example3() {
    ppl6::CAssocArray param;
    param.Set("host","db.pfp.de");
    param.Set("port","3306");
    param.Set("user","patrick");
    param.Set("password","xxxxxxx");
    param.Set("dbname","test");
    ppl6::db::MySQL db;
    if (!db.Connect(param)) {
        ppl6::PrintError();
        return 0;
    }
} // EOF

Beschreibung der Konstruktoren und Destruktoren

ppl7::db::Database::Database

(

)

Beschreibung:

Konstruktor der Klasse

ppl7::db::Database::~Database ( )

virtual

Beschreibung:

Destruktor der Klasse.

Dokumentation der Elementfunktionen

void ppl7::db::Database::cancelTransaction ( )

virtual

Beschreibung:

Mit diesem Befehl wird die letzte mit Database::StartTransaction begonnene Transaktion abgebrochen. Alle darin enthaltenen Änderungen sind unwirksam und werden nicht gespeichert.

Rückgabe

Bei Erfolg gibt die Funktion 1 zurück, im Fehlerfall 0

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

void ppl7::db::Database::cancelTransactionComplete ( )

virtual

Beschreibung:

Mit diesem Befehl wird die komplette Transaktion bis zur obersten Ebene zurückgerollt. Alle darin enthaltenen Änderungen sind unwirksam und werden nicht gespeichert.

Rückgabe

Bei Erfolg gibt die Funktion 1 zurück, im Fehlerfall 0

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

void ppl7::db::Database::clearLastUse ( )

protected

Beschreibung:

Die Werte Database::lastping und Database::lastuse werden auf 0 gesetzt. Die Methode wird aufgerufen, wenn die Verbindung zur Datenbank getrennt wird.

void ppl7::db::Database::close ( )

virtual

Beschreibung:

Mit diesem Befehl wird die Verbindung zur Datenbank getrennt. Zu diesem Zeitpunkt sollten keine Query- Results (ppl6::db::Result) mehr vorhanden sein, die mit diesem Datenbank-Connect erstellt wurden. Es könnte sonst zu Fehlern kommen.

Rückgabe

Die Funktion liefert 1 zurück, wenn die Verbindung zur Datenbank erfolgreich getrennt wurde, im Fehlerfall 0.

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

void ppl7::db::Database::connect ( )

virtual

Beschreibung:

Mit dieser Funktion wird eine Verbindung zu einem Datenbank-Server hergestellt. Die dafür erforderlichen Parameter müssen zuvor mit der Funktion Database::setParam gesetzt worden sein.

Beispiel:

Bei dem nachfolgenden Beispiel wird eine MySQL-Datenbank verwendet.

int DB_Example2() {
    ppl6::db::MySQL db;
    db.SetParam("host","db.pfp.de");
    db.SetParam("port","3306");
    db.SetParam("user","patrick");
    db.SetParam("password","xxxxxxx");
    db.SetParam("dbname","test");

    if (!db.Connect()) {
        ppl6::PrintError();
        return 0;
    }
} // EOF

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

void ppl7::db::Database::connect ( const AssocArray &  params )

virtual

Beschreibung:

Mit dieser Funktion wird eine Verbindung zu einem Datenbank-Server hergestellt, wobei die dafür notwendigen Parameter dem Array params entnommen werden.

Die für den Connect erforderlichen oder optionalen Parameter hängen von der jeweiligen Datenbank ab und sind in der jeweiligen Dokumentation zu finden. Es gibt jedoch eine Reihe von Parametern, die bei allen Datenbanken identisch sind:

• host: Der Hostname oder die IP-Adresse des Datenbank-Servers
• port: Der TCP-Port des Datenbank-Servers
• dbname: Der Name der intialen Datenbank. Dieser Parameter kann optional sein, da mit der Funktion Database::SelectDB die Datenbank auch später noch gewechselt werden kann.
• user: Der Name des Benutzers, mit dem sich an der Datenbank authentifiziert werden soll
• password: Das Passwort des Benutzers im Klartext

Parameter

params

Ein Assoziatives Array mit den für den Connect erforderlichen Parameter.

Rückgabe

Bei Erfolg liefert die 1 zurück, im Fehlerfall 0.

Beispiel:

int DB_Example3() {
    ppl6::CAssocArray param;
    param.Set("host","db.pfp.de");
    param.Set("port","3306");
    param.Set("user","patrick");
    param.Set("password","xxxxxxx");
    param.Set("dbname","test");
    ppl6::db::MySQL db;
    if (!db.Connect(param)) {
        ppl6::PrintError();
        return 0;
    }
} // EOF

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

void ppl7::db::Database::connectCreate ( const AssocArray &  params )

virtual

Beschreibung:

Mit dieser Funktion wird eine Verbindung zum Datenbankserver aufgebaut und - sofern nicht schon vorhanden - eine Datenbank angelegt. Die dafür notwendigen Parameter werden dem Array params entnommen. Diese Parameter sind abhängig vom Datenbank-Typ, es gibt jedoch eine Reihe von Parametern, die bei allen Datenbanken identisch sind:

• host: Der Hostname oder die IP-Adresse des Datenbank-Servers
• port: Der TCP-Port des Datenbank-Servers
• dbname: Der Name der intialen Datenbank. Dieser Parameter kann optional sein, da mit der Funktion Database::SelectDB die Datenbank auch später noch gewechselt werden kann.
• user: Der Name des Benutzers, mit dem sich an der Datenbank authentifiziert werden soll
• password: Das Passwort des Benutzers im Klartext

Parameter

params

Ein Assoziatives Array mit den für den Connect erforderlichen Parameter.

Ausnahmebehandlung

diverse

Beispiel:

int DB_Example4() {
    ppl6::CAssocArray param;
    param.Set("host","db.pfp.de");
    param.Set("port","3306");
    param.Set("user","patrick");
    param.Set("password","xxxxxxx");
    param.Set("dbname","test");
    ppl6::db::MySQL db;
    if (!db.ConnectCreate(param)) {
        ppl6::PrintError();
        return 0;
    }
} // EOF

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

ppluint64 ppl7::db::Database::count	(	const String &	table,
		const String &	where = String()
	)

void ppl7::db::Database::createDatabase ( const String &  name )

virtual

Beschreibung:

Mit diesem Befehl wird auf dem Server eine eine neue Datenbank mit dem Namen name erstellt. Dazu muss jedoch vorher bereits eine Verbindung zu einem Server hergestellt worden sein (siehe Database::Connect) und der Datenbank-User muss die notwendigen Rechte zum Anlegen einer Datenbank besitzen.

Parameter

[in]

name

Name der anzulegenden Datenbank

Rückgabe

Konnte die Datenbank erfolgreich angelegt werden, gibt die Funktion 1 zurück, im Fehlerfall 0.

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

String ppl7::db::Database::databaseType ( ) const

virtual

Beschreibung:

Diese Funktion gibt einen String mit dem Typ der Datenbank zurück. Der String kann einen der folgenden Werte enthalten:

• MySQL
• Postgres
• Sybase
• unknown

Rückgabe

String mit dem Typ der Datenbank

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

void ppl7::db::Database::endTransaction ( )

virtual

Beschreibung:

Mit diesem Befehl wird die zuletzt mit Database::StartTransaction begonnene Transaktion beendet. Dadurch werden die innerhalb der Transaktion veränderten Daten endgültig in der Datenbank gespeichert.

Rückgabe

Die Funktion liefert 1 zurück, wenn die Transaktion vollständig erfolgreich abgeschlossen wurde. Im Fehlerfall wird 0 zurückgegeben und keine der innerhalb der Transaktion enthaltenen Änderungen wurde durchgeführt.

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

String ppl7::db::Database::escape ( const String &  str ) const

virtual

Beschreibung:

Mit dieser Funktion wird der übergebene String str Datenbank-konform escaped. Der escapete String str kann anschließend gefahrlos in SQL-Statements innerhalb von Anführungszeichen oder Hochkommata verwendet werden.

Parameter

[in,out]

str

Der zu escapende String

Rückgabe

Bei Erfolg gibt die Funktion 1 zurück, im Fehlerfall 0.

Zu beachten

In der Regel muss eine Verbindung zur Datenbank bestehen, damit der Aufruf erfolgreich ist.

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

void ppl7::db::Database::exec ( const String &  query )

virtual

Beschreibung:

Mit dieser Funktion kann ein SQL-Query an die Datenbank geschickt werden, bei dem das Ergebnis keine Rolle spielt. Sie bietet sich daher für INSERT, UPDATE oder andere SQL-Befehle an, die keine Ergebniszeilen zurückliefern. Bei SELECT-Befehlen sollte stattdessen die Funktion Database::Query verwendet werden.

Parameter

[in]

query

Die gewünschte SQL-Abfrage

Rückgabe

War die SQL-Abfrage erfolgreich, liefert die Funktion 1 zurück, im Fehlerfall 0. Über die Funktion Database::GetAffectedRows kann ausgelesen werden, wieviele Datensätze durch den Query verändert wurden.

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

AssocArray ppl7::db::Database::execArray

(

const String &

query

)

Beschreibung:

Mit dieser Funktion wird der SQL-Query query ausgeführt und die erste Zeile der Ergebnisdaten als Assoziatives Array zurückgegeben. Die Funktion bietet sich daher für Selects an, die genau einen Datensatz zurückliefern. Liefert ein Select mehrere Datensätze zurück, kann stattdessen die Funktion Database::ExecArrayAll verwendet werden.

Zu beachten

Die Funktion ruft ihrerseits die Funktion Database::ExecArray(CAssocArray &result, const CString &query) auf und die Daten des Arrays müssen mehrfach kopiert werden. Es wird daher empfohlen, direkt Database::ExecArray(CAssocArray &result, const CString &query) aufzurufen

Parameter

[in]

query

Der Select-Befehl

Rückgabe

Bei Erfolg liefert die Funktion die Daten in einem Assoziativen Array zurück. Im Fehlerfall ist das Array leer.

void ppl7::db::Database::execArray	(	AssocArray &	result,
		const String &	query
	)

Beschreibung:

Mit dieser Funktion wird der SQL-Query query ausgeführt und die erste Zeile der Ergebnisdaten im Assoziativen Array result gespeichert. Die Funktion bietet sich daher für Selects an, die genau einen Datensatz zurückliefern. Liefert ein Select mehrere Datensätze zurück, kann stattdessen die Funktion Database::ExecArrayAll verwendet werden.

Parameter

[out]	result	Ein Assoziatives Array, in dem das Ergebnis gespeichert wird. Der ursprüngliche Inhalt des Arrays wird durch Aufruf dieser Funktion gelöscht. Falls der SQL-Befehl kein Ergebnis geliefert hat, bleibt das Array leer.
[in]	query	Der Select-Befehl

Rückgabe

Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.

AssocArray ppl7::db::Database::execArrayAll

(

const String &

query

)

Beschreibung:

Mit dieser Funktion wird der SQL-Query query ausgeführt und alle Zeilen des Ergebnisses als Assoziatives Array zurückgegeben. Die Funktion bietet sich daher für Selects an, die mehrere Datensätze zurückliefern. Liefert ein Select nur einen einzigen Datensätze zurück oder wird nur der erste Datensatz benötigt, kann stattdessen die Funktion Database::ExecArray verwendet werden.

Zu beachten

Die Funktion ruft ihrerseits die Funktion Database::ExecArrayAll(CAssocArray &result, const CString &query) auf und die Daten des Arrays müssen mehrfach kopiert werden. Es wird daher empfohlen, direkt Database::ExecArrayAll(CAssocArray &result, const CString &query) aufzurufen

Parameter

[in]

query

Der Select-Befehl

Rückgabe

Bei Erfolg liefert die Funktion die Daten in einem Assoziativen Array zurück. Das Array besteht dabei aus zwei Ebenen. Die erste Ebene ist durchnummeriert, jeder Datensatz erhält also eine Nummer. Auf der zweiten Ebene befinden sich dann die Key-Value-Paare des jeweiligen Datensatzes. Im Fehlerfall ist das Array leer.

void ppl7::db::Database::execArrayAll	(	AssocArray &	result,
		const String &	query
	)

Beschreibung:

Mit dieser Funktion wird der SQL-Query query ausgeführt und alle Zeilen des Ergebnisses im Assoziativen Array result gespeichert. Die Funktion bietet sich daher für Selects an, die mehrere Datensätze zurückliefern. Liefert ein Select nur einen einzigen Datensätze zurück oder wird nur der erste Datensatz benötigt, kann stattdessen die Funktion Database::ExecArray verwendet werden.

Parameter

[out]	result	Ein Assoziatives Array, in dem das Ergebnis gespeichert wird. Der ursprüngliche Inhalt des Arrays wird durch Aufruf dieser Funktion gelöscht. Falls der SQL-Befehl kein Ergebnis geliefert hat, bleibt das Array leer. Das Array besteht dabei aus zwei Ebenen. Die erste Ebene ist durchnummeriert, jeder Datensatz erhält also eine Nummer. Auf der zweiten Ebene befinden sich dann die Key-Value-Paare des jeweiligen Datensatzes.
[in]	query	Der Select-Befehl

Rückgabe

Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.

AssocArray ppl7::db::Database::execArrayAllf	(	const char *	query,
			...
	)

Beschreibung:

Mit dieser Funktion wird zunächst der SQL-Query anhand des Formatierungsstrings query gebaut, ausgeführt und alle Zeilen des Ergebnisses als Assoziatives Array zurückgegeben. Die Funktion bietet sich daher für Selects an, die mehrere Datensätze zurückliefern. Liefert ein Select nur einen einzigen Datensätze zurück oder wird nur der erste Datensatz benötigt, kann stattdessen die Funktion Database::ExecArrayf verwendet werden.

Zu beachten

Die Funktion ruft ihrerseits die Funktion Database::ExecArrayAll(CAssocArray &result, const CString &query) auf und die Daten des Arrays müssen mehrfach kopiert werden. Es wird daher empfohlen, direkt Database::ExecArrayAllf(CAssocArray &result, const CString &query) aufzurufen

Parameter

[in]	query	Der Select-Befehl
[in]	...	Optionale Parameter für den Formatierungsstring

Rückgabe

Bei Erfolg liefert die Funktion die Daten in einem Assoziativen Array zurück. Das Array besteht dabei aus zwei Ebenen. Die erste Ebene ist durchnummeriert, jeder Datensatz erhält also eine Nummer. Auf der zweiten Ebene befinden sich dann die Key-Value-Paare des jeweiligen Datensatzes. Im Fehlerfall ist das Array leer.

void ppl7::db::Database::execArrayAllf	(	AssocArray &	result,
		const char *	query,
			...
	)

Beschreibung:

Mit dieser Funktion wird zunächst der SQL-Query anhand des Formatierungsstrings query gebaut, ausgeführt und alle Zeilen des Ergebnisses im Assoziativen Array result gespeichert. Die Funktion bietet sich daher für Selects an, die mehrere Datensätze zurückliefern. Liefert ein Select nur einen einzigen Datensätze zurück oder wird nur der erste Datensatz benötigt, kann stattdessen die Funktion Database::ExecArray verwendet werden.

Parameter

[out]	result	Ein Assoziatives Array, in dem das Ergebnis gespeichert wird. Der ursprüngliche Inhalt des Arrays wird durch Aufruf dieser Funktion gelöscht. Falls der SQL-Befehl kein Ergebnis geliefert hat, bleibt das Array leer. Das Array besteht dabei aus zwei Ebenen. Die erste Ebene ist durchnummeriert, jeder Datensatz erhält also eine Nummer. Auf der zweiten Ebene befinden sich dann die Key-Value-Paare des jeweiligen Datensatzes.
[in]	query	Der Select-Befehl
[in]	...	Optionale Parameter für den Formatierungsstring

Rückgabe

Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.

AssocArray ppl7::db::Database::execArrayf	(	const char *	query,
			...
	)

Beschreibung:

Mit dieser Funktion wird zunächst der SQL-Query anhand des Formatierungsstrings query gebaut, ausgeführt und die erste Zeile der Ergebnisdaten als Assoziatives Array zurückgegeben. Die Funktion bietet sich daher für Selects an, die genau einen Datensatz zurückliefern. Liefert ein Select mehrere Datensätze zurück, kann stattdessen die Funktion Database::ExecArrayAll verwendet werden.

Zu beachten

Die Funktion ruft ihrerseits die Funktion Database::ExecArray(CAssocArray &result, const CString &query) auf und die Daten des Arrays müssen mehrfach kopiert werden. Es wird daher empfohlen, direkt Database::ExecArray(CAssocArray &result, const CString &query) aufzurufen

Parameter

[in]	query	Formatierungsstring für den SQL-Query
[in]	...	Optionale Parameter für den Formatierungsstring

Rückgabe

Bei Erfolg liefert die Funktion die Daten in einem Assoziativen Array zurück. Im Fehlerfall ist das Array leer.

void ppl7::db::Database::execArrayf	(	AssocArray &	result,
		const char *	query,
			...
	)

Beschreibung:

Mit dieser Funktion wird zunächst der SQL-Query anhand des Formatierungsstrings query gebaut, ausgeführt und die erste Zeile der Ergebnisdaten im Assoziativen Array result gespeichert. Die Funktion bietet sich daher für Selects an, die genau einen Datensatz zurückliefern. Liefert ein Select mehrere Datensätze zurück, kann stattdessen die Funktion Database::ExecArrayAll verwendet werden.

Parameter

[out]	result	Ein Assoziatives Array, in dem das Ergebnis gespeichert wird. Der ursprüngliche Inhalt des Arrays wird durch Aufruf dieser Funktion gelöscht. Falls der SQL-Befehl kein Ergebnis geliefert hat, bleibt das Array leer.
[in]	query	Formatierungsstring für den SQL-Query
[in]	...	Optionale Parameter für den Formatierungsstring

Rückgabe

Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.

void ppl7::db::Database::execf	(	const char *	query,
			...
	)

Beschreibung:

Diese Funktion ist identisch mit Database::exec, erwartet jedoch als Parameter einen Formatierungsstring query und eine variable Anzahl von Parametern, die in den Formatierungsstring eingesetzt werden.

Die Funktion ist für INSERT, UPDATE und andere SQL-Befehle gedacht, die keine Ergebniszeilen zurückliefern. Bei SELECT-Befehlen sollte stattdessen die Funktion Database::query bzw. Database::queryf verwendet werden.

Parameter

[in]	query	Formatierungsstring für den SQL-Befehl
[in]	...	Optionale Parameter, die in den Formatierungsstring eingesetzt werden.

Ausnahmebehandlung

QueryFailedException

und andere

ppluint64 ppl7::db::Database::getAffectedRows ( )

virtual

Beschreibung:

War der vorausgehende Datenbank-Query ein Select, liefert diese Funktion die Anzahl Zeilen im Ergebnis zurück. Handelete es sich um ein Update/Insert/Replace, wird die Anzahl betroffener bzw. veränderter Datensätze zurückgegeben.

Rückgabe

Anzahl betroffender Datensätze

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

Logger * ppl7::db::Database::getLogger

(

)

Rückgabe

Gibt einen Pointer auf die konfigurierte Logger-Klasse zurück, oder NULL, wenn kein Logger konfiguriert ist.

Siehe auch

Database::setLogger

Database::removeLogger

String ppl7::db::Database::getQuoted ( const String &  value, const String &  type = String()  ) const

virtual

Beschreibung:

Diese Funktion escaped und quoted den String value Datenbank-konform abhängig vom Datentyp type. Der Rückgabewert enthält je nach Datentyp bereits Hochkommata oder Anführungszeichen und kann somit ohne weitere Quotes in einen Query eingesetzt werden.

Parameter

value	Zu quotender String
type	Datentyp. Wird nichts angegeben, wird der Wert value als String interpretiert.

Rückgabe

Escapeter und Gequoteter String

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

void ppl7::db::Database::logQuery ( const String &  query, float  duration  )

protected

Beschreibung:

Diese Funktion wird intern aufgerufen, um einen Query in das Logfile zu schreiben, sofern dieses über Database::setLogger aktiviert wurde.

Parameter

[in]	query	Der durchgeführte Query
[in]	duration	Laufzeit des Queries in Sekunden.

bool ppl7::db::Database::ping ( )

virtual

Beschreibung:

Mit dieser Funktion können Clients, die geraume Zeit untätig waren, prüfen, ob die Verbindung zum Datenbankserver noch zur Verfügung steht. Je nach Implementierung (z.B. bei MySQL) kann es sein, dass durch Aufruf dieser Funktion eine abgebrochene Verbindung automatisch wieder aufgebaut wird.

Rückgabe

Die Funktion liefert true zurück, wenn die Datenbankverbindung noch besteht. Ist dies nicht der Fall, wird false zurückgegeben. Es kann dann mit der Funktion Database::reconnect versucht werden, die Verbindung wieder herzustellen.

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

ResultSet * ppl7::db::Database::query ( const String &  query )

virtual

Beschreibung:

Dieser Befehl ist für SELECT und andere SQL-Befehle gedacht, die Ergebniszeilen zurückliefern. Im Gegensatz zu Database::Exec wird hier eine Result-Klasse zurückgeliefert, aus der die Ergebniszeilen ausgelesen werden können (siehe Result). Bei anderen Befehlen, die kein Ergebnis zurückliefern (z.B. INSERT oder UPDATE) sollte stattdessen der etwas schnellere Befehl Database::Exec verwendet werden.

Parameter

[in]

query

Die gewünschte SQL-Abfrage

Rückgabe

War die SQL-Abfrage erfolgreich, liefert die Funktion einen Pointer auf eine Result-Klasse zurück. Diese muss nach Gebrauch von der aufrufenden Anwendung mit delete oder durch Aufruf von Database::FreeResult gelöscht werden. Im Fehlerfall wird NULL zurückgeliefert.

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

ResultSet * ppl7::db::Database::queryf	(	const char *	query,
			...
	)

Beschreibung:

Dieser Befehl ist für SELECT und andere SQL-Befehle gedacht, die Ergebniszeilen zurückliefern. Im Gegensatz zu Database::Exec wird hier eine Result-Klasse zurückgeliefert, aus der die Ergebniszeilen ausgelesen werden können (siehe Result). Bei anderen Befehlen, die kein Ergebnis zurückliefern (z.B. INSERT oder UPDATE) sollte stattdessen der etwas schnellere Befehl Database::Exec verwendet werden.

Diese Funktion ist identisch mit Database::Query, erwartet jedoch als Parameter einen Formatierungsstring query und eine variable Anzahl von Parametern, die in den Formatierungsstring eingesetzt werden.

Parameter

[in]	query	Formatierungsstring für den SQL-Befehl
[in]	...	Optionale Parameter, die in den Formatierungsstring eingesetzt werden.

Rückgabe

War die SQL-Abfrage erfolgreich, liefert die Funktion einen Pointer auf eine Result-Klasse zurück. Diese muss nach Gebrauch von der aufrufenden Anwendung mit delete oder durch Aufruf von Database::FreeResult gelöscht werden. Im Fehlerfall wird NULL zurückgeliefert.

void ppl7::db::Database::reconnect ( )

virtual

Beschreibung:

Diese Funktion versucht eine unterbrochene Datenbankverbindung wieder aufzubauen. Dazu werden die gleichen Parameter wie beim früheren Connect verwendet.

Rückgabe

Kann die Datenbank-Verbindung erfolgreich wieder aufgebaut werden, liefert die Funktion 1 zurück, andernfalls 0.

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

void ppl7::db::Database::removeLogger

(

)

Beschreibung:

Mit dieser Funktion kann das Loggen aller Queries deaktiviert werden.

Siehe auch

Database::setLogger

Database::getLogger

void ppl7::db::Database::selectDB ( const String &  databasename )

virtual

Beschreibung:

In der Regel befinden sich auf einem Datenbank-Server mehrere Datenbanken. Mit dieser Funktion kann die aktive Datenbank ausgewählt werden, die danach in SQL-Befehlen ohne Prefix verwendet werden kann. Die Funktion wird auch beim Connect aufgerufen, sofern der Parameter dbname angegeben wurde.

Parameter

[in]

databasename

Name der gewünschten Datenbank

Rückgabe

Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

void ppl7::db::Database::setLogger

(

Logger &

logger

)

Beschreibung:

Mit dieser Funktion kann ein Querylog aktiviert werden. Ist es aktiviert, wird bei jedem Query ein Datensatz in das Logfile geschrieben, dem man neben Datum, Uhrzeit und Query auch entnehmen kann, wie lang der Query gebraucht hat.

Parameter

[in]

log

Referenz auf eine Instanz der Klasse Logger.

Siehe auch

Database::getLogger

Database::removeLogger

void ppl7::db::Database::setParam	(	const String &	name,
		const String &	value
	)

Beschreibung:

Die Datenbank-Klasse unterstützt zwei Connect-Funktionen: eine ohne Parameter und eine mit einem Assoziativen Array als Parameter. Damit die Connect-Funktion ohne Parameter funktioniert, müssen diese zuvor mit setParam gesetzt werden.

Parameter

[in]	name	Name des Parameters
[in]	value	Wert des Parameters als String

void ppl7::db::Database::setParam	(	const String &	name,
		int	value
	)

Beschreibung:

Die Datenbank-Klasse unterstützt zwei Connect-Funktionen: eine ohne Parameter und eine mit einem Assoziativen Array als Parameter. Damit die Connect-Funktion ohne Parameter funktioniert, müssen diese zuvor mit setParam gesetzt werden.

Parameter

[in]	name	Name des Parameters
[in]	value	Wert des Parameters als Integer

void ppl7::db::Database::setParam

(

const AssocArray &

params

)

Beschreibung:

Die Datenbank-Klasse unterstützt zwei Connect-Funktionen: eine ohne Parameter und eine mit einem Assoziativen Array als Parameter. Damit die Connect-Funktion ohne Parameter funktioniert, müssen diese zuvor mit setParam gesetzt werden.

Parameter

[in]

params

Assoziatives Array mit den Connect-Parametern

void ppl7::db::Database::startTransaction ( )

virtual

Beschreibung:

Als Transaktion (von lat. trans „über“, actio zu agere „(durch)führen“) bezeichnet man in der Informatik eine feste Folge von Operationen, die als eine logische Einheit betrachtet werden. Insbesondere wird für Transaktionen gefordert, dass sie entweder vollständig oder überhaupt nicht ausgeführt werden (Atomizität).

Mit diesem Befehl läßt sich eine Transaktion auf der Datenbank starten. Mit dem Befehl Database::EndTransaction wird sie abgeschlossen und mit Database::CancelTransaction abgebrochen.

Ab Version 6.4.3 der PPL-Library kann man Transaktionen verschachteln, in dem man Database::StartTransaction mehrfach aufruft. Mit Database::EndTransaction wird dann nur die innerste Transaktionsklammer abgeschlossen, mit Database::CancelTransaction entsprechend nur die innerste Transaktionsklammer zurückgerollt. Mit Database::CancelTransactionComplete läßt sich die komplette Transaktion bis zur äußersten Klammer zurückrollen. Bei der Verschachtelung von Transaktionen muss man darauf achten, dass immer eine gleiche Anzahl von Database::EndTransaction wie Database::StartTransaction geben muss, da sonst die Transaktion nicht vollständig geschlossen wird und es zu Datenbank Blockaden kommen kann.

Rückgabe

Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.

Erneute Implementation in ppl7::db::SQLite, ppl7::db::MySQL und ppl7::db::PostgreSQL.

void ppl7::db::Database::updateLastPing ( )

protected

Beschreibung:

Diese interne Funktion wird immer dann aufgerufen, wenn eine erfolgreiche Kommunikation mit dem Datenbank-Server stattgefunden hat. Dabei kann es sich um einen Query der Anwendung gehandelt haben aber auch um einen Ping, der automatisch durch die Verwaltung des Datenbank-Pools abgeschickt wurde (siehe Pool und PoolEx). Sie aktualisiert den Wert Database::lastping mit dem aktuellen Timestamp. Dieser Wert enthält somit immer einen Zeitstempel, zu dem zuletzt eine Verbindung zum Server bestand.

void ppl7::db::Database::updateLastUse ( )

protected

Beschreibung:

Diese interne Funktion wird immer dann aufgerufen, wenn die Anwendung einen Query erfolgreich auf dem Datenbank-Server durchgeführt hat. Sie aktualisiert den Wert Database::lastuse mit dem aktuellen Timestamp. Dieser Wert enthält somit immer einen Zeitstempel, zu dem die diese Instanz der Datenbank zuletzt durch die Anwendung verwendet wurde. Diese Information wird von den Datenbank-Pools Pool und PoolEx verwendet, um zu entscheiden, wann eine Datenbank-Verbindung nicht mehr gebraucht wird und aus dem Pool entfernt werden kann.

Freundbeziehungen und Funktionsdokumentation

friend class MultiPool

friend

friend class SinglePool

friend

Dokumentation der Datenelemente

AssocArray ppl7::db::Database::ConnectParam

private

ppluint64 ppl7::db::Database::lastping

private

ppluint64 ppl7::db::Database::lastuse

private

Logger* ppl7::db::Database::Log

private

---

Die Dokumentation für diese Klasse wurde erzeugt aufgrund der Dateien:

• /jenkins/jobs/clang_ppl7/workspace/include/ppl7-db.h
• /jenkins/jobs/clang_ppl7/workspace/src/database/Database.cpp