Rodzaje funkcji w gniazdach rozszerzeń Wapro Anywhere

W Wapro Anywhere udostępniono możliwość korrzystania z nastepujących funkcji dla gniazd rozszerzeń:

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

Wszystkie kategorie funkcji mają różne parametry zależnie od ich typu. Niemniej jednak istnieją pewne elementy wspólne dla każdej z funkcji:

• nazwa funkcji – to obowiązkowe pole, w którym należy wprowadzić unikalną nazwę dla definiowanej funkcji;
• opis – ten obszar pozwala na zawarcie dodatkowego komentarza dotyczącego działań, jakie realizuje dana 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 ulega zmianie w zależności od wybranego typu funkcji dostępnego z listy.

W dalszych rozdziałach zostaną szczegółowo omówione parametry, które można przekazać w poszczególnych typach funkcji.

Procedura SQL

Funkcja Procedury SQL stanowi fundamentalny element w gniazdach rozszerzeń. Aby móc skutecznie wywołać procedurę SQL za pomocą gniazda, istnieją dwa wymagania do spełnienia:

1. Procedura musi istnieć w bazie danych i posiadać parametry, które należy przekazać w dokładnie takiej kolejności i typach, jak zdefiniowano w polu Lista parametrów.
2. Nazwa procedury musi być zapisana w ustalonym formacie tj. musi zaczynać się od ciągu znaków „MAGSRC_”.

W polu Lista parametrów parametry procedury należy wprowadzić zgodnie ze składnią SQL, oddzielając je przecinkami. Przy parametrach wyjściowych konieczne jest uwzględnienie słowa kluczowego OUTPUT. Parametry nie muszą być ręcznie wprowadzane, ponieważ istnieje opcja skorzystania z podpowiedzi dostępnej po kliknięciu przycisku Wybierz zmienne aplikacji (F4), co otworzy okno wyboru parametrów.

PowiększPowiększ

Każda zmienna widoczna w oknie wyboru na liście Dostępne parametry może być użyta jako parametr funkcji. Obok nazwy zmiennej widoczny jest jej typ, a w kolumnie SQL output wskaźnik informujący czy zmienna jest wejściowo-wyściowa w gnieździe, czyli czy można zmienić jej wartość w procedurze i przekazać ją dalej do gniazda. Wartość zmiennej można modyfikować tylko za pomocą procedury SQL 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żna 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 należy zatwierdzić przyciskiem 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żliwe jest podejrzenie sugerowanego schematu tworzenia takich procedur, które zostały opracowane przy założeniu, że procedury będą zmieniały dane w bazie - stąd ujęcie kodu procedury w transakcję.

Rys. 6 Przykład zmodyfikowanego schematu procedury SQL

Za pomocą klawisza F3 uruchamiany jest 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 jest przez gniazdo jednokrotnie wywoływana dla zdefiniowanej listy parametrów. Jeśli chcemy wywołać ją ponowne, musimy raz jeszcze zdefiniować w gnieździe jej wywołanie. Wyjątkiem są sytuacje, gdy chcemy oprogramować wykonanie wielokrotne procedury dla zaznaczonych obiektów w Wapro Anywhere. 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.

Skrypt VBS

Wykonanie skryptu VBS jest możliwe pod warunkiem, że w środowisku systemu operacyjnego dostępny jest procesor skryptów VBS, czyli program wscript.exe.

W polu Ścieżka do skryptu należy wskazać lokalizację pliku skryptu VBS wraz z jego nazwą widoczną dla wszystkich stacji roboczych Wapro Anywhere. W szczególnym przypadku może to być katalog instalacyjny programu (nie jest to zalecana opcja).

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 i są oddzielone przecinkami oraz 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 Anywhere. W szczególnym przypadku może to być katalog instalacyjny programu (nie jest to zalecana opcja).

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

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 została zdefiniowana w kontekście pozycji dokumentu magazynowego, wtedy należy podać wartość identyfikatora pozycji id_poz_dok_mag, 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 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" (niespeł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 poniższym obrazie:

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, np. ">", "<", "=" itp.

Poszczególne elementy w warunku można łączyć operatorami logicznymi OR, AND. Stałe tekstowe należy ująć w cudzysłów.