PPL6-Icon Patrick's Programming Library Version 6.4.21 - Dokumentation
ppl6::db::Postgres Klassenreferenz

Implementierung einer Postgres-Datenbank. Mehr ...

Öffentliche Methoden

 Postgres ()
 
virtual ~Postgres ()
 
virtual int CancelTransaction ()
 Letzte Transaktion abbrechen. Mehr ...
 
virtual int CancelTransactionComplete ()
 Transaktion vollständig abbrechen. Mehr ...
 
int Close ()
 Verbindung zu Datenbank trennen. Mehr ...
 
int Connect ()
 Connect auf eine Datenbank erstellen. Mehr ...
 
virtual int Connect (const CAssocArray &params)
 Connect auf eine Postgres-Datenbank erstellen. Mehr ...
 
virtual int ConnectCreate (const CAssocArray &params)
 Connect zum Server aufbauen und Datenbank anlegen. Mehr ...
 
virtual int CreateDatabase (const char *name)
 Datenbank erstellen. Mehr ...
 
virtual CString databaseType () const
 Typ der Datenbank. Mehr ...
 
virtual int Disconnect ()
 Verbindung zur Datenbank trennen. Mehr ...
 
virtual int EndTransaction ()
 Transaktion beenden. Mehr ...
 
virtual int Escape (CString &str) const
 String escapen. Mehr ...
 
virtual int Exec (const CString &query)
 SQL-Query ohne Ergebnis ausführen. Mehr ...
 
CAssocArray ExecArray (const CString &query)
 SQL-Query ausführen und ersten Datensatz als Array zurückgeben. Mehr ...
 
int ExecArray (CAssocArray &result, const CString &query)
 SQL-Query ausführen und ersten Datensatz in Array speichern. Mehr ...
 
CAssocArray ExecArrayAll (const CString &query)
 SQL-Query ausführen und alle Datensätze in Array speichern. Mehr ...
 
int ExecArrayAll (CAssocArray &result, const CString &query)
 SQL-Query ausführen und alle Datensätze in Array speichern. Mehr ...
 
CAssocArray ExecArrayAllf (const char *query,...)
 SQL-Query bauen, ausführen und alle Datensätze in Array speichern. Mehr ...
 
int ExecArrayAllf (CAssocArray &result, const char *query,...)
 SQL-Query bauen, ausführen und alle Datensätze in Array speichern. Mehr ...
 
CAssocArray ExecArrayf (const char *query,...)
 SQL-Query bauen, ausführen und ersten Datensatz als Array zurückgeben. Mehr ...
 
int ExecArrayf (CAssocArray &result, const char *query,...)
 SQL-Query bauen, ausführen und ersten Datensatz in Array speichern. Mehr ...
 
int Execf (const char *query,...)
 Ergebnislosen SQL-Query anhand eines Formatierungsstrings bauen und ausführen. Mehr ...
 
void FreeResult (Result *res)
 Result-Klasse freigeben. Mehr ...
 
virtual pplint64 GetAffectedRows ()
 Betroffene Zeilen. Mehr ...
 
CString GetEscaped (const CString &str)
 String escapen. Mehr ...
 
virtual ppluint64 GetInsertID ()
 Letzer durch eine AUTO_INCREMENT-Spalte generierten Wert. Mehr ...
 
CLogGetLogfile ()
 
virtual CString getQuoted (const CString &value, const CString &type=CString()) const
 Wert Datenbank-konform quoten. Mehr ...
 
ppluint64 InsertKey (const char *table, CAssocArray &a, const char *keyname, const CAssocArray &exclude=CAssocArray())
 Datensatz mit incrementellem Schlüssel speichern. Mehr ...
 
virtual int Ping ()
 Erreichbarkeit der Datenbank prüfen. Mehr ...
 
virtual ResultQuery (const CString &query)
 SQL-Query mit Ergebnis ausführen. Mehr ...
 
ResultQueryf (const char *query,...)
 SQL-Query mit Ergebnis ausführen. Mehr ...
 
int ReadKeyValue (CAssocArray &res, const char *query, const char *keyname, const char *valname=NULL)
 
virtual int Reconnect ()
 Verlorene Datenbank-Verbindung wieder herstellen. Mehr ...
 
int Save (const char *method, const char *table, CAssocArray &a, const char *clause=NULL, const CAssocArray &exclude=CAssocArray(), const CAssocArray &types=CAssocArray())
 Datensatz speichern. Mehr ...
 
