Instrukcja obsługi R2płatnik

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

Otwiera tabelę programu.

Parametry

• TableName - nazwa tabeli programu

• TableNameW - nazwa tabeli programu w formacie UNICODE

• DisableAfterOpen - blokuje wykonanie eventu DoAfterOpen (z reguły oznacza to, że tabela nie otwiera swoich detail'i)

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

• (1) OpenTable('PRACOWNICY',False) - otworzy tabelę z pracownikami oraz wszystkie podrzędne tabele (w zasadzie wszystkie tabele programu dotyczące części kadrowej) - bardzo długo

• (2) OpenTable('PRACOWNICY',True) - otworzy tylko tabelę z pracownikami - szybko

• (3) OpenTable('AKTUALNE ZATRUDNIENIE',True) - otworzy tylko tabelę z aktualnym zatrudnieniem - szybko

• (4) OpenTable('KARTA URLOPOWA',False) - otworzy tabelę z kartą urlopową oraz inne tabele potrzebne do poprawnego operowania na tabeli KARTA URLOPOWA - szybko ze względu na małą ilość tabel do otwarcia

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

• TableName - nazwa tabeli programu

• TableNameW - nazwa tabeli programu w formacie UNICODE

• DisableAfterOpen - blokuje wykonanie eventu DoAfterOpen (z reguły oznacza to, że tabela nie otwiera swoich detail'i)

• Filter - filtr SQL, który zawęża zestaw zwracanych rekordów

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

• Handle - uchwyt tabeli zwrócony przez OpenTable

• IndexFieldNames - lista nazw pól sortujących oddzielonych średnikami lub przecinkami

• IndexFieldNamesW - lista pól sortujących w standardzie UNICODE

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

Przesuwa kursor na następny/poprzedni rekord tabeli.

Parametry

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

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

Parametry

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

• KeyFields - lista nazw pól kluczowych, po których następuje pozycjonowanie kursora tabeli, nazwy pól powinny być oddzielone średnikami

• KeyFieldsW - lista nazw pól kluczowych w formacie UNICODE

• KeyValues - lista wartości pól kluczowych, według których następuje pozycjonowanie kursora tabeli, lista wartości pól powinna być zadana jako tablica typów Variant

• Ref - jeśli True, to przed lokowaniem kursora tabela zostanie odświeżona.

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

Zwracane wartości

Jeśli podana tabela istnieje, zwraca stan tabeli:

• 0 - tabela nieaktywna (nie otwarta)
• 1 - tabela w trybie przeglądania (dsBrowse)
• 2 - tabela w trybie edycji (dsEdit)
• 3 - tabela w trybie wprowadzania nowego rekordu (dsInsert)

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

• Value - True - blokuje lub False uaktywnia wykonywanie eventów

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

• Value - True - blokuje lub False uaktywnia odświeżanie

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

• Value - miejsce na zmienną typu string (łańcuch znaków) dla zwróconego zapytania SQL (ANSI)

• ValueW - miejsce na zmienną typu string (łańcuch znaków) dla zwróconego zapytania SQL (UNICODE)

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

• Param - numer parametru (zaczyna się od 0)

• Value - wartość parametru

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

• Lookups - jeśli True, to odświeża także tabele połączone z polami typu lookup

• Force - jeśli True, to odświeża tabelę niezależnie od wewnętrznego licznika zmian

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

• Handle - uchwyt tabeli zwrócony przez OpenTable()

Zwracane wartości

Liczba pól tabeli

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

Podaje definicje pól tabeli

Parametry

• Handle - uchwyt tabeli zwrócony przez OpenTable()

• Struct - wskaźnik na tablicę pól o strukturze FIELDSTRUCT

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).