Jakie zmienne gniazd rozszerzeń są dostępne w programie?
Podczas konfigurowania parametrów przekazywanych do funkcji można wykorzystać dwa rodzaje zmiennych:
- zmienne systemowe – których nazwa zaczyna się od znaku @,
- zmienne kontekstowe – których nazwa zaczyna się od znaku $.
Sposób wykorzystania zmiennych w funkcjach jest identyczny i nie zależy od rodzaju zmiennych. To co odróżnia wymienione 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ć 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 będzie jej natomiast w gniazdach związanych z kartoteką artykułów.
Lista dostępnych w danym gnieździe zmiennych wyświetli się po kliknięciu przycisku Wybierz zmienne aplikacji (klawisz F4) na formularzu definicji funkcji. Okno Wybór parametrów zawiera listę Dostępne parametry, 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 definiowana jest funkcja.
Zmienne umożliwiają tylko odczyt wartości. W przypadku funkcji typu Procedura SQL możliwa jest jednak zmiana wartości niektórych z nich. O tym, czy można zmienić wartość zmiennej w procedurze SQL decyduje kolumna SQL Output na liście Dostępnych zmiennych. Zapis Tak w kolumnie oznacza, że zmienna będzie przekazywana do procedury składowanej ze słowem OUTPUT, co w języku SQL oznacza, że zmiana jej wartości wewnątrz procedury spowoduje przekazanie tej zmiany do gniazda. Zmienne kontekstowe powiązane są z danymi w formularzach, toteż zmiana ich wartości skutkuje zmianą danych w programie, np. zmiana wartości zmiennej $CenaNettoPLN w funkcji podpiętej w gnieździe o adresie Dokumenty handlowe | Okno danych pozycji dokumentu handlowego | Dodawanie pozycji | Otwarcie okna danych pozycji | Przed spowoduje, że cena netto pokazana w formularzu po otwarciu okna danych pozycji dokumentu, będzie taka jak wartość zmiennej $CenaNettoPLN, a nie domyślna dla artykułu, jakby wynikało ze standardowego zachowania programu.
Z kolei wpisanie w formularzu nowej wartości ceny netto spowoduje przepisanie tej ceny do zmiennej $CenaNettoPLN, więc odczyt jej wartości w gnieździe Dokumenty handlowe | Okno danych pozycji dokumentu handlowego | Dodawanie pozycji | Zatwierdzenie danych pozycji | Przed pokaże cenę taką jak na formularzu.
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 programie (wykonującego funkcję w gnieździe) |
| @ZakresDatyOd | int | data początku ustawionego zakresu dat w programie w formacie Wapro Mag |
| @ZakresDatyDo | int | data końca ustawionego zakresu dat w programie w formacie Wapro Mag |
| @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ł anulowany |
Zmienne systemowe można podzielić na dwie podgrupy:
- Zmienne przechowujące aktualne ustawienia środowiska Wapro Mag (@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. Można 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 trzeba 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 będzie równa 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 równe 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 po kliknięciu przycisku Wybierz zmienne.