int SaveGenQuery (CString &Query, const char *method, const char *table, CAssocArray &a, const char *clause=NULL, const CAssocArray &exclude=CAssocArray(), const CAssocArray &types=CAssocArray())
 Query zum Speichern des Datensatzes generieren. Mehr ...
 
virtual int SelectDB (const char *databasename)
 Aktive Datenbank auswählen. Mehr ...
 
void SetLogfile (CLog *log=NULL)
 Querylog aktivieren oder deaktivieren. Mehr ...
 
void SetLogfile (CLog &log)
 Querylog aktivieren. Mehr ...
 
virtual void SetMaxRows (ppluint64 rows)
 Maximale Anzahl Zeilen im Ergebnis eines Selects. Mehr ...
 
void SetParam (const char *name, const char *value)
 Parameter für den Connect setzen. Mehr ...
 
void SetParam (const char *name, int value)
 Parameter für den Connect setzen. Mehr ...
 
virtual int StartTransaction ()
 Transaktion starten. Mehr ...
 

Geschützte Methoden

void ClearLastUse ()
 Timestamps auf 0 setzen. Mehr ...
 
void LogQuery (const char *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 Methoden

void * Pgsql_Query (const CString &query)
 Query ausführen. Mehr ...
 

Private Attribute

pplint64 affectedrows
 
CAssocArray condata
 
void * conn
 
ppluint64 lastinsertid
 
ppluint64 maxrows
 
int transactiondepth
 

Ausführliche Beschreibung

Include:
#include <ppl6-db.h>
Beschreibung:
Mit dieser Klasse kann eine Verbindung zu einer Postgres-Datenbank aufgebaut werden, um darüber SQL-Queries durchzuführen.
Beispiel:
int DB_Postgres_Example1() {
// Verbindungsparameter festlegen
param.Set("host","db.pfp.de");
param.Set("port","5432");
param.Set("user","patrick");
param.Set("password","xxxxxxx");
param.Set("dbname","test");
// Datenbank-Klasse anlegen
// Verbindung aufbauen
if (!db.Connect(param)) {
return 0;
}
// Query abschicken
ppl6::db::Result *res=db.Query("select * from user oder by nachname, vorname");
if (!res) { // Fehler abfangen
} else {
printf ("Es wurden %i Datensätze gefunden\n",res->Rows());
// Result wieder freigeben
delete res;
}
// Die Verbindung wird durch den Destruktor der Klasse automatisch
// ordnungsgemäß getrennt
} // EOF

Beschreibung der Konstruktoren und Destruktoren

ppl6::db::Postgres::Postgres ( )
ppl6::db::Postgres::~Postgres ( )
virtual

Dokumentation der Elementfunktionen

int ppl6::db::Postgres::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 von ppl6::db::Database.

int ppl6::db::Postgres::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 von ppl6::db::Database.

void ppl6::db::Database::ClearLastUse ( )
protectedinherited
Beschreibung:
Die Werte Database::lastping und Database::lastuse werden auf 0 gesetzt. Es ist unklar, wann diese Funktion aufgerufen wird.
int ppl6::db::Database::Close ( )
inherited
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.
int ppl6::db::Database::Connect ( )
inherited
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.
Rückgabe
Bei Erfolg liefert die 1 zurück, im Fehlerfall 0.
Beispiel:
Bei dem nachfolgenden Beispiel wird eine MySQL-Datenbank verwendet. Die Klasse "Database" kann selbst nicht verwendet werden, da es sich hierbei nur um eine abstrakte Basisklasse handelt.
int DB_Example2() {
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()) {
return 0;
}
} // EOF

int ppl6::db::Postgres::Connect ( const CAssocArray params)
virtual
Beschreibung:
Mit dieser Funktion wird eine Verbindung zu einem Postgres 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.
  • user: Der Name des Benutzers, mit dem sich an der Datenbank authentifiziert werden soll
  • password: Das Passwort des Benutzers im Klartext
  • searchpath: Kommaseparierte Liste mit den Schemata, die in den Suchpfad aufgenommen werden sollen
    Parameter
    paramsEin 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() {
    param.Set("host","db.pfp.de");
    param.Set("port","3306");
    param.Set("user","patrick");
    param.Set("password","xxxxxxx");
    param.Set("dbname","test");
    if (!db.Connect(param)) {
    return 0;
    }
    } // EOF

