Operacje na tabelach

Funkcje API

function OpenTable(TableName:PChar; DisableAfterOpen:Boolean=False):LResult;stdcall;
function OpenTableW(TableNameW:PWideChar; DisableAfterOpen:Boolean=False):LResult;stdcall;

Otwiera tabelę programu.

Parametry

Zwracane wartości

Jeśli tabela o podanej nazwie istnieje i została otwarta to zwraca jej uchwyt. W przeciwnym wypadku zwraca 0, wtedy szczegółowy komunikat o błędzie można odczytać funkcją GetLastError().

Uwagi

Lista wszystkich tabel programu znajduje się w załaczniku. Zablokowanie eventu DoAfterOpen powoduje znaczne zmniejszenie pamięci potrzebnej do otwarcia tabeli i skrócenie czasu jej otwierania. Jednak należy mieć świadomość, że odpowiednie detaile, do których chcemy mieć dostęp należy otworzyć samemu.

Przykład

Jeśli w aplikacji chcemy pracować tylko na karcie urlopowej znacznie korzystniej jest otworzyć tabele (2), (3) i (4), zamiast (1) i (4);


function OpenTableEx(TableName:PChar; DisableAfterOpen:Boolean; Filter:PChar):LResult;stdcall;
function OpenTableExW(TableNameW:PWideChar; DisableAfterOpen:Boolean; Filter:PChar):LResult;stdcall;

Otwiera tabelę programu ograniczoną dodatkowym filtrem.

Parametry

Zwracane wartości

Jeśli tabela o podanej nazwie istnieje i została otwarta to zwraca jej uchwyt. W przeciwnym wypadku zwraca 0, wtedy szczegółowy komunikat o błędzie można odczytać funkcją GetLastError().

Uwagi

Funkcja analogiczna do OpenTable() z możliwością ograniczenia ilości dostępnych rekordów. Filtr tabeli, jako wyrażenie SQL, dopisuje się do klauzuli WHERE zapytania tabeli. Pozwala to na otwarcie tabeli zawierającej tylko określony zestaw rekordów np. zawężony do jakiegoś okresu lub nawet składający się z jednego rekordu np. [Nazwisko]='Kowalski'

Przykład

var PracT:integer;
PracT:=OpenTableEx('PRACOWNICY',False,'[Nazwisko]=''R2urlopowski'' AND [Imie]=''Jan''');
if PracT=0 then begin
   GetLastError(pca);
   ShowMessage(pca);
end;

KartaUrlopowaT:=OpenTableEx('KARTA URLOPOWA',False,'YEAR(OD)=2013'); //tylko wpisy z 2013 roku


procedure TableClose(Handle:integer);stdcall;

Zamyka tabelę.

Parametry


procedure CloseAllTables;stdcall;

Zamyka wszystkie otwarte tabele programu.

Uwagi

Standardowo nie musimy zamykać tabel, gdyż wszystkie otwarte tabele są automatycznie zamykane przed zakończeniem aplikacji. Możemy zamknąć wszystkie tabele (i potem otworzyć ponownie) podczas przelogowywania się na innego użytkownika lub podłączania do innej bazy danych.

Przykład

LogoffUser('');
CloseAllTables;
LoginUser('ALA','654321');


function TableRecordCount(Handle:integer):Integer;stdcall;

Podaje ilość rekordów tabeli.

Parametry

Zwracane wartości

Jeśli podana tabela istnieje, zwraca ilość rekordów tabeli. W przeciwnym wypadku zwraca -1 i wtedy szczegółowy komunikat o błędzie można odczytać funkcją GetLastError().


function TableOrder(Handle:integer; IndexFieldNames:PChar):Integer;stdcall;
function TableOrderW(Handle:integer; IndexFieldNamesW:PWideChar):Integer;stdcall;

Sortuje tabelę według zadanych pól.

Parametry

Zwracane wartości

Jeśli podana tabela istnieje i można ją posortować po zadanych polach zwraca True, w przeciwnym wypadku zwraca False i wtedy szczegółowy komunikat o błędzie można odczytać funkcją GetLastError().

if not TableOrder(PracT,'Nazwisko;Imie') then begin
   GetLastError(pca);
   ShowMessage(pca);
end;


procedure TableFirst(Handle:integer);stdcall;
procedure TableLast(Handle:integer);stdcall;

Ustawia kursor na pierwszym/ostatnim rekordzie tabeli.

Parametry


procedure TableNext(Handle:integer);stdcall;
procedure TablePrior(Handle:integer);stdcall;

Przesuwa kursor na następny/poprzedni rekord tabeli.

Parametry


