Typy danych w Comarch ERP Enterprise

Wprowadzenie

Artykuł zawiera przegląd typów danych, ich znaczenie i właściwości techniczne.

W kolejnych rozdziałach wyszczególniono istniejące typy danych wraz z ich podstawowymi właściwościami oraz najważniejszymi API dostępnymi w każdym przypadku. Mapowanie i użyteczność typów danych zależy od danego kanału i jest opisane w artykułach:

• o usłudze Business Integration Service (BIS): Zdalne interfejsy BIS

Grupa docelowa

• programiści

Opis

Opis interfejsów API jest podzielony w następujący sposób:

• Typ pierwotny – typ danych zdefiniowany w aplikacji Obiekty deweloperskie.
• Logiczny typ danych – logiczny typ danych, który może służyć jako podstawa dla własnych typów danych. W przypadku niektórych typów (np. Bool, Property) użycie logicznego typu danych lub odpowiedniego wyprowadzenia jest niezbędne dla funkcjonalności.
• Zapytanie o typ danych – logiczny typ danych, który lub jego pochodne są używane w zapytaniach. W przypadku większości typów danych inny logiczny typ danych nie jest konieczny w przypadku zapytań.
• Pole GUI – jest to klasa Java, której można użyć do wprowadzenia lub wyprowadzenia wartości tego typu danych w interfejsie graficznym.
• Pole GUI dla zapytań – jest to klasa Java, której można używać do wprowadzania lub wysyłania zapytań dotyczących wartości tego typu danych w interfejsie graficznym. W zależności od typu danych pola te umożliwiają wielokrotne wpisy, zakresy lub użycie symboli zastępczych. Są one szczególnie wykorzystywane w poszukiwaniach i zastosowaniach na listach. W zależności od przypadku pole GUI może być używane w specjalnym trybie zapytań (SelectionMode) lub może istnieć specjalne pole zapytania.
• Walidacje – klasa cisag.pgm.util.RepositoryValidation i niektóre inne klasy umożliwiają sprawdzanie wartości i wysyłanie „ogólnych” komunikatów na podstawie typu danych wraz z ich opisem. Można m.in. sprawdzić, czy określono „ciąg znaków” i czy nie została przekroczona maksymalna dozwolona długość. Korzystanie z tych interfejsów API upraszcza tworzenie kontroli i zmniejsza liczbę identycznych wiadomości.
• Wartości null – usługa trwałości obsługuje wartości null podczas ustawiania obiektów biznesowych i odczytywania z bazy danych. Jeśli metody zestawu Business Objects dopuszczają wartość null, opisuje to, w jaki sposób usługa trwałości obsługuje tę wartość podczas zapisu do bazy danych. Opisuje także, w jaki sposób wartość null w bazie danych (np. spowodowana użyciem outer join) jest przetwarzana przez usługę trwałości.
• Klasy pomocy – do tworzenia wartości i elementarnych operacji na wartościach typu danych. Operacje te obejmują m.in. tworzenie wartości, sprawdzanie, czy wartość została określona i konwertowanie wartości na niestandardową reprezentację do użycia w wiadomościach. Metody tych klas zazwyczaj zwracają tylko wartości i same nie generują żadnych komunikatów.

Typy danych: Boolean

Typy danych Boolean może przyjmować jedynie wartości true lub false. Jeśli ten typ danych jest również używany do wpisywania parametru polecenia Toolshell, można określić wartości true lub false dla tego parametru lub można go pominąć.

Wartość logiczna

Bool

Typ danych Bool jest taki sam jak typ danych Boolean. Jedyna różnica polega na tym, że typ danych Bool jest używany w poleceniach Toolshell do wpisywania parametrów, których wynik odpowiada wartości true, a których brak odpowiada wartości false, a jawne podanie wartości jest nie wymagane.

Użycie logicznego typu danych lub odpowiedniego wyprowadzenia jest istotne dla funkcjonalności.

Liczby

Byte

Short

Integer

Long

Liczby dziesiętne

Float

