Dostępne rodzaje funkcji w gniazdach rozszerzeń

Jesteś tutaj:
< Powrót

Dostępne rodzaje funkcji w gniazdach rozszerzeń

W gniazdach rozszerzeń można stosować 9 typów funkcji:

  • Procedura SQL
  • Skrypt VBS
  • Moduł wykonywalny
  • Komunikat – wywołanie okna komunikatu
  • Pytanie – wywołanie okna zapytania
  • Koniec – funkcja przerywająca (kończąca) działanie gniazda rozszerzeń
  • Tabela dodatkowa – wywołanie tabeli dodatkowej
  • Formularz tabeli – wywołanie formularza tabeli dodatkowej
  • IF (warunek) THEN ELSE – instrukcja warunkowego wykonania

Funkcje w zależności od typu przyjmują różne parametry natomiast elementami wspólnymi dla wszystkich funkcji są ( Rys. 4 ):

  • nazwa funkcji – obowiązkowa do wypełnienia nazwa własna definiowanej funkcji;
  • opis – w którym możemy zawrzeć własny, dodatkowy komentarz do działań jakie realizuje funkcja;

Rys. 4 Formularz edycji funkcji w gnieździe rozszerzeń

Zarówno nazwa jak i opis widoczne są w Edytorze gniazd rozszerzeń bez konieczności otwierania formularza. Wygląd formularza zmienia się w zależności od typu funkcji, którą wybiera się z listy dostępnych typów.
W kolejnych rozdziałach omówione zostaną parametry możliwe do przekazania w poszczególnych typach funkcji.

Procedura SQL

Procedura SQL (Rys. 4) jest podstawową funkcją używaną w gniazdach. Aby możliwe było uruchomienie przez gniazdo procedury SQL spełnione muszą być dwa warunki:
1) procedura musi istnieć w bazie danych i musi posiadać parametry podawane w takiej kolejności i takich typów jakie zdefiniowano w polu „Lista parametrów”;
2) nazwa procedury musi być w ustalonym formacie tzn. zaczynać się od ciągu znaków „MAGSRC_”.
W polu „Lista parametrów” parametry procedury podaje się zgodnie ze składnią SQL tzn. oddziela przecinkami. Przy parametrach wyjściowych należy pamiętać o słowie kluczowym OUTPUT. Nie ma potrzeby wpisywania parametrów ręcznie – można skorzystać z podpowiedzi dostępnej pod przyciskiem „Wybierz zmienne aplikacji” (F4) , której uruchomienie skutkuje pojawieniem się okna wyboru parametrów (Rys. 5).

Każda zmienna widoczna w oknie wyboru na liście „Dostępne parametry” może być użyta jako parametr funkcji. Obok nazwy zmiennej uwidoczniony jest jej typ oraz w kolumnie „SQL output” wskaźnik czy zmienna jest wejściowo-wyściowa w gnieździe tzn. czy możliwa jest jej zmiana wartości w procedurze oraz przekazanie tej wartości dalej do gniazda. Tylko za pomocą procedury SQL można zmienić wartość zmiennej pod warunkiem, że jest ona typu „SQL output”. Zmienne z listy „Dostępne parametry” przenosimy przyciskami pomiędzy listami do wykazu „Wybranych parametrów”. Ważna jest kolejność wybranych parametrów (którą możemy w dowolnym momencie zmienić) ponieważ zmienne będą przekazywane do procedury w takiej kolejności jak widać na liście „Wybrane parametry”. Skompletowaną listę potrzebnych parametrów zatwierdzamy F10 co generuje w polu „Lista parametrów” formularza edycji funkcji zgodną ze składnią SQL listę zmiennych i ich typów oddzielonych przecinkami.
Po zdefiniowaniu listy parametrów przez gniazdo procedury SQL możemy podejrzeć sugerowany schemat tworzenia takich procedur, który został opracowany przy założeniu, że procedury będą zmieniały dane w bazie (stąd ujęcie kodu procedury w transakcję) (Rys. 6).