function TableEOF(Handle:integer):Boolean;stdcall;
function TableBOF(Handle:integer):Boolean;stdcall;

Informuje, że kursor jest na końcu/początku tabeli.

Parametry

Zwracane wartości

Jeśli kursor jest na początku, czyli przed pierwszym rekordem tabeli zwraca True.

Uwagi

Oznacza to, że kursora nie można przesunąć już dalej na "koniec" funkcją TableNext, czyli kursor jest na końcu tabeli, a nie na ostatnim rekordzie.

Przykład

TableFirst(PracT);
while not TableEOF(PracT) do begin
   GetTableFieldAsString(PracT,'Nazwisko',pca);
   TableNext(PracT);
end;


function TableLocate(Handle:integer; KeyFields: PChar; KeyValues: Variant; Ref:Boolean=False):Boolean;stdcall;
function TableLocateW(Handle:integer; KeyFieldsW: PChar; KeyValues: OleVariant; Ref:Boolean=False):Boolean;stdcall;

Lokuje kursor tabeli na rekordzie spełniającym warunki zadane w KeyFields i KeyValues.

Parametry

Zwracane wartości

Jeśli kursor zostanie spozycjonowany na rekordzie, który spełnia zadane warunki, zwraca True. W przeciwnym wypadku można odczytać komunikat o błędzie funkcją GetLastError().

Przykład

if not TableLocate(PracT,'Nazwisko;Imie',VarArrayOf(['R2urlopowski','Jan'])) then begin
   GetLastError(pca);
   ShowMessage(pca);
end;

if not TableLocate(KartaUrlopowaT,'X_I',123) then exit;


function TableRecNo(Handle:integer):Integer;stdcall;

Podaje numer kolejny rekordu, na którym stoi kursor tabeli.

Parametry

Zwracane wartości

Jeśli podana tabela istnieje, zwraca numer kolejny rekordu, na którym stoi kursor tabeli; w przeciwnym wypadku zwraca -1 i szczegóły w GetLastError().


function TableSelectedRecord(Handle:integer):Boolean;stdcall;

Sprawdza, czy rekord jest podświetlony przez danego użytkownika.

Parametry

Zwracane wartości

Zwraca True jeśli aktualny rekord jest podświetlony, w przeciwnym wypadku False.

Uwagi

Funkcja szczególnie przydatna, jeśli nasza aplikacja uruchamiana jest razem z programem (przy wykorzystaniu funkcji LoginUserAsProgram()). Wtedy możemy wykorzystać informację o podświetlonych rekordach w programie (przez tego samego użytkownika).


function TableInsert(Handle:integer):Boolean;stdcall;

Dostawia nowy rekord do tabeli.

Parametry

Zwracane wartości

Zwraca True jeśli tabela znajdzie się w stanie dsInsert, czyli nowy rekord został dostawiony, ale jeszcze nie zatwierdzony. Jeśli z jakiegoś powodu nie da się dostawić nowego rekordu to funkcja zwróci False i wtedy powód odmowy można odczytać funkcją GetLastError().

Uwagi

Po dostawieniu nowego rekordu tą funkcją wartości wszystkich pól zainicjują się tak samo jak w programie. Należy uzupełnić wartości wybranych pól i zatwierdzić rekord funkcją TablePost().

Przykład

if not TableInsert(KartaUrlopowaT) then begin
   GetLastError(pca);
   ShowMessage(pca);
   exit;
end;
SetTableFieldAsInteger(KartaUrlopowaT,'R_DNIA',0);//rodzaj urlopu: 0-wypoczynkowy
SetTableFieldAsDate(KartaUrlopowaT,'Od',StrToDate('2013-11-20'));
SetTableFieldAsDate(KartaUrlopowaT,'Do',StrToDate('2013-11-21'));
SetTableFieldAsInteger(KartaUrlopowaT,'STATUS',1);//status: 0-zatwierdzony, 1-planowany
if not TablePost(KartaUrlopowaT) then begin
   GetLastError(pca);
   ShowMessage(pca);
   TableCancel(KartaUrlopowaT);
end;


function TableEdit(Handle:integer):Boolean;stdcall;

Wprowadza rekord tabeli w stan edycji.

Parametry

Zwracane wartości

Zwraca True jeśli tabela znajdzie się w stanie dsEdit, czyli bieżący rekord jest edytowany. Jeśli z jakiegoś powodu nie da się dostawić nowego rekordu (np. rekord jest edytowany przez innego użytkownika) to funkcja zwróci False i wtedy powód odmowy można odczytać funkcją GetLastError().

Uwagi

Po wprowadzedniu rekordu w stan dsEdit należy poprawić wartości wybranych pól i zatwierdzić rekord funkcją TablePost().