Typ danych Float nie jest zwykle używany w systemie, ponieważ reprezentuje wartości zmiennoprzecinkowe, a zatem potencjalnie wartości zaokrąglone. W systemie używane są liczby dziesiętne. Tylko niektóre klasy GUI używają tego typu danych jako części definicji układu.

Double

Typ danych Double nie jest zwykle używany w systemie, ponieważ reprezentuje wartości zmiennoprzecinkowe, a zatem potencjalnie wartości zaokrąglone. W systemie używane są liczby dziesiętne. Tylko niektóre klasy GUI używają tego typu danych jako części definicji układu.

Znaki

Character

String

Text

Teksty to Strings o nieokreślonej długości.

URI-String

Property

Property to ustawienia w plikach właściwości. Ten typ danych służy do identyfikacji możliwych ustawień i przypisania do nich bezpośredniej pomocy.

Binary

Binary

GUID

GUID to techniczna identyfikacja obiektów. Identyfikator GUID jest tablicą bajtów o długości 16 bajtów. Większość obiektów biznesowych w systemie używa pojedynczego identyfikatora GUID jako klucza podstawowego. Umożliwia to łatwe i jednolite mapowanie użycia tego klucza podstawowego jako klucza obcego w innych obiektach biznesowych.

BLOB

ValueSet

ValueSet

Zestaw wartości (ValueSet) to wyliczenie wartości. Powiązane elementy zestawu wartości zawierają specyficzne cechy listy. Element składa się z dodatniej krótkiej wartości, stałej nazwy i tłumaczonej etykiety. Z reguły dla każdego zestawu wartości, w którym zdefiniowano stałe, generowana jest klasa Java. Nazwa elementu jest używana jako nazwa stała, a krótka wartość jako wartość stała.

Czas i data

Istnieje wiele specjalnych typów danych, które służą do przetwarzania informacji o godzinie i dacie. Podstawą wymienionych rozróżnień jest logiczny typ danych wartości.

Strefa czasowa stanowi podstawę mapowania i przetwarzania informacji o czasie i dacie. Wraz z innymi informacjami definiuje kalendarz. Jest to podstawa operacji operujących na tygodniach kalendarzowych.

Dodatkowo na wybór typu danych wpływają następujące pytania:

• Czy jest to bezwzględna specyfikacja czasu (data, data i godzina), względna specyfikacja czasu (czas trwania, pora dnia), czy też symboliczna specyfikacja czasu (co tydzień)?
• Czy wartość dotyczy strefy czasowej?
• Czy wartość ma precyzję daty lub precyzję znacznika czasu?

W przypadkach, w których używane są atrybuty validFrom i validUntil wygenerowane przez usługę trwałości, istnieją dalsze możliwości ustawienia zależności czasowej w obiekcie deweloperskim Business Object.

Dostępne są opcje:

• Brak
• Zawsze wstawiaj nowy rekordy
• Zawsze zapisuj bieżący rekord
• Kontrolowane przez aplikację
• Kontrolowane przez aplikację, data ze strefą czasową
• Kontrolowane przez aplikację, znacznik czasu ze strefą czasową

W takich przypadkach:

• dodatkowo generowany jest atrybut _timeZoneGuid
• atrybut validFrom i atrybut validUntil są generowane jako znacznik czasu
• atrybut validFrom jest interpretowany jako lokalna data ważności od lub lokalny znacznik czasu ważności od
• atrybut validUntil jest interpretowany jako lokalna data ważności do lub lokalny znacznik czasu ważności do

Elementy obowiązywania od-do wizualizowane są za pomocą standardowych pól. Klasa pomocy com.cisag.pgm.gui.ValidFromUntilSupport umożliwia połączenie dwóch pól w pole Od-Do.

Strefa czasowa

Strefa czasowa (technicznie TimeZone) określa różnicę czasu w odniesieniu do średniego czasu Greenwich. Efektywne przesunięcie zasadniczo zależy od przepisów dotyczących czasu letniego danej strefy czasowej, a zatem od dnia w roku. W systemie dostępne strefy czasowe są stałe. Odniesienia do stref czasowych są przechowywane w postaci identyfikatora GUID powiązanego obiektu biznesowego TimeZone. Obiekt biznesowy TimeZone znajduje się w bazie repozytorium. Źródłem strefy czasowej jest prawie zawsze kalendarz. Dlatego nie ma specjalnego pola GUI ani specjalnych interfejsów API do obsługi strefy czasowej poza kalendarzem.