Rys. 6 Przykład zmodyfikowanego schematu procedury SQL
Klawiszem F3 uruchamiamy edytor zawierający schemat procedury. Schemat jest od razu dostosowany do definicji funkcji tzn. zawiera nazwę i parametry procedury SQL, które zostały wcześniej zdefiniowane (pole „nazwa” i „lista parametrów”). Schemat można dowolnie poprawić w edytorze i umieścić w bazie danych przyciskiem „Wykonaj SQL”. Zaleca się jednak aby schemat skopiować do schowka i dalej poddać wypełnieniu kodem, który procedura ma realizować w zewnętrznym edytorze SQL (np. SQL Management Studio).

W większości wypadków procedura SQL wywoływana jest przez gniazdo jednokrotnie dla zdefiniowanej listy parametrów. Jeśli chcemy wywołać ją ponowne musimy jeszcze raz zdefiniować w gnieździe jej wywołanie. Wyjątkiem są sytuacje gdy chcemy oprogramować wykonanie wielokrotne procedury dla zaznaczonych obiektów w WAPRO Mag. W takim przypadku należy zaznaczyć opcję „wykonaj w pętli dla zaznaczonych obiektów” jak również przekazać jako jeden z parametrów zmienną @IdObiektu, która będzie się zmieniać w kolejnych iteracjach. Trzeba pamiętać, że kod obsługi musimy napisać dla pojedynczego @IdObiektu a nie dla grupy zaznaczonych.
Należy pamiętać o specyficznym sposobie obsługi błędów sygnalizowanych w procedurze SQL (błędów wykonania SQL). Gniazda automatycznie po odebraniu sygnalizacji błędu wyświetlają komunikat o błędzie (zwracany z SQL funkcją raiserror) i przerywają dalsze wykonanie kodu zarówno umieszonego w gnieździe rozszerzeń jak i standardowego kodu programu, którego wykonanie nastąpiłoby normalnie po zakończeniu kodu gniazda (więcej nt. obsługi błędów w rozdziale 6.1).

Skrypt VBS

Wykonanie skryptu VBS jest możliwe tylko jeśli w środowisku systemu operacyjnego dostępny jest procesor skryptów VBS czyli program wscript.exe. Standardowo w systemach XP i Vista procesor skryptów VBS powinien być dostępny.
W polu „Ścieżka do skryptu” należy wskazać lokalizację pliku skryptu VBS wraz z jego nazwą widoczną dla wszystkich stacji roboczych WAPRO Maga. W szczególnym przypadku może to być katalog instalacyjny programu (nie zalecane!).
W polu „Parametr 2” można przekazać wartości zmiennych dostępnych w gnieździe. Wartości będą oddzielone przecinkami i ujęte w cudzysłów zgodnie z zasadami przekazywania parametrów do programów w środowisku systemu operacyjnego.
Skrypt powinien również odbierać wartość parametrów połączenia do bazy danych (tzw. Connection String) przekazywaną jako parametr 1. Parametry połączenia podawane są w kolejności: nazwa serwera, nazwa bazy danych, użytkownik serwera, hasło użytkownika serwera oddzielone przecinkami i oczywiście  ujęte w cudzysłowy.
Wartości zmienne oddzielone przecinkami najłatwiej w skrypcie VBS odebrać funkcją Split, która zwraca jednowymiarową tablicę wartości tekstowych z łańcucha znakowego, w którym wartości oddzielone są separatorami np. przecinkami.

Moduł wykonywalny