Przykład

if not TableEdit(DanePersonalneT) then begin
   GetLastError(pca);
   ShowMessage(pca);
   exit;
end;
SetTableFieldAsString(DanePersonalneT,'Drugie_imie','Tomasz');
if not TablePost(DanePersonalneT) then begin
   GetLastError(pca);
   ShowMessage(pca);
   TableCancel(DanePersonalneT);
end;


function TablePost(Handle:integer):Boolean;stdcall;

Zatwierdza nowy rekord lub zmiany rekordu tabeli.

Parametry

Zwracane wartości

Jeśli z jakiegoś powodu nie da się zatwierdzić rekordu (np. nowe wartości pól są niedopuszczalne) to funkcja zwróci False i wtedy powód odmowy można odczytać funkcją GetLastError(). Jeśli nowy lub edytowany rekord zostanie zatwierdzony, czyli tabela znajdzie się w stanie dsBrowse to funkcja zwróci True. W takim przypadku można również odczytać ewentualne ostrzeżenie (mimo akceptacji) funkcją GetLastError().

Uwagi

W przypadku odmowy zatwierdzenia rekordu tabela pozostanie w stanie dsInsert lub dsEdit. Należy wtedy wpisać akceptowalne wartości pól lub anulować wprowadzone zmiany funkcją TableCancel().

Przykład

if not TablePost(KartaUrlopowaT) then begin
   GetLastError(pca);
   ShowMessage(pca);
   TableCancel(KartaUrlopowaT);
   exit;
