Rozdział 8

CLI (Call Level Interface)

8.1 Wprowadzenie

Call Level Interface to biblioteka procedur, służących do kontaktu z bazami danych SQL, w tym przypadku języka C. W PostgreSQL biblioteka taka nazywa się libpq.

Program w C z wywołaniami funkcji bibliotecznych libpq przetwarza się normalnie kompilatorem C na program wykonywalny, dołączając odpowiednie biblioteki.

cc -I`pg_config --includedir` -o test1 test1.c -lpq

8.2 Połączenie

Aby połączyć się z bazą danych należy użyć procedury:

  conn = PQconnectdb("host=libdb dbname=bd user=scott password=tiger");

zaś rozłączenia (także w przypadku niepowodzenia) dokonujemy pisząc

  PQfinish(conn);

Zmienna conn jest typu PGconn* i reprezentuje (być może nawiązane) połączenie. Aby sprawdzić, czy próba połączenia powiodła się, należy wywołać

  status = PQstatus(conn);

Jeśli wartością status będzie CONNECTION_BAD, to nie udało się. W przeciwnym razie wartością status powinno być CONNECTION_OK.

8.3 Polecenia SQL

Polecenia SQL przekazujemy do serwera funkcją

  wynik = PQexec(conn, "SELECT gatunek FROM Gatunki");

Zmienna wynik jest typu PGresult i reprezentuje (jeśłi nie jest NULL) otrzymany wynik. Aby stwierdzić, czy polecenie wykonało się poprawni, należy wywołać

  status = PQresultStatus(wynik);

Poprawne odpowiedzi to PGRES_TUPLES_OK dla zapytań oraz PG_COMMAND_OK dla poleceń nie zwracających wierszy tabeli. Po wykorzystaniu wyniku polecenia należy zwolnić zajmowaną pamięć

  PQclear(wynik);

8.4 Zapytania

Zajmiemy się teraz dostępem do wyszukanej informacji. Poniższe procedury podają liczbę wierszy i kolumn:

  int ile_wierszy = PQntuples(wynik);
  int ile_kolumn = PQnfields(wynik);

Podając numer można otrzymać nazwę kolumny:

  char* nazwa = PQfname(wynik, 0);

Aby otrzymać wartość w kolumnie dla danego wiersza, należy użyć

  int wiersz = 3;
  int kolumna = 1;
  char* pole = PQgetvalue(wynik, wiersz, kolumna);

Dla wartości pustych otrzymamy pusty napis (""). Aby sprawdzić, czy wynik zawiera wartość pustą, wywołujemy

  if (PQgetisnull(wynik, wiersz, kolumna))
    ...

natomiast długość pola otrzymamy przez

  int rozmiar = PQgetlength(wynik, wiersz, kolumna);

(dla napisów wynik jest taki sam jak dla strlen(), w przypadku wartości binarnych tak nie będzie).

8.5 Inne polecenia

Dla innych poleceń funkcja

  char* status = PQcmdStatus(wynik);

zwraca napis bedący zwykle nazwą polecenia, ale czasem zawierający dodatkowe informacje np. liczbę przetworzonych wierszy. Liczbę przetworzonych wierszy można też otrzymać (jako napis!) bezpośrednio wołając

  char* ile = PQcmdTuples(wynik)