Kalendarz

Określenie strefy czasowej wystarczy, aby przekonwertować godzinę na datę i godzinę. Do obliczenia tygodnia kalendarzowego (KW) potrzebne są dwie dodatkowe informacje. Oto definicje tego, który dzień tygodnia jest uważany za pierwszy dzień tygodnia (atrybut firstDayOfWeek) i od ilu dni tydzień 1 jest interpretowany jako tydzień 1 i już nie jako tydzień 53 (MinimDaysInFirstWeek). Strefa czasowa plus te dwie wartości razem tworzą kalendarz w systemie (Kalendarz w Javie interfejs com.cisag.pgm.datatype.CisCalendar). W aplikacji Konfiguracja kalendarz systemowy można zdefiniować na poziomie systemu. Dla każdej organizacji ustalany jest osobny kalendarz. Wybranie organizacji jako kontekstu na standardowym pasku narzędzi może przełączyć bieżący kalendarz sesji. Zmiana w organizacji ma różne skutki w różnych zastosowaniach. Etykieta pola wyboru organizacji zawiera informacje na ten temat. Zmiana organizacji ma wpływ na prezentację informacji czasowych. W przypadku znaczników czasu wyświetlana wartość jest przeliczana; w przypadku czasu lokalnego wyświetlana jest strefa czasowa, jeśli różni się ona od strefy czasowej kontekstu. Jeżeli w sesji nie jest aktywna żadna baza danych OLTP, obowiązuje kalendarz systemowy.

W linii stanu wyświetlany jest aktualnie aktywny kalendarz i jego strefa czasowa. Strefa czasowa i właściwości kalendarza są wyświetlane w podpowiedzi strefy czasowej.

Etykieta ustawień kalendarza w wierszu stanu

Aktualna godzina w pasku statusu przygotowywana jest zawsze na podstawie aktywnego kalendarza. Oprócz bieżącej daty podpowiedź pokazuje porę dnia, czy w strefie czasowej rozróżnia się czas letni i zimowy oraz jaka różnica czasu jest aktualnie aktywna.

Tooltip dla ustawień czasu w pasku stanu

Timestamp

Znacznik czasu (TimeStamp) to wartość określająca punkt na osi czasu UTC. Dokładność znacznika czasu wynosi zawsze milisekundy i jest bezwzględna i niezależna od strefy czasowej i technicznie jest reprezentowana jako długa wartość w instancji klasy Java java.util.Date. Przygotowanie znacznika czasu w postaci tekstu czytelnego dla człowieka zawsze wymaga podania strefy czasowej. Ten sam znacznik czasu ma inną reprezentację tekstową w zależności od strefy czasowej używanej do przetwarzania. Podczas przetwarzania należy wziąć pod uwagę czas letni i zimowy. Oznaczają one między innymi, że nie każda wartość może być reprezentowana lub unikalna w każdej strefie czasowej.

Wszystkie znaczniki czasu w interfejsie (np. czas na pasku stanu) są przetwarzane zgodnie ze strefą czasową aktywnego kontekstu. Strefa czasowa znaczników czasu jest wyświetlana tylko raz w pasku stanu. Jeśli strefa czasowa ulegnie zmianie ze względu na zmianę organizacji, reprezentacje wszystkich znaczników czasu zostaną zaktualizowane. W przypadku aplikacji odbywa się to domyślnie, gdy system wywołuje metodę taskSwitch() i wiąże się to z resetowaniem wartości w polach. Jeśli aplikacja automatycznie zareaguje na zmianę organizacji, na przykład w celu wyświetlenia monitu bezpieczeństwa, można ustawić własną akcję dla tego zdarzenia. W tym przypadku funkcja taskSwitch() nie jest wywoływana automatycznie i aplikacja musi sama zaktualizować zawartość pola przed i po wyświetleniu okna dialogowego.

W zakresie wartości znacznika czasu w systemie istnieją następujące symboliczne wartości i przedziały:

• • UNDEFINED_TIME_STAMP – nieokreślony znacznik czasu.

• MIN_TIME_STAMP – minus nieskończoność, tj. H. znacznik czasu mniejszy niż wszystkie inne określone znaczniki czasu. Jest on przechowywany w bazie danych jako 31.12.0001 23:02:00.000 GMT.

• MAX_TIME_STAMP – plus nieskończoność, tj. H. znacznik czasu większy niż wszystkie inne określone znaczniki czasu. Jest przechowywany w bazie danych jako 31.12.4712 00:00:00.000 GMT.

Istnieją również następujące wartości, które nie są bezpośrednio generowane ani nie są dostępne dla systemu. Wykorzystuje się je podczas konwersji danych wejściowych lub wyprowadzania wyżej wymienionych wartości symbolicznych.

Wartości wymienione poniżej nie mogą być trwałe. Powiązane klasy walidacyjne muszą uniemożliwiać zapisanie tych wartości w ramach transakcji.

• MIN_TIME_STAMP_LIMIT – wszystkie wartości mniejsze od tej wartości są interpretowane jako MIN_TIME_STAMP. Obecnie 01.01.1800 00:00:00.000 GMT.

• MAX_TIME_STAMP_LIMIT – wszystkie wartości większe lub równe tej wartości są interpretowane jako MAX_TIME_STAMP. Obecnie 01/01/4000 00:00:00.000 GMT.

• MIN_TIME_STAMP_EXTERNAL – czytelna wartość reprezentacji MIN_TIME_STAMP. Obecnie 01.01.1000 00:00:00.000 GMT.

• MAX_TIME_STAMP_EXTERNAL – czytelna reprezentacji MAX_TIME_STAMP. Obecnie 31/12/9999 00:00:00.000 GMT.

• Nieprawidłowe znaczniki czasu -wprowadzone przez użytkownika skutkują nieprawidłowymi identyfikatorami GUID, podobnie jak w przypadku EntityFields. Służą one do tymczasowego przechowywania wartości w odpowiednio wpisanych zmiennych do czasu ich sprawdzenia.

Prawidłowe wartości znaczników czasu w systemie.

Operacje arytmetyczne na znacznikach czasu muszą uwzględniać wartości symboliczne. Na przykład MIN_TIME_STAMP + 1 s = MIN_TIME_STAMP.

Wszystkie informacje dotyczące ważności, np. zależności czasowej obiektów biznesowych w usłudze trwałości, są zazwyczaj znacznikami czasu.

Lokalny znacznik czasu

We wszystkich miejscach, gdzie specyfikację czasu należy przygotować w ten sam sposób, bez względu na kontekst (lokalna specyfikacja czasu), oprócz faktycznego znacznika czasu należy zapisać także strefę czasową. Jest to strefa czasowa, dla której przygotowywana jest wartość. Podczas wprowadzania ta strefa czasowa jest zawsze używana do „analizowania” danych wejściowych. W przeciwieństwie do znaczników czasu, strefa czasowa aktualnie aktywnego kalendarza nie ma wpływu na wartość czasu lokalnego. Jedynie strefa czasowa nie jest wyświetlana, jeśli przy wyprowadzaniu czasu lokalnego jego strefa czasowa odpowiada strefie czasowej aktualnie aktywnego kalendarza.

W czasie wykonywania czasy lokalne są reprezentowane jako obiekty typu złożonego CisDate. CisDate składa się ze znacznika czasu i odniesienia do strefy czasowej. Istnieją dwie możliwości przechowywania strefy czasowej czasu lokalnego:

• atrybut typu CisDate ma własną kolumnę do przechowywania strefy czasowej
• obiekt biznesowy udostępnia wspólną strefę czasową dla swoich atrybutów. Obiekt biznesowy może także zawierać jednocześnie oba typy czasu lokalnego. Użycie wspólnej strefy czasowej dla podzbioru atrybutów zmniejsza liczbę kolumn potrzebnych w bazie danych.

Obsługa dat lokalnych technicznie nie różni się od obsługi lokalnych znaczników czasu. Jednak daty są traktowane specjalnie podczas wprowadzania i wyprowadzania.