Erneute Implementation von ppl6::db::Database.

int ppl6::db::Postgres::ConnectCreate ( const CAssocArray 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
paramsEin 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_Example4() {
param.Set("host","db.pfp.de");
param.Set("port","3306");
param.Set("user","patrick");
param.Set("password","xxxxxxx");
param.Set("dbname","test");
if (!db.ConnectCreate(param)) {
return 0;
}
} // EOF

Erneute Implementation von ppl6::db::Database.

int ppl6::db::Postgres::CreateDatabase ( const char *  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]nameName der anzulegenden Datenbank
Rückgabe
Konnte die Datenbank erfolgreich angelegt werden, gibt die Funktion 1 zurück, im Fehlerfall 0.

Erneute Implementation von ppl6::db::Database.

CString ppl6::db::Postgres::databaseType ( ) const
virtual
Beschreibung:
Diese Funktion gibt einen String mit dem Typ der Datenbank zurück. Der String kann einen der folgenden Werte enthalten:
Rückgabe
String mit dem Typ der Datenbank

Erneute Implementation von ppl6::db::Database.

int ppl6::db::Postgres::Disconnect ( )
virtual
Beschreibung:
Durch Aufruf dieser Funktion wird die Verbindung zur Datenbank getrennt.
Rückgabe
Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.

Erneute Implementation von ppl6::db::Database.

int ppl6::db::Postgres::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 von ppl6::db::Database.

int ppl6::db::Postgres::Escape ( CString 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]strDer 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 von ppl6::db::Database.

int ppl6::db::Postgres::Exec ( const CString 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]queryDie 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 von ppl6::db::Database.

CAssocArray ppl6::db::Database::ExecArray ( const CString query)
inherited
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]queryDer Select-Befehl
Rückgabe
Bei Erfolg liefert die Funktion die Daten in einem Assoziativen Array zurück. Im Fehlerfall ist das Array leer.
int ppl6::db::Database::ExecArray ( CAssocArray result,
const CString query 
)
inherited
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]resultEin 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]queryDer Select-Befehl
Rückgabe
Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.
CAssocArray ppl6::db::Database::ExecArrayAll ( const CString query)
inherited
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]queryDer 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.
int ppl6::db::Database::ExecArrayAll ( CAssocArray result,
const CString query 
)
inherited
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]resultEin 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]queryDer Select-Befehl
Rückgabe
Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.
CAssocArray ppl6::db::Database::ExecArrayAllf ( const char *  query,
  ... 
)
inherited
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]queryDer 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.
int ppl6::db::Database::ExecArrayAllf ( CAssocArray result,
const char *  query,
  ... 
)
inherited
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]resultEin 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]queryDer Select-Befehl
[in]...Optionale Parameter für den Formatierungsstring
Rückgabe
Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.
CAssocArray ppl6::db::Database::ExecArrayf ( const char *  query,
  ... 
)
inherited
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]queryFormatierungsstring 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.
int ppl6::db::Database::ExecArrayf ( CAssocArray result,
const char *  query,
  ... 
)
inherited
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]resultEin 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]queryFormatierungsstring 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.
int ppl6::db::Database::Execf ( const char *  query,
  ... 
)
inherited
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 gedachtm die keine Ergebniszeilen zurückliefern. Bei SELECT-Befehlen sollte stattdessen die Funktion Database::Queryf verwendet werden.
Parameter
[in]queryFormatierungsstring für den SQL-Befehl
[in]...Optionale Parameter, die in den Formatierungsstring eingesetzt werden.
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.
void ppl6::db::Database::FreeResult ( Result res)
inherited
Beschreibung:
Mit dieser Funktion wird die von den Funktionen Database::Query oder Database::Queryf zurückgegebene Result-Klasse wieder gelöscht. Es wird jedoch empfphlen die Result-Klasse einfach mit delete zu löschen, da dies etwas schneller ist.
Parameter
[in]resPointer auf eine Result-Klasse
pplint64 ppl6::db::Postgres::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, im Fehlerfall -1

Erneute Implementation von ppl6::db::Database.