end;
if GetLastError(pca) then ShowMessage('Nowy urlop został zapisany.'+#13#10+pca) //np. ostrzeżenie o przekroczeniu limitu
else ShowMessage('Nowy urlop został zapisany');


function TableCancel(Handle:integer):Boolean;stdcall;

Anuluje nowy rekord lub zmiany rekordu tabeli.

Parametry

Zwracane wartości

Zwraca True jeśli tabela znajdzie się w stanie dsBrowse, czyli nowy lub edytowany rekord zostanie anulowany. W przeciwnym wypadku można odczytać komunikat o błędzie funkcją GetLastError().

Uwagi

Jeśli z jakiegoś powodu, po dostawieniu nowego rekordu lub wprowadzeniu rekordu w stan edycji (TableInsert(), TableEdit) i wypełnieniu pól rekordu wartościami chcemy anulować wprowadzone zmiany, należy użyć tej funkcji.

Przykład

TableEdit(DanePersonalneT);
if not SetTableFieldAsString(DanePersonalneT,'PESEL','11223344444') then begin //kontrola poprawnego wypełnienia pola
   GetLastError(pca);
   ShowMessage(pca);
   TableCancel(DanePersonalneT);
end;


function TableDelete(Handle:integer):Boolean;stdcall;

Usuwa bieżący rekord tabeli.

Parametry

Zwracane wartości

Zwraca True jeśli rekord tabeli został usunięty. W przeciwnym wypadku funkcją GetLastError() można odczytać komunikat o odmowie wykasowania rekordu.

Przykład

if not TableDelete(KartaUrlopowaT) then begin
   GetLastError(pca);
   ShowMessage(pca);
end;


function TableState(Handle:integer):Integer;stdcall;

Podaje stan tabeli.

Parametry

Zwracane wartości

Jeśli podana tabela istnieje, zwraca stan tabeli:

Jeśli tabela nie istnieje zwraca -1 - enentualny komunikat o błędzie w funkcji GetLastError().


function TableDisableEvents(Handle:integer; Value:Boolean):Boolean;stdcall;

Blokuje lub uaktywnia wykonywanie wewnętrznych zdarzeń podczas edycji tabeli.

Parametry

Zwracane wartości

Zwraca True jeśli eventy zostały zablokowane lub uaktywnione.

Uwagi

Przy każdej operacji na tabeli typu TableInsert(), TableEdit(), TablePost() czy TableDelete, wykonują się wewnętrzne zdarzenia implikowane przez warstę logiczną aplikacji. Zablokowanie tych zdarzeń nie jest zalecane, mimo, iż znacznie przyspieszy to wykonanie operacji na tabeli, gdyż powoduje tylko "czyste" dostawienie, edytowanie bądź kasowanie rekordu. Należy więc bardzo uważać, aby nie zablokować czynności powiązanych, które aplikacja powinna standardowo wykonać. Na przykład dostawienie rekordu do tabeli PRACOWNICY normalnie powoduje także utworzenie odpowiedniego rekordu w tabeli AKTUALNE ZATRUDNIENIE oraz w kilku innych tabelach, ale już sama edycja notatek (która nie implikuje zdarzeń powiązanych, np. walidacji innych pól) może być wykonana przy wyłączonych zdarzeniach wewnętrznych.

Przykład

TableDisableEvents(PracT,true);
try
   TableEdit(PracT);
   SetTableFieldAsString(PracT,'N1','notatka 1');
   SetTableFieldAsString(PracT,'N2','notatka 2');
   TablePost(PracT);
finally
   TableDisableEvents(PracT,false);
end;


function TableDisableMasterDetail(Handle:integer; Value:Boolean):Boolean;stdcall;

Blokuje lub uaktywnia odświeżanie tabel powiązanych (datail'i) podczas nawigacji tabeli głównej (master), comoże znacznie przyspieszyć odczytywanie zawartości tabeli głównej.

Parametry

Zwracane wartości

Zwraca True jeśli odświeżanie zostało zablokowane lub uaktywnione.

Uwagi

Podczas nawigowania tabeli funkcjami typu TableNext(), TablePrior(), odświeżają się zawartości tabel podrzędnych. Zablokowanie tego odświeżania znacznie przyspiesza nawigowanie tabeli, bo powoduje tylko "czyste" przejście do następnego bądź poprzedniego rekordu. Jeśli chcemy wykonywać operacje na tabelach podrzędnych to należy pamiętać, żeby odświeżanie z powrotem odblokować.

Przykład

TableDisableMasterDetail(PracT,true);
try
   TableFirst(PracT);
   while not TableEOF(PracT) do begin
      GetTableFieldAsString(PracT,'Nazwisko',pca);
      TableNext(PracT);
   end;
finally
   TableDisableMasterDetail(PracT,false);
end;


procedure GetTableSQL(Handle:integer; Value:PChar);stdcall;
procedure GetTableSQLW(Handle:integer; ValueW:PWideChar);stdcall;

Podaje zapytanie SQL tabeli.

Parametry

Zwracane wartości

Zwraca zapytanie SQL dla podanej tabeli


procedure TableSetParam(Handle, Param:integer; Value:Variant);stdcall;
procedure TableSetParamW(Handle, Param:integer; Value:OleVariant);stdcall;

Ustawia wartość parametru w tabeli.

Parametry

Uwagi

Jeśli zapytanie SQL tabeli jest sparametryzowane (tzn. zawiera wyrażenie typu: Parametr, to do jego wykonania jest potrzebna wartość parametru. Powyższa funkcja ustawia tę wartość. Potem należy użyć procedury Requery, aby wykonać sparametryzowne zapytanie SQL i odświeżyć zawartość tabeli


procedure TableRequery(Handle:integer);stdcall;

Odświeża tabelę.

Parametry

Uwagi

Po otwarciu tabeli zestaw rekordów zawiera najświeższe informacje z bazy danych, jednak po pewnym czasie, jeśli z tabeli korzystają inni użytkownicy ulega on deaktualizacji. Jeśli chcemy mieć aktualne dane z bazy danych należy użyć tej funkcji. Przy operacjach na tabeli typu Locate, Insert, Edit czy Delete odświeżanie następuje automatycznie.


procedure TableRefresh(Handle:integer; Lookups:Boolean=False; Force:Boolean=False);stdcall;

Odświeża tabelę.

Parametry

Uwagi

Po otwarciu tabeli zestaw rekordów zawiera najświeższe informacje z bazy danych, jednak po pewnym czasie, jeśli z tabeli korzystają inni użytkownicy ulega on deaktualizacji. Jeśli chcemy mieć aktualne dane z bazy danych należy użyć tej funkcji. Przy operacjach na tabeli typu Locate, Insert, Edit czy Delete odświeżanie następuje automatycznie. W odróżnieniu od TableRequery() ta procedura odświeża tabelę tylko gdy wykryje zmiany w wewnętrzym liczniku zmian, bądź przy ustawieniu flagi Force na wartość True


function GetTableFieldCount(Handle:integer):integer;stdcall;

Zwraca liczbę pól tabeli.

Parametry

Zwracane wartości

Liczba pól tabeli


function GetTableFieldDefs(Handle:integer; Struct:Pointer):integer;stdcall;

Podaje definicje pól tabeli

Parametry

Zwracane wartości

Liczba pól tabeli

Uwagi

Definicje pól są wpisywane do tablicy rekordów o strukturze typu FIELDSTRUCT
Liczbę elementów tej tablicy można ustalić za pomocą funkcji GetTableFieldCount(), albo ustawić na odpowiednio dużą wartość; np. 255. Jako parametr funkcji należy podać wskaźnik na tę tablicę (adres tablicy).