• Pora dnia nie jest wizualizowana na wyjściu
• Przy wprowadzaniu godziny przyjmuje się, że część dnia to „00:00”.

W przypadku dat oznaczających „do chwili obecnej” dane wejściowe i wyjściowe są również przesuwane o jeden dzień kalendarzowy. Wpis 31.12.2023 dla Do daty jest zapisywany jako 01.01.2024 00:00:00.000. Dzięki temu informacja 01.01…-31.12… uwzględnia cały rok.

Data lokalna

Obsługa dat lokalnych technicznie nie różni się od obsługi lokalnych znaczników czasu. Jednak daty są traktowane specjalnie podczas wprowadzania i wyprowadzania.

• Pora dnia nie jest wizualizowana na wyjściu
• Przy wprowadzaniu godziny przyjmuje się, że część dnia to „00:00”.

Bieżące dane lokalne

W przypadku dat oznaczających „do chwili obecnej” dane wejściowe i wyjściowe są również przesuwane o jeden dzień kalendarzowy. Wpis 31.12.2023 dla Do daty jest zapisywany jako 01.01.2024 00:00:00.000. Dzięki temu informacja 01.01…-31.12… uwzględnia cały rok.

Lokalna data obowiązywania Od

Lokalny znacznik czasu Od

Lokalna data obowiązywania Do

Lokalny znacznik czasu Do

Pora dnia

Pora dnia (technicznie TimeOfDay) to szczególny przypadek lokalnego znacznika czasu. Strefa czasowa jest ustawiona na GMT i uwzględniana jest tylko część czasowa znacznika czasu z dnia 1 stycznia 2024r. Ponieważ strefa czasowa jest stała, nie ma potrzeby jej zapisywania. Informacje 00:00 są zapisywane jako 01.01.2024 00:00 GMT. W Javie 00:00 odpowiada wartości nowa data (0), a 23:59.59.999 odpowiada wartości nowa data (86399999).

Okres techniczny

Okres techniczny to liczba milisekund lub nanosekund. Przykładami może być czas wykonania serwera aplikacji, zadanie przetwarzania lub specyfikacja limitu czasu. Reprezentacja technicznego czasu trwania jest niezależna od kalendarza jako „T – tygodnie, D – dni, H – godziny, M- minuty, S –  sekundy MM – milisekundy”. Do tego dochodzi krótka prezentacja i pominięcie ­na końcu 0.

Okres specjalistyczny

W przeciwieństwie do czasu technicznego, czas specjalistyczny przechowuje wartość symboliczną, np. 1 kwartał.

Interwał czasowy (dwa znaczniki czasu)

Przedział czasu (technicznie TimeInterval) to nieograniczony przedział znaczników czasu Od, Do. W zależności od konkretnego wymagania zapisywane są oba limity lub tylko jeden z dwóch limitów. W modelu danych zostaną wykorzystane odpowiadające im poszczególne pola typu timestamp, na których można definiować indeksy.

Cykliczny interwał

Cykliczny interwał (technicznie SymbolicInterval) opisuje regułę dla zestawu powtarzających się punktów w czasie, np. „Każdego pierwszego dnia miesiąca o godzinie 1:00”. Wraz z kalendarzem, godziną rozpoczęcia i liczbą można obliczyć kolejność kolejnych znaczników czasu spełniających regułę.

Termin

Termin (PointInTime) to okres czasu, którego początek jest ustalony z określoną precyzją (rok, kwartał, miesiąc, tydzień kalendarzowy, dzień) z góry zdefiniowanym kalendarzem.

Księgowość

W obiektach biznesowych serwera księgowego nie są używane żadne specjalne typy danych. Usługa trwałości, wyszukiwania OQL i sterownik ODBC zapewniają dostęp do odczytu powiązanych obiektów biznesowych w przestrzeni nazw com.varag.app.database.obj. Ponieważ dostęp do zapisu nie jest dozwolony, nie ma klas testowych ani pomocniczych.

Księgowość-Boolean

Zestaw wartości księgowych

Identyfikacja obiektu księgowego

Data księgowania

Znacznik czasu księgowania