CString ppl6::db::Database::GetEscaped ( const CString str)
inherited
Beschreibung:
Mit dieser Funktion wird der übergebene String str Datenbank-konform escaped und als Return-Wert zurückgegeben. Der escapete String kann gefahrlos in SQL-Statements innerhalb von Anführungszeichen oder Hochkommata verwendet werden.
Parameter
[in]strDer zu escapende String
Rückgabe
Liefert den escapten String zurück. Falls ein Fehler aufgetreten ist, kann der String leer sein.
Zu beachten
In der Regel muss eine Verbindung zur Datenbank bestehen, damit der Aufruf erfolgreich ist.
ppluint64 ppl6::db::Postgres::GetInsertID ( )
virtual
Beschreibung:
Liefert den von der vorherigen INSERT- oder UPDATE-Anweisung für eine AUTO_INCREMENT-Spalte generierten Wert. Verwenden Sie diese Funktion, wenn Sie eine INSERT-Anweisung auf einer Tabelle mit einem AUTO_INCREMENT-Feld ausgeführt haben.
Rückgabe
Wert

Erneute Implementation von ppl6::db::Database.

CLog * ppl6::db::Database::GetLogfile ( )
inherited
CString ppl6::db::Postgres::getQuoted ( const CString value,
const CString type = CString() 
) 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
valueZu quotender String
typeDatentyp. Wird nichts angegeben, wird der Wert value als String interpretiert.
Rückgabe
Escapeter und Gequoteter String

Erneute Implementation von ppl6::db::Database.

ppluint64 ppl6::db::Database::InsertKey ( const char *  table,
CAssocArray a,
const char *  keyname,
const CAssocArray exclude = CAssocArray() 
)
inherited
Beschreibung:
Diese Funktion ähnelt Database::Save, jedoch unterstützt sie nur die INSERT-Methode. Speziell ein Insert auf eine Tabelle, bei der der primäre Schlüssel ein incrementeller Wert ist, der jedoch nicht automatisch von der Datenbank erhöht wird.
Die Funktion sperrt zunächst die angegebene Tabelle table für Schreibzugriffe. Dann wird der höchste Wert des Schlüssels keyname gesucht und um 1 erhöht. Mit diesem Schlüssel werden die Daten aus dem Array a mit INSERT gespeichert, außer den Feldern, die in exclude angegeben wurden. Dazu wird die Funktion Database::Save aufgerufen. Danach wird die Tabelle table wieder entsperrt. Der Wert des Schlüssels wird als 64-Bit-Wert zurückgegeben.
Parameter
[in]tableName der Datenbank-Tabelle, in die der Datensatz gespeichert werden soll
[in]aEin assoziatives Array mit den zu speichernden Daten
[in]keynameDer Feldname des primären Schlüssels der Tabelle
[in]excludeEin optionales Array, das die Feldnamen aus a enthält, die nicht gespeichert werden sollen
Rückgabe
Bei Erfolg gibt die Funktion den Wert des Schlüssels zurück, mit dem der Datensatz gespeichert wurde, im Fehlerfall 0.
void ppl6::db::Database::LogQuery ( const char *  query,
float  duration 
)
protectedinherited
Beschreibung:
Diese Funktion wird intern aufgerufen, um einen Query in das Logfile zu schreiben, sofern dieses über Database::SetLogfile aktibviert wurde.
Parameter
[in]queryDer durchgeführte Query
[in]durationLaufzeit des Queries in Sekunden.
void * ppl6::db::Postgres::Pgsql_Query ( const CString query)
private
Beschreibung:
Dies ist eine interne Funktion, die einen Query an die Postgres-Datenbank schickt. Schlägt dies fehl, weil die Verbindung zur Datenbank zwischenzeitlich verloren ging, wird ein Reconnect versucht und bei Erfolg der Query wiederholt. Die Klasse erwartet, dass der Mutex bereits gelockt ist und die Variable Postgres::conn ein gültiges Postgres Connection-Handle enthält.
Parameter
[in]queryString mit dem abzusetzenden Query
Rückgabe
Konnte der Query erfolgreich ausgeführt werden, liefert die Funktion 1 zurück, im Fehlerfall 0. Der Mutex ist bei Verlassen der Funktion auf jeden Fall gesetzt.
int ppl6::db::Postgres::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 1 zurück, wenn die Datenbankverbindung noch besteht. Ist dies nicht der Fall, wird 0 zurückgegeben. Es kann dann mit der Funktion Database::Reconnect versucht werden, die Verbindung wieder herzustellen.

Erneute Implementation von ppl6::db::Database.

