B.15 PostgreSQL C-API
 
B.15.1 Übersetzen einer Anwendung
Benötigte Headerdatei:
#include <libpq-fe.h>
Compileraufruf (benötigt Pfad zum Include-Verzeichnis von PostgreSQL API):
$ gcc -c -I/usr/include/pgsql client_anwendung.c
Linkeraufruf (benötigt Pfadangaben zu den Bibliotheken von PostgreSQL API):
$ gcc -o client_anwendung client_anwendung.o \
-L/usr/lib/pgsql -lpq
B.15.2 Eine Verbindung zum PostgreSQL-Server herstellen
PGconn *PQconnectdb(const char *conninfo);
PGconn *PQsetdbLogin(const char *pghost,
const char *pgport,
const char *pgoptions,
const char *pgtty,
const char *dbName,
const char *login,
const char *pwd);
PGconn *PQsetdb(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName);
/* Nichtblockierende Funktionen */
PGconn *PQconnectStart(const char *conninfo);
PostgresPollingStatusType PQconnectPoll(PGconn *conn);
B.15.3 Status und Informationen zur Verbindung ermitteln
Tabelle B.75
Status und Informationen zur Verbindung ermitteln
| Funktion
|
Bedeutung
|
| ConnStatusType PQstatus(
const PGconn *conn);
|
Status des Verbindungsaufbaus überprüfen
|
| char *PQdb(
const PGconn *conn);
|
Gibt einen Zeiger zurück auf den Datenbanknamen der Verbindung.
|
| char *PQuser(
const PGconn *conn);
|
Gibt den Benutzernamen der Verbindung zurück.
|
| char *PQpass(
const PGconn *conn);
|
Gibt das Passwort der Verbindung zurück.
|
| char *PQhost(
const PGconn *conn);
|
Gibt den Serverhostnamen der Verbindung zurück.
|
| char *PQport(
const PGconn *conn);
|
Gibt den Port der Verbindung zurück.
|
| char *PQtty(const PGconn *conn);
|
Gibt das TTY für die Debugausgaben der Verbindung zurück.
|
| char *PQoptions(
const PGconn *conn);
|
Gibt Konfigurationsoptionen die der Verbindungsanfrage übergeben wurden zurück.
|
| int PQsocket(
const PGconn *conn);
|
Gibt die Deskriptornummer des mit dem Server verbundenen Sockets zurück. Bei –1 wird angezeigt, dass keine Verbindung besteht.
|
| int PQbackendPID(
const PGconn *conn);
|
Gibt die Prozesskennung (PID) des Serverprozesses zurück, der mit dieser Verbindung arbeite zurück.
|
| SSL *PQgetssl(
const PGconn *conn);
|
Hier wird eine SSL-Struktur zurückgegeben. Wird SSL nicht verwendet wird NULL zurückgegeben. Mehr dazu entnehmen Sie ggf. aus der Anleitung von OpenSSL.
|
B.15.4 Verbindung beenden oder wieder aufnehmen
Tabelle B.76
Verbindung beenden oder wieder aufnehmen
| Syntax
|
Bedeutung
|
| void PQfinish(PGconn *conn);
|
Verbindung schließen und den Speicher für das PGconn-Objekt wieder freigegeben
|
| void PQreset(PGconn *conn);
|
Schließt die Verbindung zum Server und versucht eine neue Verbindung zum selben Server mit den gleichen Parametern aufzubauen
|
| int PQresetStart(PGconn *conn);
PostgresPollingStatusType
PQresetPoll(PGconn *conn);
|
Für nicht blockierenden Verbindungen gibt es diese Funktionen die Versuchen eine Verbindung zu schließen und erneut mit demselben Server eine neue nicht blockierende Verbindung aufzubauen
|
B.15.5 SQL-Anfragen an den Server machen und den Status auswerten
Tabelle B.77
Anfrage an den Server und den Status auswerten
| Syntax
|
Bedeutung
|
| PGresult *PQexec(
PGconn *conn,
const char *command);
|
Anfragen an den Server
|
| ExecStatusType PQresultStatus(
const PGresult *res);
|
Rückgabe-Status der Anfrage
|
| char *PQresStatus(
ExecStatusType status);
|
Macht aus den von PQresultStatus() zurückgegebenen Wert eine aussagekräftige Stringkonstante
|
| char *PQresultErrorMessage(
const PGresult *res);
|
wie PQresultStatus() und PqresStatus() in einem Rutsch
|
B.15.6 Ergebnis einer SQL-Anfrage auswerten
Tabelle B.78
Funktionen, um das Ergebnis einer Anfrage auszuwerten
| Funktion
|
Bedeutung
|
| int PQntuples(
const PGresult *res);
|
Gibt die Anzahl der Zeilen (Tuples) des Anfrageergebnisses zurück.
|
| int PQnfields(
const PGresult *res);
|
Gibt die Anzahl der Spalten in einer Zeile des Anfrageergebnisses zurück.
|
| char *PQfname(
const PGresult *res,
int spalten_nummer);
|
Gibt den Namen der Spalte spalten_nummer – beginnend bei 0 – zurück.
|
| int PQfnumber(
const PGresult *res,
const char *field_name);
|
Gibt die Nummer der Spalte zum angegebene Spaltennamen field_name zurück.
|
| Oid PQftype(
const PGresult *res,
int spalten_nummer);
|
Hiermit können Sie den Datentypen der Spalte erfahren. Eine Übersicht der OIDs finden Sie in der Datei pg_type.h (meistens im Verzeichnis von libpq im Pfad server/catalog/pg_type.h zu finden).
|
| int PQfmod(
const PGresult *res,
int spalten_nummer);
|
Gibt die typenspezifischen Modifikationsdaten der Spalte (beginnend mit 0) mit der angegebenen Nummer zurück.
|
| int PQfsize(
const PGresult *res,
int spalten_nummer);
|
Gibt die Größe in Bytes der Spalte spalten_nummer zurück. Wird –1 zurückgegeben, handelt es sich um einen String variabler Länge.
|
| int PQbinaryTuples(
const PGresult *res);
|
Diese Funktion gibt 1 zurück, wenn PGresult binäre Zeilendaten enthält. Bei 0 handelt es sich um Texdaten.
|
| void PQclear(PQresult *res);
|
Speicherplatz der Anfrage freigeben
|
B.15.7 Rückgabe des Anfrageergebnisses auslesen
Tabelle B.79
Rückgabe des Anfrageergebnisses auslesen
| Syntax
|
Bedeutung
|
| char* PQgetvalue(
const PGresult *res,
int zeilen_nummer,
int spalten_nummer);
|
Einzelne Spaltenwerte auslesen
|
| int PQgetisnull(
const PGresult *res,
int zeilen_nummer,
int spalten_nummer);
|
Testet ob, der Wert einer Spalte gleich NULL ist
|
| int PQgetlength(
const PGresult *res,
int zeilen_nummer,
int spalten_nummer);
|
Länge des Datenwertes einer Spalte
|
B.15.8 Ergebnisse anderer Befehle ermitteln
Tabelle B.80
Ergebnisse anderer Befehle ermitteln
| Syntax
|
Bedeutung
|
| char * PQcmdStatus(
PGresult *res);
|
Gibt eine Statuszeichenkette für einen Befehl (bspw.: INSERT 16994 1) zurück
|
| char * PQcmdTuples(
PGresult *res);
|
Gibt die Anzahl der Zeilen, die auf einen SQL-Befehl wie INSERT, UPDATE oder DELETE eine Auswirkung hatte, zurück
|
| Oid PQoidValue(
const PGresult *res);
|
Gibt entweder einen (ganzzahligen) Wert vom Typ Oid oder im Falle eines Fehlers InvalidOid zurück
|
| char * PQoidStatus(
const PGresult *res);
|
Gibt eine Zeichenkette mit der OID der eingefügten Zeile zurück, wenn die SQL-Anweisung ein INSERT war – ansonsten 0 wenn die Zieltabelle keine OIDs hatte. Wenn der SQL-Befehl kein INSERT war, wird ein leerer String zurückgegeben.
|
|
