Jakie rodzaje funkcji dostępne są w gniazdach rozszerzeń?

W gniazdach rozszerzeń można stosować dziewięć 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. Elementami wspólnymi dla wszystkich funkcji są:

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

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.

Jak uruchomić procedurę SQL?

Procedura SQL 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 po kliknięciu przycisku Wybierz zmienne aplikacji (klawisz F4) - uruchomienie skutkuje pojawieniem się okna wyboru parametrów.

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, a w kolumnie SQL output wskaźnik informujący o tym, czy zmienna jest wejściowo-wyjściowa w gnieździe, tzn. czy możliwa jest jej zmiana wartości w procedurze oraz przekazanie tej wartości 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 przenosi się przyciskami widocznymi 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 Zatwierdź (klawisz F10), co spowoduje wygenerowanie na formularzu edycji w polu Lista parametrów funkcji zgodnej ze składnią SQL listy 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ę.

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. Aby wywołać ją ponowne, należy raz jeszcze zdefiniować w gnieździe jej wywołanie. Wyjątkiem są sytuacje, gdy należy 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.

Jak wykonać 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 Mag. 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 w skrypcie VBS najłatwiej 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.

Jak działa 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 Mag. 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.

Jak dodać 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 powodują wstrzymanie dalszego przetwarzania kodu do czasu zamknięcia okna komunikatu.

Jak dodać pytanie?

Funkcja typu Pytanie wyświetla na ekranie okno dialogowe z przyciskami TAK i NIE. Podobnie jak w przypadku funkcji Komunikat, można 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.

Jak zakończyć wykonanie kodu gniazda rozszerzeń?

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

Jak dodać tabele dodatkowe?

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.

Jak dodać 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 należy podać 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.

Jak umieścić IF (warunek) THEN ELSE w gnieździe?

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.

Poziom, na którym funkcje po ELSE są dołączone nie ma znaczenia.

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.