Result * ppl6::db::Postgres::Query ( const CString 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]queryDie 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 von ppl6::db::Database.

Result * ppl6::db::Database::Queryf ( const char *  query,
  ... 
)
inherited
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]queryFormatierungsstring 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.
int ppl6::db::Database::ReadKeyValue ( CAssocArray res,
const char *  query,
const char *  keyname,
const char *  valname = NULL 
)
inherited
int ppl6::db::Postgres::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 von ppl6::db::Database.

int ppl6::db::Database::Save ( const char *  method,
const char *  table,
CAssocArray a,
const char *  clause = NULL,
const CAssocArray exclude = CAssocArray(),
const CAssocArray types = CAssocArray() 
)
inherited
Beschreibung:
Diese Funktion speichert die im Assoziativen Array a vorhandenen Felder und Werte mit der Methode method in der Tabelle table. Je nach Methode wird dabei aus den Daten ein entprechender SQL-Query gebaut. Soll ein Update durchgeführt werden, muss zusätzlich noch eine Where-Klausel mit dem Parameter clause angegeben werden. Enthalten die Daten in a Felder, die in der Tabelle table nicht vorhanden sind, muss zusätzlich noch das Array exclude angegeben werden, dass die zu ignorierenden Feldnamen enthält.
Die Daten in a werden vor dem Einsetzen in den Query korrekt Escaped.
Parameter
[in]methodDie Methode, mit der der Datensatz in die Datenbank geschrieben werden soll. In Frage kommen:
  • INSERT
  • UPDATE
  • REPLACE
[in]tableName der Tabelle
[in]aEin Assoziatives Array mit den zu speichernden Feldern
[in]clauseEin Optionaler Parameter, der bei UPDATE angegeben werden muss und die Where-Klausel enthält. Das Keywort "where" muss nicht angegeben werden
[in]excludeEin optionales assoziatives Array, was die Namen der Felder enthält, die nicht gespeichert werden sollen. Muss verwendet werden, wenn in a Felder enthalten sind, die in der Tabelle table nicht existieren.
[in]typesEin optionales assoziatives Array, was die Typen der zu speichernden Daten angibt. Hier wird zur Zeit nur "int" und "bit" interpretiert, was dazu führt, dass die Werte nicht in Anführungszeichen in den SQL-Query eingebaut werden. Alle anderen Typen werden wie bisher als String behandelt. Bei dem ASE von Sybase gibt es Probleme, wenn man versucht einen Ziffer in Anführungszeichen anzugeben, wenn das Feld als "numeric" oder "bit" definiert ist.
Rückgabe
Bei Erfolg gibt die Funktion 1 zurück, im Fehlerfall 0.
Beispiel:
Das folgende Beispiel zeigt, wie mit Hilfe von Save ein Datensatz mit UPDATE aktualisiert wird. Es wird von folgender Tabellendefinition ausgegangen:
   userid    int4 not null primary key,
   vorname   varchar(64) nut null,
   nachname  varchar(64) nut null,
   email     varchar(128) nut null
int DB_Save_Example1(ppl6::db::Database *db) {
// Die Funktion geht davon aus, dass "db" eine gültige Datenbank-Verbindung
// enthält.
Data.Set("vorname","Patrick");
Data.Set("nachname","Fedick");
Data.Set("email","xxx@xxxx.xx");
return db->Save("update","user",Data,"where userid=1");
} // EOF
int ppl6::db::Database::SaveGenQuery ( CString Query,
const char *  method,
const char *  table,
CAssocArray a,
const char *  clause = NULL,
const CAssocArray exclude = CAssocArray(),
const CAssocArray types = CAssocArray() 
)
inherited
Beschreibung:
Diese Funktion generiert aus den im Assoziativen Array a vorhandenen Feldern und Werten in Abhängigkeit der Methode method einen SQL-Query für die Tabelle table. Soll ein Update durchgeführt werden, muss zusätzlich noch eine Where-Klausel mit dem Parameter clause angegeben werden. Enthalten die Daten in a Felder, die in der Tabelle table nicht vorhanden sind, muss zusätzlich noch das Array exclude angegeben werden, dass die zu ignorierenden Feldnamen enthält.
Die Daten in a werden vor dem Einsetzen in den Query korrekt Escaped.
Parameter
[out]QueryString, in dem der Query gespeichert werden soll
[in]methodDie Methode, mit der der Datensatz in die Datenbank geschrieben werden soll. In Frage kommen:
  • INSERT
  • UPDATE
  • REPLACE