Moduły rozszerzeń muszą mieć postać wykonywalnych programów tzn. typu EXE lub BAT.
W polu „Ścieżka do modułu” należy wskazać lokalizację pliku modułu rozszerzeń wraz z jego nazwą widoczną dla wszystkich stacji roboczych WAPRO Maga. W szczególnym przypadku może to być katalog instalacyjny programu (nie zalecane!).
W polu „Parametr 2” można przekazać wartości zmiennych dostępnych w gnieździe. Wartości będą oddzielone przecinkami i ujęte w cudzysłów zgodnie z zasadami przekazywania parametrów do programów w środowisku systemu operacyjnego.
Moduł powinien również odbierać wartość parametrów połączenia do bazy danych (tzw. Connection String) przekazywaną jako parametr 1. Parametry połączenia podawane są w kolejności: nazwa serwera, nazwa bazy danych, użytkownik serwera, hasło użytkownika serwera oddzielone przecinkami i oczywiście  ujęte w cudzysłowy.

Komunikat
Komunikat wyświetla na ekranie okno dialogowe z przyciskiem OK. W polu „Treść komunikatu” można wstawić dowolny ciąg tekstowy lub wartość zmiennych wybranych przyciskiem „Wybierz zmienne aplikacji”. Umieszczenie w gnieździe funkcji typu „Komunikat” i uruchomienie wykonania powoduje wstrzymanie dalszego przetwarzania  kodu do czasu zamknięcia okna komunikatu.

Pytanie
Funkcja typu Pytanie wyświetla na ekranie okno dialogowe z przyciskami TAK i NIE. Podobnie jak w przypadku funkcji „Komunikat” możemy w treści pytania umieścić wartości dostępnych zmiennych w gnieździe, w którym uruchomione zostanie pytanie. Naciśnięcie przez użytkownika przycisku TAK w odpowiedzi na pytanie ustawia zmienną @OdpNaPytanie dostępną w gniazdach na wartość 1 zaś wybór przycisku NIE powoduje przypisanie wartości 0. Sprawdzenie wartości zmiennej i podjęcie dalszych działań umożliwia funkcja typu „IF (warunek) THEN ELSE” (instrukcja warunkowego wykonania – rozdział 3.9)
Funkcja typu Pytanie jest funkcją interakcji z użytkownikiem toteż jej wykonanie w gnieździe wstrzymuje wykonanie dalszej części kodu do czasu zamknięcia okna pytania.

Koniec
Funkcja Koniec przerywa bezwarunkowo wykonanie kodu gniazda rozszerzeń (nie kończy działania aplikacji). W zależności od parametru statusu końca program po wyjściu z gniazda może realizować standardową funkcjonalność (status = 1 OK) lub nie wykonywać standardowych funkcji i powrócić do miejsca, które aktywowało wykonanie gniazda (status = 0 Przerwij).

 

Tabela dodatkowa
Funkcja typu Tabela dodatkowa umożliwia wywołanie w kodzie gniazda okna listy wierszy tabeli dodatkowej zdefiniowanej wcześniej w programie. W polu „Nazwa SQL tabeli dodatkowej” należy wybrać z listy nazwę serwerową tabeli . Następnie trzeba podać wartość identyfikatora pola zależnego od kontekstu tabeli, w którym została zdefiniowana (czyli klucza obcego tabeli). Przykładowo jeśli tabela została zdefiniowana w kontekście firmy należy podać wartość identyfikatora id_firmy. Jeśli natomiast w kontekście pozycji dokumentu magazynowego, wtedy należy podać wartość identyfikatora pozycji id_poz_dok_mag (Rys. 7), dla którego będą pokazywane zapisy w oknie listy wierszy tabeli. Na postawie kontekstu w jakim została zdefiniowana tabela, program sam sugeruje nazwę identyfikatora, który jest wymagany. Wartość identyfikatora można przekazać jako wartość stałą (liczbę) lub wartość zmiennej dostępnej w gnieździe. W drugim przypadku nie ma znaczenia typ zmiennej tzn. czy zmienna jest tekstowa czy liczbowa – ważne aby zawierała wartość numeryczną, którą można skonwertować na wartość potrzebnego identyfikatora.
Wykonanie w gnieździe funkcji typu Tabela dodatkowa spowoduje wywołanie okna listy wierszy zdefiniowanej tabeli, zaś program będzie oczekiwał z dalszym wykonaniem kodu gniazda do czasu zamknięcia tego okna.

