Zmienne (parametry funkcji) gniazd rozszerzeń
Zmienne w przypadku Wapro Anywhere zostały zmodyfikowane do operowania obiektami JSON, w których użytkownik ma dostęp do pełnego stanu sesji i obiektu, na której operuje dane gniazdo.
Parametry w gniazdach Wapro Anywhere do np procedur SQL mają określoną strukturę i nazwy i dostepne są w definicji przykładowej procedury. Procedura powinna mieć 4 parametry - operowanie zmiennymi odbywa się na zasadzie obiektu JSON zarówno w danych wejściowych ja i wyjściowych:
- @sesion varchar(max) - w tej zmiennej znajdują się wszystkie informacje o sesji w aplikacji (dostępne tu są informacje o aktualnie wybranej firmie, magazynie, użytkowniku czy języku)
- @data varchar(max) - w tej zmiennej zawarte są pola formularza lub listy, która dostępna była akurat w danym gnieździe
- @result varchar(max) - w tej zmiennej dostępny jest obiekt analogiczny do @data ale już po zmianie danych (jeśli procedura nadpisała w obiekcie @data dane w jakimś polu to zmienna @result będzie interpretowana na aplikacji frontend celem ustawienia nowej wartości w polu formularza po wykonaniu gniazda)
- @errorData varchar(max) - w tej zmiennej znajdują się ewentualne informacje o błędach, które aplikacja powinna odebrać w przypadku wystąpienia błędu w trakcie wykonania procedury
Schemat procedury w aplikacji zawarty w aplikacji Wapro Anywhere pokazuje w jaki sposób odczytywać z poszczególnych obiektów dane oraz jak je w nich modyfikować aby za pomocą gniazda zmienić zawartość w kodzie SQL a następnie aby aplikacja zinterpretowała nowe wartości i odświeżyła je w formularzu aplikacji.
Podstawowy podział zmiennych można wyróżnić na:
- zmienne systmowe - dostępne globalnie w aplikacji
- zmienne kontekstowe - dostępne w zależności od formularza np. nazwa kontrahenta lub artykułu zależy wprost od formularza, na której dane gniazdo działa
Sposób wykorzystania zmiennych w funkcjach jest identyczny i nie zależy od rodzaju zmiennych. To co odróżnia ww. rodzaje zmiennych, to fakt, że zmienne systemowe występują zawsze w każdym gnieździe programu, natomiast zmienne kontekstowe dostępne są tylko w tych gniazdach, w których mogą być sensownie wykorzystane.
Przykładowo zmienna $Brutto_Netto przechowująca informacje o tym, czy dokument liczony jest od kwoty brutto czy od kwoty netto pojawia się w gnieździe o adresie Dokumenty handlowe | Okno danych dokumentu handlowego | Dodawanie lub poprawianie dokumentu | Zatwierdzenie danych dokumentu | Przed. Nie znajdziemy jej natomiast w gniazdach związanych z kartoteką artykułów.
Lista dostępnych w danym gnieździe zmiennych znajduje się w sekcji F4 (Lista zmiennych) na formularzu definicji funkcji. Okno Parametr operacji zawiera listę, która prezentuje zmienne możliwe do wykorzystania w danym gnieździe i dla danego typu funkcji. Zmienne przechowują informacje o wartościach danych dostępnych w miejscu programu, w którym definiujemy funkcję.
Generalnie zmienne umożliwiają tylko odczyt wartości. W przypadku funkcji typu Procedura SQL możliwa jest jednak zmiana wartości niektórych z nich.
Zmiana wartości zmiennej polega na nadpisaniu obiektu @data w kodzie SQL poprzez modyfikację obiektu JSON. Zmodyfikowany obiekt jest zwrotnie interpretowany przez aplikację celem odczytania danych do formularza.
Operowanie zmiennymi JSON znajdziesz w dokumentacji języka T-SQL na stronie producenta firmy Microsoft. Główne funkcje używane do operowania zmiennymi to OPENJSON do odczytu oraz MODIFY do modifykacji.
Osobną rolę w gniazdach spełniają zmienne systemowe. Ich pełna lista wraz z objaśnieniem znajduje się w poniższej tabeli.
| Nazwa zmiennej | Typ wartości (SQL) | Znaczenie |
|---|---|---|
| @TekstBledu | varchar(255) | przechowuje tekst błędu ostatnio wykonanej funkcji, np. w przypadku procedury SQL będzie to tekst zwracany funkcją raiseerror |
| @BylBlad | tinyint | zawiera wartość "1", jeśli funkcja zakończyła się błędem i "0", jeśli jej wykonanie przebiegło poprawnie |
| @IdFirmy | numeric | id_firmy, w kontekście której pracuje program |
| @IdMagazynu | numeric | id_magazynu, w kontekście którego pracuje program |
| @IdObiektu | numeric | w zależności od umiejscowienia gniazda jest to identyfikator dokumentu (zapisu w kartotece) lub pozycji dokumentu - analogicznie do raportów Crystal Reports oraz operacji dodatkowych |
| @IdUzytkownika | numeric | id_użytkownika aktualnie pracującego w Wapro Anywhere (wykonującego funkcję w gnieździe) |
| @ZakresDatyOd | int | data początku ustawionego zakresu dat w programie w formacie Wapro Anywhere |
| @ZakresDatyDo | int | data końca ustawionego zakresu dat w programie w formacie Wapro Anywhere |
| @OpisZakresuDat | varchar(255) | opis zakresu dat, który w programie jest widoczny na dolnej belce statusowej |
| @KodKontekstu_Uzycie | int | wartość pola UZYCIE tabeli ZAZNACZONE, automatycznie ustawiana przez program przy zaznaczaniu elementów list w zależności od miejsca listy w programie |
| @Wynik1 | varchar(255) | zmienna dla programisty gniazd - do dowolnego wykorzystania w funkcjach |
| @Wynik2 | varchar(255) | zmienna dla programisty gniazd - do dowolnego wykorzystania w funkcjach |
| @Wynik3 | varchar(255) | zmienna dla programisty - do dowolnego wykorzystania w funkcjach |
| @OdpNaPytanie | tinyint | przechowuje stan ostatniej odpowiedzi na pytanie - wartość "1" oznacza, że wybrano odpowiedź "TAK" na oknie dialogowym |
| @IdObiektuNadrzednego | numeric | analogiczna do @IdObiektu, z tym że wszędzie tam gdzie @IdObiektu będzie równe id_pozycji dokumentu, to @IdObiektuNadrzednego będzie równe identyfikatorowi dokumentu. Dla dokumentów @IdObiektu = @IdObiektuNadrzednego lub @IdObiektuNadrzednego = "0" |
| @Status | tinyint | przechowuje wartość "1", jeśli ostatnio uruchamiany w gnieździe formularz tabeli dodatkowej został zatwierdzony i wartość "0", jeśli została anulowana |
Zmienne systemowe można więc podzielić na dwie podgrupy:
- Zmienne przechowujące aktualne ustawienia środowiska Wapro Anywhere (@IdFirmy, @IdMagazynu, @IdObiektu, @IdUzytkownika, @ZakresDatyOd, @ZakresDatyDo, @OpisZakresuDat, @KodKontekstu_Uzycie, @IdObiektuNadrzednego);
- Zmienne przechowujące dane zwracane przez określone typy funkcji lub obsługujące sygnalizację błędu (@TekstBledu, @BylBlad, @Wynik1, @Wynik2, @Wynik3, @OdpNaPytanie, @Status).
Na szczególną uwagę zasługują zmienne @TekstBledu i @BylBlad, co wynika ze sposobu obsługi błędów w gniazdach rozszerzeń. Standardowo po odebraniu sygnalizacji błędu wygenerowanego przez funkcję wyświetlany jest komunikat o błędzie (zwracany np. z procedury SQL funkcją raiserror), a następnie przerywane jest dalsze wykonanie kodu zarówno umieszonego w gnieździe rozszerzeń, jak i kodu programu, którego wykonanie nastąpiłoby normalnie po zakończeniu wykonania wszystkich funkcji w gnieździe. Zmienna @BylBlad ustawiana jest na wartość "1", a komunikat błędu zapisany w zmiennej @TekstBledu. Jeśli jednak następna w kolejności funkcja do wykonania użyje jako parametrów jednej z ww. zmiennych (np. w funkcji IF @BylBlad>0 THEN ELSE lub komunikat wyświetlający @TekstBledu), wówczas program przyjmuje, że obsługę błędu przejmuje programista gniazda i wykonanie dalszego kodu gniazda nie jest przerywane, a także nie jest wyświetlany standardowy komunikat błędu (patrz Przykład 2). Możemy więc całkowicie przechwytywać błędy generowane przez funkcje umieszczone w gniazdach i np. rejestrować je w tabeli dodatkowej zamiast wyświetlać. Można również oprogramować różne działania w zależności od poprawnego lub niepoprawnego zakończenia funkcji.
Należy pamiętać, że wartości wszystkich zmiennych dostępne są jedynie w obrębie gniazda. W innym gnieździe, nawet jeśli występują te same zmienne, ich wartości albo wynikają z formularzy (w przypadku zmiennych kontekstowych), albo z ustawień aplikacji (w przypadku zmiennych systemowych). Zmienne przewidziane dla programistów (np. @Wynik1) oraz zmienne obsługi błędów i statusów funkcji (@Status, @OdpNaPytanie, @BylBlad) są zainicjowane wartościami domyślnymi ("0" w przypadku wartości numerycznych i pusty ciąg znaków w przypadku wartości tekstowych). Nie można więc ustawić wartości zmiennej w jednym gnieździe i odebrać tą wartość w innym gnieździe. Jeśli chcemy przekazać pewne parametry między funkcjami uruchamianymi w różnych gniazdach, najlepiej zapisać wartości tych parametrów w bazie danych np. w tabeli dodatkowej.
Na uwagę zasługują zmienne kontekstowe $CzyDodano, $CzyPoprawiono, $CzyUsunieto, które występują w gniazdach typu Po na listach dokumentów, artykułów czy kontrahentów. Pokazują one status wykonania operacji, która miała miejsce po wykonaniu określonego działania na liście.
Przykładowo w gnieździe o adresie Dokumenty handlowe | Lista dokumentów handlowych | Zdarzenia związane z pojedynczym dokumentem | Poprawianie dokumentu | Po zmienna $CzyPoprawiono ustawiona na "1" oznacza, że dokument, którego identyfikator znajduje się w zmiennej @IdObiektu, został poprawiony. Wartość "0" będzie oznaczała, że zmiany zostały wycofane i dokument nie był zmodyfikowany. Analogicznie w przypadku dodawania dokumentów zmienna $CzyDodano = "1", będzie oznaczała, że dokument został dodany, a jego identyfikator będzie zawarty w zmiennej @IdObiektu. Z kolei jeśli dokument nie został dodany ($CzyDodano = "0"), zmienna @IdObiektu nie ulegnie zmianie tzn. będzie zawierała identyfikator dokumentu podświetlonego na liście dokumentów.
Gniazda rozszerzeń dokonują automatycznie konwersji typów zmiennych. Nie ma więc potrzeby stosować konwersji typów, aby wyświetlać wartości numeryczne w funkcjach typu komunikat czy pytanie. Należy jednak pamiętać, że takich konwersji trzeba dokonywać korzystając ze zmiennych @Wynik1, @Wynik2, @Wynik3, które są typu tekstowego, w przypadku gdy podstawiamy wartości numeryczne do tych zmiennych w procedurach SQL. Ma to szczególnie znaczenie, gdy projektowane rozwiązania mają być uniwersalne i stosowane na różnych wersjach MS SQL Server.
Podczas pracy z czystą bazą danych lub z programem po aktualizacji, zanim rozpoczniemy pracę z gniazdami i zaczniemy je wypełniać, zalecane jest wykonanie dowolnych działań w oknach, z którymi zamierzamy pracować. Następnie należy wylogować się z programu i ponownie zalogować.
Wynika to z zastosowanego mechanizmu przypisywania zmiennych do gniazd. Informacje te nie są tworzone i zapisywane podczas procesu instalacji (aktualizacji) bazy programu. Dane te zapisywane są sukcesywnie dopiero podczas pracy programem, ponieważ przy liczbie około 700 gniazd rozszerzeń liczba wierszy w tabeli przechowującej przypisania zmiennych do gniazd sięga kilkunastu tysięcy.
Zapisywanie tych informacji w trakcie instalacji (aktualizacji) znacznie wydłużyłoby jej czas. Wobec tego dopiero otwieranie kolejnych okien powoduje sprawdzenie, czy zmienne są już zarejestrowane w gniazdach dostępnych na tych oknach. Jeśli zmienna nie figuruje na liście zmiennych zarejestrowanych dla gniazda, to jest dodawana do bazy danych i do listy rejestrowej zmiennych w programie. Lista ta (ograniczona kontekstem gniazda) prezentowana jest pod klawiszem Wybierz zmienne.