[in]tableName der Tabelle
[in]aEin Assoziatives Array mit den zu speichernden Feldern
[in]clauseEin Optionaler Parameter, der bei UPDATE angegeben werden muss und die Where-Klausel enthält. Das Keywort "where" muss nicht angegeben werden
[in]excludeEin optionales assoziatives Array, was die Namen der Felder enthält, die nicht gespeichert werden sollen. Muss verwendet werden, wenn in a Felder enthalten sind, die in der Tabelle table nicht existieren.
[in]typesEin optionales assoziatives Array, was die Typen der zu speichernden Daten angibt. Hier wird zur Zeit nur "int" und "bit" interpretiert, was dazu führt, dass die Werte nicht in Anführungszeichen in den SQL-Query eingebaut werden. Alle anderen Typen werden wie bisher als String behandelt. Bei dem ASE von Sybase gibt es Probleme, wenn man versucht einen Ziffer in Anführungszeichen anzugeben, wenn das Feld als "numeric" oder "bit" definiert ist.
Rückgabe
Bei Erfolg gibt die Funktion 1 zurück, im Fehlerfall 0.
Beispiel:
Das folgende Beispiel zeigt, wie mit Hilfe von Save ein Datensatz mit UPDATE aktualisiert wird. Es wird von folgender Tabellendefinition ausgegangen:
   userid    int4 not null primary key,
   vorname   varchar(64) nut null,
   nachname  varchar(64) nut null,
   email     varchar(128) nut null
int DB_Save_Example1(ppl6::db::Database *db) {
// Die Funktion geht davon aus, dass "db" eine gültige Datenbank-Verbindung
// enthält.
Data.Set("vorname","Patrick");
Data.Set("nachname","Fedick");
Data.Set("email","xxx@xxxx.xx");
return db->Save("update","user",Data,"where userid=1");
} // EOF
int ppl6::db::Postgres::SelectDB ( const char *  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]databasenameName der gewünschten Datenbank
Rückgabe
Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.

Erneute Implementation von ppl6::db::Database.

void ppl6::db::Database::SetLogfile ( CLog log = NULL)
inherited
Beschreibung:
Mit dieser Funktion kann ein Querylog aktiviert oder deaktiviert 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]logPointer auf eine Klasse vom Typ CLog, um das Logging zu aktivieren, oder NULL um es zu deaktivieren.
void ppl6::db::Database::SetLogfile ( CLog log)
inherited
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]logReferenz auf eine Klasse vom Typ CLog.
Zu beachten
Soll das Logging deaktiviert werden, muss die Funktion mit NULL oder ohne Parameter aufgerufen werden.
void ppl6::db::Postgres::SetMaxRows ( ppluint64  rows)
virtual
Beschreibung:
Mit dieser Funktion wird festgelegt, wieviele Zeilen ein Select-Ergebnis maximal zurückgeben soll. Je nach Datenbank wird dies erreicht, in dem dem SQL-Query noch ein Limit mitgegeben wird.
Parameter
[in]rowsAnzahl maximaler Zeilen oder 0, wenn es kein Limit geben soll.

Erneute Implementation von ppl6::db::Database.

void ppl6::db::Database::SetParam ( const char *  name,
const char *  value 
)
inherited
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 überhaupt funktioniert, müssen diese zuvor mit SetParam gesetzt werden.
Parameter
[in]nameName des Parameters
[in]valueWert des Parameters als String
void ppl6::db::Database::SetParam ( const char *  name,
int  value 
)
inherited
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 überhaupt funktioniert, müssen diese zuvor mit SetParam gesetzt werden.
Parameter
[in]nameName des Parameters
[in]valueWert des Parameters als Integer
int ppl6::db::Postgres::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 von ppl6::db::Database.

void ppl6::db::Database::UpdateLastPing ( )
protectedinherited
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 ppl6::db::Database::UpdateLastUse ( )
protectedinherited
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.

Dokumentation der Datenelemente

pplint64 ppl6::db::Postgres::affectedrows
private
CAssocArray ppl6::db::Postgres::condata
private
void* ppl6::db::Postgres::conn
private
ppluint64 ppl6::db::Postgres::lastinsertid
private
ppluint64 ppl6::db::Postgres::maxrows
private
int ppl6::db::Postgres::transactiondepth
private

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