Rys. 7 Formularz definicji funkcji typu Tabela dodatkowa

 

Formularz tabeli
Funkcja typu Formularz tabeli (Rys. 8) umożliwia wywołanie w kodzie gniazda okna formularza edycji wiersza tabeli dodatkowej. Pierwsze dwa parametry tzn. „Nazwa SQL tabeli dodatkowej” i wartość identyfikatora pola zależnego od kontekstu tabeli (klucza obcego tabeli) definiuje się identycznie jak przy funkcji typu Tabela dodatkowa. Trzecim parametrem jest „Id wiersza tabeli dla potrzeb formularza”, w którym podajemy wartość kolumny IDENTYFIKATOR generowanej automatycznie podczas  definiowania tabeli dodatkowej.
Formularz może być wywołany w trybie dodawania lub poprawiania. Wstawienie wartości  0 (lub zmiennej zwracającej wartość zero) spowoduje, że formularz będzie uruchomiony w trybie dodawania wiersza do tabeli dodatkowej. Wstawienie wartości większej niż 0 spowoduje uruchomienie formularza w trybie poprawiania wiersza o identyfikatorze wiersza równym podanej wartości.
Zatwierdzenie formularza skutkuje ustawieniem wartości zmiennej @Status dostępnej w gnieździe na 1 zaś anulowanie – ustawieniem wartości 0. Można więc za pomocą warunku @Status > 0 w instrukcji warunkowego wykonania kodu sprawdzić czy użytkownik zatwierdził czy anulował formularz i uzależnić od tego sposób dalszego wykonania kodu gniazda.

Rys. 8 Formularz definicji funkcji typu Formularz tabeli

 

IF (warunek) THEN ELSE
Instrukcja warunkowego wykonania kodu gniazda IF (warunek) THEN ELSE umożliwia sterowanie wykonaniem funkcji zdefiniowanych w gnieździe w zależności od spełniania lub nie warunku podanego jako jej parametr. Warunek musi zwracać logiczną wartość PRAWDA lub FAŁSZ. Warunek, którego sprawdzenie zwraca wartość PRAWDA, powoduje przeniesienie sterowania do miejsca oznaczonego w edytorze gniazd rozszerzeń THEN i wykonanie sekwencji funkcji zaś zwrócenie wartości FAŁSZ (nie spełnienie warunku) powoduje, że wykonane zostaną funkcje po ELSE zaś te, które zostały umieszczone po THEN zostaną pominięte.
Instrukcja warunkowego wykonania jest funkcją złożoną tzn. jej umieszczenie w gnieździe powoduje powstanie dwóch gałęzi drzewa. Do gałęzi zawierającej w nazwie THEN dołączamy funkcje, których wykonanie będzie poprawne w przypadku spełnienia warunku zaś do gałęzi zawierającej w nazwie ELSE dołączyć należy funkcje, które powinny wykonać się gdy warunek nie jest spełniony.
Nie ma znaczenie poziom, na którym funkcje po  ELSE są dołączone tzn.
wykonanie funkcji pokazanych na Rys. 9:

Rys. 9 Instrukcja warunkowego wykonania – funkcja podpięta do ELSE

spowoduje efekt identyczny jak wykonanie funkcji pokazanych na Rys. 10.

Rys. 10  Instrukcja warunkowego wykonania – funkcja na tym samym poziomie co ELSE

Warunek buduje się w oparciu o zmienne. Wartości zmiennych można porównywać ze stałymi lub innymi zmiennymi za pomocą standardowych operatorów >,<,= itp.
Poszczególne elementy w warunku można łączyć operatorami logicznymi OR, AND. Stałe tekstowe należy ująć w cudzysłów.