Bloczki wyjściowe

---

Konfiguracja bloczków wyjściowych dotyczy wyłącznie zapisu do bazy danych oraz zapisu do typowanego pliku XML.

Reszta bloczków nie wymaga konfiguracji w zakładce Szczegóły. Jedyna parametryzacja odbywa się po uruchomieniu pakietu w oknie Wartości parametrów uruchamiania bloczków i sprowadza się do określenia lokalizacji zapisu plików wyjściowych.

Bloczki zostały umieszczone po lewej stronie okna w menu Przybornik.

Zalicza się do nich następujące typy bloczków:

1. Typowane wyjście XML
2. Plik stałopozycyjny
3. Plik KVF
4. Zapis do pliku CSV
5. Prosty plik XML
6. Plik określony szablonem
7. Plik rekordów zapisanych binarnie
8. Prosty plik Excel
9. Zapis do bazy danych
10. Wyślij e-mail

Obsługa pustych plików

Konfiguracja pustych plików umożliwia zdefiniowanie dowolnej ilości pustych plików opartych o wzorzec nazwy (parametr na bloczku: Wzorzec ścieżki dostępu plików), które mają zostać stworzone podczas przetwarzania danego bloczka.

1. Jeśli wzorzec nazwy pliku nie został podany, a opcja tworzenia pustych plików została zaznaczona, nastąpi stworzenie jednego pustego pliku o nazwie odpowiadającej plikowi wynikowemu.
2. Dodatkowo, istnieje możliwość samodzielnego (poprzez zewnętrzną bibliotekę) wypełnienia pól wzorca nazwy pliku, poprzez wywołanie zewnętrznej metody z odpowiednimi parametrami.
3. Dostępna jest także możliwość łączenia sposobów generowania pustych plików np. poprzez wypełnienie w kodzie, jak i definicję ustaloną w aplikacji.
4. Konfiguracja plików wynikowych odnosi się również do konfiguracji pustych plików, tzn. można ustawić nagłówki, separatory nagłówków, kodowanie itp.

Sposoby tworzenia plików

Istnieje możliwość zdefiniowania operacji wykonywanej przy tworzeniu pliku, jeśli zdefiniowana ścieżka posiada już plik w danej lokalizacji.

Dostępnych jest 5 operacji:

1. Nadpisz ( domyślna ) – nadpisuje istniejący plik,
2. Przerwij działanie pakietu – przerywa wykonywanie przetwarzania. Sprawdzane jest w momencie zapisu do pliku,
3. Dopisz dane - dopisuje dane do istniejącego pliku oddzielając je separatorem zdefiniowanym w Separator dopisywanych danych,
4. Utwórz nowy plik z sufiksem liczbowym,
5. Dodaj do starego pliku sufiks liczbowy.

Koniec pliku

Istnieje możliwość zdefiniowania tekstu (oraz znaków specjalnych np. \n ) dodawanego na końcu każdego pliku. W przypadku plików całkowicie pustych (bez danych, nagłówków, stopek itp. ) mechanizm dodawania do końca pliku jest pomijany.

Typowany plik wyjściowy XML

Bloczek Typowane wyjście XML umożliwia zapisanie przetworzonych danych do pliku o formacie XML.

1. Zapisywany plik jest dzielony na część główną i listy danych reprezentowane przez bloczki list.
2. Szczegóły podzielone zostały między dwie zakładki:

Schemat XML

1. Zakładka Schemat XML pozwala na automatyczne utworzenie na podstawie przykładowego pliku lub schemy XSD, schematu wynikowego.

2. Przykładowy plik zostaje zaczytany do Systemu za pomocą przycisku Dodaj przykładowy xml i przez wpisanie dokładnej ścieżki do pliku, a następnie wybranie przycisku Otwórz.
3. Na podstawie przykładowego pliku wyświetlony zostanie schemat drzewa XML.
4. Wynikowy schemat przetwarzania przedstawiony zostanie po zaznaczeniu elementu z drzewa XML oraz wybraniu opcji Wybierz korzeń.

Lista danych

1. Każda ścieżka przetwarzania jest zapisywana do pojedynczej listy rekordów. Lista taka jest zapisywana do pliku XML do wybranego przez Użytkownika elementu wielokrotnego.
2. Operacja odbywa się z poziomu zakładki Lista danych.

3. Po dodaniu nowej listy za pomocą opcji dostępnej w pasku zadań zakładki i zaznaczeniu elementu mocowania w wynikowym schemacie przetwarzania, wybierz przycisk Wybierz punkt mocowania listy.
4. Utworzone listy danych reprezentowane są na schemacie pakietu przetwarzania przez bloczki list.

Plik stałopozycyjny

Plik stałopozycyjny - jest to opcja pozwalająca na zapisanie wcześniej przetworzonych danych do pliku stałopozycyjnego.

1. Format pliku charakteryzuje dane, które zawsze mają to samo określone miejsce w strukturze i parametry (ilość znaków).
2. Najważniejszą opcją, którą należy edytować w przypadku tego bloczka jest atrybut Kolumny, dostępny po wybraniu panelu Właściwości. Po wyborze przycisku edycji, zostanie wyświetlone okno, w którym można edytować długość i przesunięcie określonych pól, które mają się znaleźć w pliku.

W poniższym przypadku dane pobrane z bazy danych (bloczek Odczyt z bazy) zostają zapisane do pliku stałopozycyjnego.

Przy tak zdefiniowanych przesunięciach i długości dla poszczególnych pól dane mogą zostać zapisane do wynikowego pliku.

Plik KVF

Bloczek Plik KVF pozwala na zapisanie płaskich rekordów do pliku o liniach postaci „klucz = wartość” z dodatkowym separatorem rekordów.

Bloczek nie posiada własnego edytora, jedyne opcje można ustawiać poprzez panel Właściwości.

Opcje te to:

1. separator rekordów – łańcuch znaków, który będzie wstawiany między poszczególne rekordy,
2. usuwaj „białe znaki” z wartości – ustawienie wartości spowoduje usunięcie „białych znaków” z początku i końca każdej zapisywanej wartości.

Poniżej przykład pobrania danych z bazy, a następnie zapis do pliku KVF:

Ważnym elementem jest wybrana opcja w polu Separator rekordów. Domyślnie separatorem jest nowa linia czyli \r\n. Przy próbie wczytania pliku KVF poprzez bloczek wejściowy musimy wiedzieć jaki jest separator rekordów w pliku i także go wskazać patrz: Bloczki wejściowe>Plik KVF.

Plik CSV

Bloczek Zapis do pliku CSV umożliwia zapis przetworzonych danych do pliku o formacie CSV obsługiwanym przez większość arkuszy kalkulacyjnych i programów bazodanowych.

Bloczek, podobnie jak inne bloczki zapisujące dane do pliku, nie posiada własnego edytora. Znaczące opcje można ustawiać korzystając z panelu Właściwości:

1. separator kolumn – napis, który będzie zapisywany między poszczególnymi wartościami w pojedynczym wierszu,
2. wypisuj nagłówek – opcja umożliwiająca ukazanie nagłówka w pierwszym wiersz w pliku.

Należy pamiętać aby przy wczytywaniu pliku CSV podać odpowiedni separator rekordów. Jeżeli w pliku wyjściowym wskazany został separator rekordów jako ; wówczas w bloczku wejściowym przy wczytywaniu pliku należy określić taki sam separator danych.

Prosty plik XML

Bloczek Prosty plik XML pozwala na zapisanie rekordów do pliku o formacie XML jako wielokrotne elementy bezpośrednio pod korzeniem. Wartości pól danych mogą być atrybutami lub elementami.

Znaczące opcje, które można ustawiać, korzystając z panelu Właściwości:

1. pola jako elementy – atrybut pozwala zdefiniować, czy pola w rekordach danych będą zapisywane do pliku XML jako atrybuty czy jako elementy,
2. znaki wcięcia – znaki używane do formatowania pliku XML - do tworzenia wcięć podczas zapisu do pliku.

Najprostszy przykład wykorzystania bloczka to stworzenie pakietu, w którym pobierane są dany z tabel w bazie danych, a następnie zapisywane do pliku XML. Więcej patrz: Odczyt z bazy i zapis danych do pliku.

Plik określony szablonem

Bloczek Plik określony szablonem pozwala na zapis danych do pliku o dowolnym formacie tekstowym, zdefiniowanym za pomocą:

• szablonu całego pliku, odwołującego się do szablonów przypisanych do rekordów, oraz
• poszczególnych pól danych (z opcjonalnymi parserami dostosowującymi postać wartości).

1. W efekcie za pomocą tego bloczka można uzyskać inne formaty zapisu, dla których nie istnieją dedykowane (szybsze, wygodniejsze) bloczki zapisu (np. CSV, POS, XML).
2. Bloczek może być traktowany jako „odwrotność” bloczka wczytywania danych za pomocą drzew wyrażeń regularnych.

Przykład widoku edytora bloczka:

3. Do rekordu może być dołączonych więcej niż jeden szablon (można nadawać im różne nazwy, w celu późniejszego odwołania się), rekordy wielokrotne mogą być rozdzielane wybranym ciągiem znaków – separatorem.
4. Edytor szablonów posiada kilka funkcji ułatwiających pracę, np. przerobienie przykładowych danych na szablon.

Edytor

Edytor podzielony jest na dwie części.

1. Lewa, będąca drzewem struktury danych, umożliwia dodawanie adnotacji Szablon rekordu i Parser.
2. Prawa część pozwala na bezpośrednią edycję szablonów. Szablon może być przypisany do pliku lub rekordu, który może mieć przypisany więcej niż jeden szablon.

Szablony są pisane prostym językiem, zawierającym możliwość odwołania się do dowolnego rekordu lub pola w strukturze danych. Opcja Zmieniaj zakładki w zależności od wyboru włącza lub wyłącza automatyczne przełączanie zakładek w prawej części okna na odpowiadającą wybranemu rekordowi w części lewej.

Definiowanie szablonu pliku

1. Szablon dla pliku definiowany jest w zakładce Szablon pliku w prawej części edytora.
2. Treść każdego pliku zapisanego przez bloczek zostanie utworzona na podstawie tego szablonu.
3. W przeciwieństwie do innych szablonów, odwołania do pól nie zostaną zastąpione przez całą ich serię, lecz przez wartość znajdującą się w pierwszym rekordzie, jaki zostanie przetworzony przez bloczek.
4. Przy tak zdefiniowanym szablonie pliku jak poniżej otrzymamy plik, który będzie prezentować w treści Imię i Nazwisko klienta.

Definiowanie szablonów rekordu

1. Szablon dla rekordu definiowany jest za pomocą adnotacji Szablon rekordu.
2. Po dodaniu takiej adnotacji, w prawej części edytora pojawi się nowa zakładka, odpowiadająca wybranemu rekordowi.
3. Rekord może mieć kilka szablonów, każdy o innej nazwie, a jeden z nich może zostać szablonem domyślnym.

4. Aby przypisać szablon do rekordu, najpierw należy dodać do niego adnotację Szablon rekordu.

5. W prawej części okna pojawi się wtedy zakładka ze ścieżką do wybranego rekordu. Można teraz definiować szablony. W tym celu należy wybrać odpowiednią zakładkę, a następnie wcisnąć przycisk Dodaj szablon.

6. Zostanie wyświetlone okno z prośbą o podanie nazwy nowego szablonu. Gdy będzie ona unikalna, zostanie on utworzony, a w edytorze zostanie wyświetlona kolejna zakładka z nazwą nowo utworzonego szablonu.

7. Jeden z szablonów może być szablonem domyślnym, który będzie wybierany w przypadku, gdy użytkownik nie wyspecyfikuje nazwy szablonu w odwołaniu do rekordu (patrz: Język definicji szablonu).
8. Aby ustawić szablon jako domyślny, należy zaznaczyć jego zakładkę a następnie wcisnąć przycisk Ustaw jako domyślny. Dla rekordu zawsze musi być ustawiony szablon domyślny.
9. Zmianę nazwy szablonu należy wykonać przez dwukrotne kliknięcie na tytuł zakładki danego szablonu. Zostanie wyświetlone nowe okno, w którym należy wpisać nową nazwę.
10. Aby usunąć szablon, należy zaznaczyć jego zakładkę, a następnie wcisnąć przycisk Usuń szablon.
11. Teraz możesz zdefiniować szablon dla danych pobieranych z rekordu Faktury.

12. Aby dane z rekordu faktury zostały także wygenerowane w pliku należy jeszcze w szablonie pliku dodać odwołanie do utworzonego szablonu rekordu lub do samego rekordu danych. W poniższym przypadku w szablonie pliku jest odwołanie do rekordu danych Faktury.

13. Jeżeli w szablonie pliku nie wskażemy innego szablonu rekordu to zawsze będzie brany do wygenerowania pliku szablon rekordu, który jest ustawiony jako domyślny.

14. Jeżeli dodamy inne szablony do tego samego rekordu, wówczas w szablonie pliku należy wskazać według jakiego szablonu rekordu mają zostać wygenerowane dane, jeżeli nie jet to szablon domyślny dla rekordu. Poniżej zdefiniowano drugi szablon dla rekordu Faktury.

15. W szablonie pliku należy wskazać nazwę szablonu rekordu - w przeciwnym razie dane zostaną wygenerowane według szablonu domyślnego. Odwołanie do szablonu odbywa się poprzez wykorzystanie #s(nazwa szablonu rekordu)#

Definiowanie parsera dla pola

1. Każde pole w rekordzie może mieć przypisany parser za pomocą adnotacji Parser.
2. Umożliwia to konwersję danych do dowolnego innego typu lub wypisanie do pliku w niestandardowych formatach.
3. Parsery mogą być zdefiniowane tylko dla pól i pozwalają na zmianę typu pola.
4. W tym celu należy do pola dodać adnotację Parser, a następnie wybrać i skonfigurować odpowiedni parser wartości.
5. Gdy typ wynikowy nie będzie łańcuchem znaków, wartość pola zostanie na niego przekonwertowana za pomocą wybranej polityki konwersji typów.

Odwołania do pól i rekordów

1. Do każdego szablonu można wstawić odwołanie do innego rekordu lub pola. W przypadku, gdy cel odwołania jest polem lub rekordem wielokrotnym, zostanie on wstawiony we wszystkich egzemplarzach występujących w rekordzie, jeden po drugim.
2. Odwołanie pozwala też na wyspecyfikowanie szablonu, który zostanie użyty podczas wstawiania rekordu, a także separatora oddzielającego kolejne rekordy lub pola w pliku wynikowym.

3. Zazwyczaj kolorowanie składni prezentuje, w którym miejscu ma zostać wstawiony szablon rekordu, jak poniżej szablon2. Może zdarzyć się sytuacja, że kolorowanie nie będzie jasno na to wskazywać. Więcej informacji patrz: Język definicji szablonu.

Obsługa multiplików

1. Bloczek pozwala na zapis do multiplików.
2. Szablon nazwy takiego pliku definiowany jest w panelu Właściwości bloczka. Każdy z multiplików zostanie wygenerowany na podstawie szablonu pliku.

Ułatwienia edycji szablonów

Główną częścią prawego okna edytora bloczka jest pole tekstowe służące do bezpośredniej edycji wybranego szablonu. W celu przyspieszenia pisania szablonów, wprowadzono kilka ułatwień.

1. Podstawowym i najlepiej widocznym jest kolorowanie składni: odwołania do pól i rekordów są podkreślane, a poszczególne części mają różne kolory. Również sekwencje ucieczki są oddzielone wizualnie – pogrubione.
2. Edytor ma również zaimplementowaną obsługę drag-and-drop – przeciągnięcie pola lub rekordu na szablon powoduje wstawienie odwołania do niego. Można ten efekt osiągnąć również przez podwójne kliknięcie na rekord lub pole – odwołanie zostanie wtedy wstawione w miejscu kursora.
3. Aby zapobiec automatycznemu przełączaniu się zakładek z szablonami, należy wyłączyć opcję Zmieniaj zakładki w zależności od wyboru.

Język definicji szablonu

Język definicji składa się z trzech podstawowych elementów:

1. Otwarty tekst, który zostanie przepisany do pliku w takiej postaci, w jakiej pojawił się w edytorze.
2. Sekwencje ucieczki, pozwalających na dodanie do pliku znaków, które trudno wprowadzić za pomocą klawiatury, lub słabo widocznych w edytorze. Zostaną one zastąpione przez znaki, które symbolizują. Dostępne sekwencje ucieczki:

• \n – zostanie zastąpiona znakiem nowej linii (LF)
• \r – zostanie zastąpiona znakiem powrotu karetki (CR)
• \t – zostanie zastąpiona znakiem tabulatora
• \\ - zostanie zastąpiona znakiem \
• ##( - zostanie zastąpiona ciągiem #(
• )## - zostanie zastąpiona ciągiem )#

3. Odwołania do rekordów lub pól. Format takiego odwołania jest następujący: #(ścieżka do rekordu/pola)#s(nazwa szablonu)#,(separator)# (kursywą zaznaczono części opcjonalne):

• ścieżka do rekordu/pola – jest to ścieżka w drzewie struktury danych, specyfikująca rekord lub pole, które ma zostać wstawione w miejscu odwołania. Ścieżka ta jest rozwiązywana względem rekordu, w którego szablonie zostało użyte odwołanie.
• nazwa szablonu – używana tylko w przypadku odwołań do rekordu. Jeśli cel odwołania ma więcej niż jeden szablon, tutaj należy podać nazwę konkretnego szablonu, który ma zostać wstawiony w miejscu odwołania. W przypadku, gdy nazwa szablonu zostanie pominięta, zostanie użyty szablon domyślny. Gdy jednak zostanie podana i będzie błędna, zostanie zgłoszony błąd.
• separator – używany zarówno w przypadku odwołań do pól, jak i do rekordów. Definiuje separator szablonów, w przypadku, gdy cel odwołania jest polem lub rekordem wielokrotnym. Każde dwa pola lub rekordy wstawione w miejsce odwołania zostaną oddzielone podanym separatorem.

Proste, przykładowe szablony:

ostrzeżenie

Jeżeli korzystasz z opcji drag&drop do przenoszenia pól ze schematu danych lub dwukliku na dane pole aby wstawić je do szablonu pliku oraz szablonu rekordów, wówczas kolorowanie składni może zachowywać się inaczej lub w ogóle nie być stosowane. Różnica też może być w zapisie ścieżki do rekordów lub pól, jednak mimo to zarówno jeden jak i drugi zapis jest poprawny i pozwoli na poprawne wygenerowanie pliku.

Plik rekordów zapisanych binarnie

Plik rekordów zapisanych binarnie - pozwala zapisać rekordy do pliku w formacie binarnym. Plik zajmuje mało miejsca, zapis działa bardzo szybko. Bloczek przydaje się do tymczasowego zapisu i przechowania danych w najprostszej postaci w celu użycia ich w kolejnych fazach przetwarzania (np. w celu wcześniejszego posortowania danych przed ich dalsza obróbką).

1. Bloczek, podobnie jak inne bloczki zapisujące dane do pliku, nie posiada własnego edytora, nie posiada też żadnych opcji konfiguracyjnych.
2. Bloczek jest najczęściej używany wraz ze swoim odpowiednikiem – bloczkiem wejściowym Plik rekordów zapisanych binarnie.

Poniżej przykład odczytu danych z bazy danych i zapis do pliku wyjściowego.

Prosty plik EXCEL

Prosty plik Excel pozwala na zapis rekordów do pliku Excel. Rekord może posiadać wielopoziomową strukturę.

W poniższym przykładzie w pakiecie przetwarzania zostają pobrane dane ubezpieczeń oraz klientów z 2 różnych tabel w bazie danych, a następnie zapisane do jednego pliku wynikowego EXCEL.

1. Odczytaj dane z tabel i połącz ze sobą poprzez bloczek Loop join.

2. Dodaj bloczek Odwzorowanie w miejscu i zmień rekord Klient na jednokrotny. Schemat wejściowy do wygenerowania pliku nie może zawierać rekordów wielokrotnych.
3. Po wykonaniu akcji rekord pojedynczy zostanie dodany do schematu z dopiskiem Single.

4. Usuń rekord wielokrotny Klient oraz pola, których nie chcesz generować w pliku.

5. Dodaj bloczek Prosty plik Excel i uruchom pakiet.

Wyślij e-mail

Wyślij e-mail pozwala na wysyłanie e-maili. Można wybrać odbiorców, treść wiadomości i załączniki.

1. Wysyłane wiadomości mogą być zarówno zwykłym tekstem, jak również mieć sformatowaną treść (treść maila jako HTML).
2. W przypadku wysyłania maili ze sformatowaną treścią samą treść generujemy używając Generowania dokumentów – powstaje ona jako wypełnienie szablonu dokumentu, który następnie jest konwertowany na format MHTML i wklejany jako treść maila.
3. W bloczku, przy pomocy odwzorowania w miejscu po uprzednim wybraniu punktu montowania „korzenia” wywołania (analogicznie do wywołania algorytmu czy usługi), wypełniamy wymagane pola wywołania takie jak priorytet, temat, zawartość, odbiorców, nadawcę, załączniki itd.

Przy funkcjonalności wysyłki email niezbędna jest także konfiguracja serwera smtp patrz: Konfiguracja SMTP - common.param.smtp_(..).

Zapis do bazy danych

Bloczek Zapis do bazy danych pozwala na zapis do bazy danych rekordów oznaczanych specjalną adnotacją.

Konfiguracja polega na:

1. zdefiniowaniu nazwy bazy danych – (w panelu Właściwości patrz też: Źródła danych oraz Odczyt rekordów z bazy danych),
2. określeniu szczegółów odwzorowania rekordów do tabel bazy danych.

Bloczek zapisu do bazy danych składa się z dwóch następujących po sobie elementów:

1. odwzorowanie w miejscu, określające sposób dostosowania rekordu do tabel i kolumn tabel, wstawiające specjalne adnotacje bazodanowe interpretowane przez następny element,
2. mechanizm zapisu do tabel (jeden z kilku – do wyboru za pomocą właściwości Metoda zapisu do bazy danych).

Narzędzie oferuje 3 sposoby zapisu do tabel:

1. SQL_INSERT_UPDATE_DELETE – zapis przy użyciu zapytań SQL (działający praktycznie z każdą bazą danych),
2. BULK_MSSQL_BCP_PROTOCOL – szybki zapis przy użyciu protokołu BulkCopy - działa tylko z bazami Microsoft SQL Server. W przypadku zapisu tą metoda jedyną dostępną operacją jest Insert oraz Dynamic (przy czym wynik ewaluacji musi być operacją Insert lub Skip). Dodatkowo opcja podczas wykonywania operacji Insert nie ustawia samodzielnie relacji między rekordami (Użytkownik musi o to zadbać samodzielnie przed zapisem do bazy danych).
3. BULK_ORACLE_SQLLDR - szybki zapis z użyciem narzędzia SQL Loader - działa tylko z bazami firmy Oracle. Podobnie, jak w przypadku użycia protokołu BulkCopy, metoda ta pozwala tylko na wstawianie danych do bazy (operacja Insert lub Dynamic z ewaluacją do Insert lub Skip).

Do przygotowania danych do zapisu do bazy służy Edytor Mapowań (mapowania w miejscu).

Oprócz standardowo dostępnych adnotacji, Użytkownik ma do dyspozycji także Adnotacje bazodanowe (patrz: Wstawianie adnotacji) .

1. Za pomocą adnotacji Zapis rekordu do bazy danych, Użytkownik określa rodzaj operacji, jaka ma zostać wykonana dla oznaczonego nią rekordu (INSERT, UPDATE, DELETE) na panelu Szczegóły.

2. Jeśli żaden rekord nie zostanie oznaczony adnotacją Zapis rekordu do bazy danych, dane nie będą zapisywane do bazy.
3. Wszystkie rekordy oznaczone adnotacją Zapis rekordu do bazy danych, muszą posiadać w bazie tabele mające identyczne nazwy. Jeśli rekord w schemacie ma inną nazwę niż wymagana tabela, wówczas należy:

• zmienić nazwę na taką samą jak nazwa tabeli,
• dodać do rekordu adnotację Nazwa tabeli/kolumny, a następnie jako wartość adnotacji należy wpisać nazwę tabeli.

4. Taki rekord, powinien także mieć pole reprezentujące klucz główny w tabeli (adnotacja Klucz główny).
5. Jeśli Użytkownik zdefiniował źródło danych i oznaczył dany rekord adnotacją Zapis rekordu do bazy danych, w widoku schematu oznaczone zostaną różnice w strukturze danych pomiędzy wskazaną tabelą, a oryginalnym schematem rekordu (np. brakujące pola, nadmiarowe pola, itp.). Patrz: Kontroler schematów wymaganych.
6. W większości baz danych występują pola generowane automatycznie (zazwyczaj są to sztuczne klucze główne).
7. Aby zostały wypełnione pola po wstawieniu ich do bazy, należy oznaczyć je adnotacją Autogeneracja.
8. W celu oznaczenia relacji bazodanowej między dwoma tabelami należy użyć adnotacji Klucz obcy, a wartość adnotacji ustawić na ścieżkę do pola nadrzędnego relacji.

wskazówka

Dodatkowo Przetwarzanie danych daje możliwość ustawienia warunków dla wstawienia lub aktualizacji wybranych pól w rekordach. Ustawianie warunków odbywa się przez oznaczanie pól specjalnymi adnotacjami.

9. W bloczku bazodanowym został dodany parametr Poziomy izolacji transakcji.
10. Poziom izolacji odnosi się do grupy transakcji bazodanowych i określa stopień ich wzajemnej separacji, czyli w jakim stopniu efekty działania danej transakcji są widoczne i wpływają na inne transakcje.
11. W bazie danych, która umożliwia współbieżny dostęp do jednego zestawu danych wielu Użytkownikom każda sesja, a wewnątrz niej każda transakcja, dokonuje odczytów i/lub modyfikacji współdzielonych danych. Konsekwencją tego są nieuchronne konflikty. Można ich uniknąć izolując od siebie transakcje.

Operowanie na poszczególnych elementach drzewa zostało szczegółowo opisane w rozdziale poświęconym dostosowywania schematów rekordów oraz pól patrz: Przetwarzanie danych.

Przykład wykonania operacji bazodanowej

W poniższym przykładzie stworzono pakiet, który pobiera dane z bazy, wykonuje modyfikacje na danych i zapisuje dane do bazy danych.

1. Przejdź na szczegóły bloczka Zapis do bazy danych. Na panelu Właściwości upewnij się do jakiej bazy danych chcesz zapisać dane. (Domyślnie zazwyczaj to CONNECT_STRINNG)

2. Przejdź na szczegóły bloczka (dwuklik na bloczku). Ustal do jakiej tablicy zapisać dane.
3. Zaznacz rekord i wybierz opcję z menu górnego Baza danych:

• Oznacz jako rekord do zapisu w bazie danych - zaznaczony rekord zostanie dodany do bazy danych
• Dodaj nowy rekord przeznaczony do zapisu - dodanie nowego rekordu do bazy danych

4. Po wybraniu opcji Oznacz jako rekord do zapisu w bazie danych wybierz tabelę, do której chcesz zapisać rekord. Jeżeli nie widzisz opcji do wybrania tabeli na schemacie danych kliknij w ikonę w pasku górnym.

5. Po wykonaniu akcji pojawią się wyszarzone pola (duszki), które pochodzą ze wskazanej wcześniej tabeli w bazie danych, tej do której chcemy zapisać dane.

6. Wyszarzone pola należy uzupełnić. Przeciągnij pola ze schematu na pola wyszarzone i wybierz z menu kontekstowego Zmień nazwę. Nazwa kolumny zostanie zmieniona na nazwę z tabeli, do której chcemy zapisać dane.

7. Możesz też wybrać opcję Dostosuj wszystko.
8. Jeżeli masz nadmiarowe pola, których nie potrzebujesz usuń je ze schematu danych poprzez menu kontekstowe.
9. Jeżeli chcesz aby pakiet mógł być wykonywany kilka razy zmień typ operacji z Insert na Auto Insert/Update w odpowiedniej kolumnie na schemacie danych lub na panelu Szczegóły, po zaznaczeniu rekordu danych z przypisaną operacją zapisu do bazy danych. Po wykonaniu akcji pakiet po każdym uruchomieniu będzie nadpisywać już istniejące rekordy w bazie danych.

10. Oznacz jeszcze Klucz główny dla tabeli. W tym przypadku zakładamy, że klucze główne to imię i nazwisko klienta/ubezpieczonego.
11. Zaznacz pola U_IMIE i U_NAZWISKO kliknij prawym i wybierz z menu kontekstowego opcję Klucz główny.

BULK_ORACLE_SQLLDR - instrukcja

Instrukcja Przetwarzania danych SQL Loader.

Użycie

1. w pliku konfiguracyjnym w kluczu SQL_LOADER_PATH należy podać katalog, w którym jest zlokalizowany sqlldr.exe (opcjonalne)
2. w bloczku Zapis do bazy danych należy wybrać implementację BULK_ORACLE_SQLLDR
3. kolejnym krokiem jest utworzenie (jeśli nie istnieje) i wpisanie nazwy tabeli wyjątków we właściwościach bloczka w UpdaterImplementation>ExceptionsTableName
4. następnie należy zmienić, w zależności od potrzeb, pozostałe właściwości UpdaterImplementation
5. przy uruchomieniu trzeba podać katalog docelowy, w którym będą znajdować się pliki loga i błędnych rekordów.

Sposób wczytywania

SQL Loader

1. SQL Loader jest narzędziem dostarczanym przez Oracle i służącym do szybkiego wczytywania dużych ilości danych do bazy.
2. Plik nazywa się sqlldr.exe i znajduje się zarówno w serwerze jak i w kliencie bazy danych Oracle w podkatalogu bin odpowiedniego produktu.
3. W przypadku ładowania danych w wersjach bazy lub klienta wcześniejszych niż 9i należy upewnić się że wersje SQL Loadera i serwera są jednakowe.
4. Sterowanie Aplikacją odbywa się przez plik kontrolny oraz (w mniejszym stopniu) przez parametry linii komend.
5. W Przetwarzaniu danych całe sterowanie przejmuje Aplikacja.
6. Podczas pracy SQL loader generuje plik loga zawierający szczegóły przetwarzania (rozszerzenie .log) oraz plik z błędnymi rekordami, jeśli dopuszczalna ilość błędów jest większa niż 0 (rozszerzenie .bad). Pliki te zostaną utworzone w katalogu podanym podczas uruchamiania pakietu i są przydatne przy analizowaniu błędów importu.

Ścieżka bezpośrednia

1. SQL Loader umożliwia wczytywanie danych dwoma ścieżkami.
2. Ścieżka konwencjonalna (Conventional Path) polega na generowaniu i wykonywaniu insertów do bazy.
3. Ścieżka bezpośrednia (Direct Path) polega na zapisywaniu bezpośrednio do plików danych.
4. W obecnej implementacji obsługiwana jest tylko ścieżka bezpośrednia, jako że wydajność ścieżki konwencjonalnej jest porównywalna z podstawową implementacją zapisu do bazy (przez dynamiczne SQL-e).

Metody ładowania danych

Metoda jest taka sama dla wszystkich tabel w bloczku.

Użytkownik może wybrać jedną z 4 metod wczytywania danych do tabeli:

1. INSERT - Zapisanie danych do pustej tabeli. Jeśli tabela nie będzie pusta wystąpi błąd.
2. APPEND - Dopisywanie nowych danych do już zawartych w tabeli.
3. REPLACE - Skasowanie danych w tabeli i zapisanie nowych. Działa kasowanie kaskadowe (skasowanie danych w innych tabelach na podstawie kluczy obcych gdy skasowany zostanie rekord nadrzędny). Wymaga uprawnień do wykonania delete.
4. TRUNCATE - Szybkie wyczyszczenie tabeli i zapisanie nowych danych. Nie działa kasowanie kaskadowe. Wymaga uprawnienia DROP ANY TABLE lub tabela musi być w schemie Użytkownika. Wymaga ręcznego wyłączenia wszystkich kluczy obcych referujących do tej tabeli z wyjątkiem tych na innych tabelach z tego bloczka.

Wiele tabel

Ładowanie danych do wielu tabel (schemat z rekordami potomnymi) realizowane jest poprzez uruchomienie dla każdej tabeli oddzielnej instancji SQL Loadera (dzieje się to automatycznie w ramach działania bloczka).

Klucze obce

1. Przy ładowaniu danych wyłączane są klucze obce zdefiniowane w ładowanej tabeli (lub tabelach).
2. Klucze obce w tabelach nieładowanych, ale referujące do tabel ładowanych nie są wyłączone – należy je wyłączyć ręcznie podczas wczytywania metodą TRUNCATE lub REPLACE, gdy nie ma kaskadowego kasowania.
3. Po poprawnym zakończeniu ładowania danych wyłączone klucze są ponownie włączane z opcją walidacji danych.
4. Podczas walidacji nastąpi sprawdzenie czy załadowane rekordy referują do istniejących rekordów tabel nadrzędnych. Jeżeli w tabeli, do której odnosi się klucz obcy nie ma odpowiednich rekordów, to do tabeli wyjątków zostaną dodane wiersze zawierające identyfikator ROW_ID błędnego rekordu oraz nazwę klucza obcego, który został naruszony, a sam klucz pozostanie wyłączony.

Pliki wyjściowe SQL Loadera

1. Podczas działania SQL Loadera powstanie dla każdej wczytywanej tabeli plik z logiem operacji o nazwie nazwa_tabeli.log lub nazwa_tabeli_<guid>.log gdy nie jest włączone nadpisywanie plików loga i błędnych rekordów.
2. W przypadku, gdy dopuszczalna ilość błędnych rekordów jest większa od 0 i wystąpi jakiś błędny rekord utworzony zostanie również plik z błędnymi rekordami o nazwie takiej jak plik loga lecz z rozszerzeniem .bad. Rekordy w tym pliku są w formacie przekazywanym SQL Loaderowi.
3. Pola są w postaci tekstowej w UTF8 rozdzielone znakami |z wyjątkiem pól tekstowych, które składają się z jednoznakowej kolumny zawierającej 1 (dla wartości NULL) lub 0, znaku |, długości wprowadzanego tekstu (ilość znaków przeznaczona na długość jest zawsze taka sama dla kolumny i jest to minimalna ilość znaków pozwalająca zapisać maksymalną dopuszczalną długość tekstu dla tej kolumny w bazie) i samego tekstu.

Zachowanie w przypadku błędów

Klucze obce

1. Jeżeli załadowane dane nie zawierają prawidłowych referencji to podczas włączania kluczy obcych wystąpią błędy.
2. Klucze takie pozostaną wyłączone, a identyfikatory błędnych rekordów zostaną dopisane do tabeli wyjątków. Błędne rekordy należy poprawić lub skasować, a następnie włączyć klucz obcy. Dobrze jest też skasować odpowiednie rekordy z tabeli wyjątków.
3. Klucze obce, które pozostały wyłączone po nieudanym imporcie danych nie zostaną włączone podczas następnego importu nawet gdy będzie w pełni udany.
4. Po każdym błędnym (przerwanym przez błąd ładowania danych SQL Loaderem) należy sprawdzić stan tych kluczy i włączyć te potrzebne (czasami może być konieczne skasowanie niepoprawnych rekordów) przed następnym uruchomieniem pakietu.

Błędne rekordy

1. Gdy SQL Loader uzna rekord za błędny nie zapisze go do bazy danych lecz do pliku z błędnymi rekordami.
2. Jeśli dopuszczalna ilość błędnych rekordów zostanie przekroczona ładowanie danych do tej tabeli zostanie przerwane.

Błąd Przetwarzania

1. Jeżeli podczas wykonywania pakietu wystąpi błąd lub jego praca zostanie w jakiś inny sposób niespodziewanie przerwana to może być konieczne zrestartowanie edytora (lub innego programu wykonującego pakiet) aby ponownie zaczął działać import danych przez SQL Loadera.

Parametry

appSettings

SQL_LOADER_PATH

Ścieżka do katalogu, w którym jest plik sqlldr.exe. Jeżeli ten klucz nie wystąpi w appSettings to zostanie wywołany SQL Loader wskazywany przez zmienną środowiskową PATH.

bloczka

AllowedErrorCount

Ilość błędnych rekordów, po przekroczeniu której nastąpi przerwanie ładowania danych do tabeli.

DataPipeBufferSize

Rozmiar bufora strumienia danych dla SQL Loadera podany w bajtach. 0 oznacza automatyczne dobieranie wartości. Należy eksperymentalnie dobrać odpowiednią wartość lub pozostawić domyślną.

ExceptionsTableName

Nazwa tabeli wyjątków. Tabelę tą tworzymy skryptem o nazwie utlexcpt.sql znajdującym się w podkatalogu \rdbms\admin klienta lub serwera Oracle.

LoadMethod

Metoda ładowania danych do tabel.

MaxCLOBLength

Maksymalna długość dla kolumn typu CLOB.

OverwriteLogAndBadFile

Nadpisywanie plików loga i błędnych rekordów przy ponownym uruchomieniu pakietu.

Uruchomieniowe

BadRecordsLogDirectory

Istniejący katalog, w którym powstaną pliki loga i błędnych rekordów.

Specjalne typy kolumn Oracle

CLOB

Odpowiednik varchar(max) lub text, istnieje możliwość dodania wczytywania tych danych z oddzielnych plików o nazwie podanej w polu rekordu

Data/czas

Czas jest wczytywany z dokładnością do setnych części sekundy.

Ograniczenia szybkich metod zapisu

Szybkie metody wstawiania rekordów do baz danych (BULK INSERT, SqlLdr, itp…) dają duże przyspieszenie, ale narzucają też sporo ograniczeń:

1. wartości generowane przez bazę danych (Identity, wyliczane przez triggery itp..) nie są pobierane z serwera i nie uzupełniają rekordów. W szczególności nie działają pola relacyjne w ramach zapisywanych rekordów, oparte o takie wyliczane wartości.

Ograniczenia specyficzne wg konkretnych implementacji:

1. ładowanie przez BULK INSERT (MS Sql Server) działa paczkami, domyślnie po 1000 sztuk, ale przesyłanie rekordów przez bloczek jest nieświadome (bulk jest stroną aktywną „PULL” i znajduje się po drugiej stronie wewnętrznej kolejki w bloczku).
2. przy wyłączonej opcji Powtarzanie zapisu jeśli przynajmniej jeden z rekordów paczki jest wyrzucony w warstwie BULK, to wyrzucana jest cała paczka i na port błędów wysyłany jest ostatnio odczytany przez BULK rekord z przypisanym błędem.
3. Gdy opcja Powtarzanie zapisu jest włączona to w przypadku błędu nastąpi próba zapisania rekordów z bieżącej paczki pojedynczo. Rekordy poprawne zostaną zapisane do bazy a błędne zostaną skierowane na port błędów. Po zapisaniu wszystkich rekordów z błędnej paczki nastąpi powrót do zapisu paczkami o ustalonym rozmiarze. Opcja Powtarzanie zapisu zmniejsza wydajność zapisu o mniej niż 5 % i wymaga ustawienia rozmiaru paczki na wartość inną niż 0.
4. Szybka metoda Oracle (SqlLdr.exe) narzuca nieco inne ograniczenia – są one opisane w rozdziale dot. SQL Loader.

Jeżeli rekord przeszedł na port wyjściowy w szybkiej metodzie zapisu nie oznacza, że został zapisany do bazy. Logika działania pakietu powinna najczęściej powodować przerwanie przetwarzania w przypadku odrzucenia choćby jednego rekordu przy zapisie. Sytuacje takie traktowane są jako błąd w definicji pakietu, a ewentualne, możliwie dokładne sprawdzenie poszczególnych wartości, można przeprowadzać wcześniej w odwzorowaniu w miejscu.

Dla przykładu:

Jeśli próbujemy zapisać do bazy danych metodą szybką do MS Sql Server (BCP_PROTOCOL, pracującą w paczkach po 1000 elementów) około 1500 rekordów, a jedynie pierwszy i ostatni rekord paczki powoduje błąd zapisu i wycofanie paczki to:

1. bez opcji Powtarzanie zapisu zostaną wygenerowane 2 błędy (po jednym dla paczki) a żadne dane nie trafią do bazy,
2. z opcją Powtarzanie zapisu zostaną zapisane wszystkie poprawne rekordy, a na wyjście błędów zostaną skierowane 2 błędne.

Transakcje bazodanowe

Obsługa baz danych jest istotną cechą Przetwarzania danych. Umiejętne wykorzystanie możliwości serwera bazy danych, transakcji (z ich zasięgiem, poziomem serializacji, zakresem blokad itd.), optymalizacji (kolejności rekordów, indeksów, partycjonowania) umożliwia tworzenie definicji przetwarzania zarówno wydajnych, poprawnych, jak i przejrzystych.

Należy opanować takie pojęcia:

1. Poziom serializowalności transakcji i rodzaje blokad zakładanych przez różne operacje.
2. Zasięg transakcji w sensie rozległości na grafie przetwarzania i rekordach.
3. Wątki i fazy przetwarzania.

wskazówka

Podstawową jednostką dostępu do bazy danych (czy to odczytu, czy zapisu) jest transakcja. Przy domyślnych ustawieniach, transakcja obejmuje pojedynczy odczyt (rekordu lub rekordów, w przypadku długich odczytów sekwencyjnych – nie będących odpowiedzią na zapytanie) lub zapis całego rekordu (od korzenia do liści).

Zasięg transakcji zapisu można zmniejszyć (tak, aby obejmowała tylko pojedynczy zapis jednego rekordu) lub zwiększyć (aby obejmowała wszystkie rekordy zapisywane w całym wątku – rekordy sąsiednie, niepowiązane w strukturze danych).

Transakcje mają miejsce w kontekście sesji (połączeń z serwerem). Przy domyślnych ustawieniach sesja jest współdzielona przez wszystkie bloczki zapisu i zapytaniowe bloczki odczytu w ramach wątku przetwarzania. Oznacza to oszczędne gospodarowanie zasobami serwera oraz pociąga za sobą kilka rzeczy:

Ewentualne przedłużone blokady z odczytu lub zapisu w jednym bloczku nie blokują innych operacji w drugim, ponieważ wszystko odbywa się w jednej transakcji (przy zwiększeniu jej zasięgu).

Odczyt sekwencyjny (bez zapytania) domyślnie zakłada blokady odczytowe na przeczytanych stronach danych (wewnątrz silnika SQL) trwające do końca operacji odczytu. Bez zastosowania „hintów” typu „with(no lock)” lub obniżenia poziomu serializowalności transakcji, może to prowadzić do zakleszczeń w toku dalszej obróbki danych. W takim trybie odczytu należy też zadbać o wymuszenie kolejności rekordów za pomocą klauzuli SQL: ORDER BY …, bez której serwer może (sic!) zwracać kilkukrotnie ten sam rekord danych.

Scalanie wyników do tabel głównych – generowanie MERGE

Bardzo często występuje problem konieczności efektywnej aktualizacji danych w bazie – zarówno:

1. aktualizacji rekordów (większość danych), ale też
2. wstawiania nowych czy
3. usuwania zbędnych (to szczególnie rzadko).

Najprostszą metodą wykonania takich zmian byłoby użycie adnotacji - operacji bazodanowej „dynamicznej”, co skutkowałoby wykonywaniem dynamicznych poleceń SQL: INSERT, UPDATE, DELETE. W przypadku mniejszej ilości danych takie postępowanie jest całkowicie wystarczające, jednak dla ilości idących w setki tysięcy czy miliony rekordów, może to oznaczać zbyt duże czasy przetwarzania (oraz zbyt duże użycie loga transakcyjnego bazy danych).

1. Aby rozwiązać ten problem zwykle stosuje się dodatkowe tabele przejściowe bardzo podobne w strukturze do tabel docelowych, służące tylko do wstawienia do nich rekordów podlegających obróbce (metodami szybkimi), a następnie wykonanie stosownych operacji INSERT, UPDATE, DELETE już wewnątrz serwera.
2. W przypadku współczesnych baz SQL Server czy Oracle, takie 3 operacje można zastąpić jednym operatorem MERGE, który wykona całą pracę oszczędzając przy tym kilkukrotnie na fizycznych operacjach odczytu/zapisu.

wskazówka

Niezależnie od używania 3 operatorów czy jednego, pozostaje konieczność napisania treści poleceń SQL – muszą one wymieniać wszystkie zaangażowane w proces kolumny, co w rzeczywistych przypadkach możne oznaczać setki napisów.

Wsparcie w edytorze

Przetwarzanie danych wspiera ten popularny schemat postępowania poprzez zaoferowanie generatora kodu SQL.

1. Opcja jest dostępna w edytorze mapowań bloczka Zapisu do bazy danych, w jego menu kontekstowym.
2. Jako klucz rekordów jest wykorzystywane pole oznaczone adnotacją Klucz główny. Można też odpowiednio uzupełnić treść skryptów po wygenerowaniu.
3. W wyświetlonym oknie dialogowym Użytkownik ma możliwość wyboru, które operacje go interesują spośród INSERT/UPDATE/DELETE, czy operacja ma być zrealizowana efektywniej (przez MERGE).

Wygenerowane skrypty służą do

1. jednorazowego zakładania tabeli podobnej do rozpatrywanej – CREATE TABLE
2. wykonywania operacji aktualizacji tabeli docelowej (INSERT/UPDATE/DELETE/MERGE), który to skrypt należy umieścić w następnym zadaniu lub w treści „ręcznego” zapisu dowolnego, losowego, pojedynczego rekordu (adnotacja „skrypt bazodanowy”).

History log – historia zmian przy zapisie przez pakiet

Bloczek Zapis do bazy danych potrafi odkładać każdy zapisany wiersz do systemowej historii zmian – tej samej, którą pokazuje aplikacja webowa. Dzięki temu migracja albo wsad uruchomiony z pakietu zostawia taki sam ślad jak zmiana zrobiona ręcznie na formularzu.

• Gdzie się to włącza – we właściwościach bloczka, gałąź History log.
• Co trafia do historii – wyłącznie pola oznaczone w modelu danych jako objęte historią zmian.
• Kiedy – razem z danymi, w tej samej transakcji: wycofanie bloczka oznacza brak wpisu.

BLOCZEK ZAPISU                              HISTORIA ZMIAN
  UMOWA            (modyfikacja)    ──►     Zestaw zmian    użytkownik, data, źródło "VTS"
    NUMER          = "U/2024/17"              Umowa 17            (modyfikacja)
    KWOTA          = 1200.00  ← było 900.00     KWOTA   900.00 → 1200.00
    POZYCJA        (dodanie)                    Pozycja 41        (dodanie)
      KOD          = "A1"                         KOD     → "A1"

Warunki wstępne

Żeby dla danej tabeli powstała historia, muszą być spełnione wszystkie poniższe:

1. Tabela jest opisana obiektem modelu danych – tym samym, z którego korzysta aplikacja webowa. Zapis do tabeli spoza modelu nie zostanie odnotowany.
2. Pola mają włączony zapis historii w projektancie modelu danych. Pole nieoznaczone nie trafi do historii, nawet jeśli bloczek je zapisuje.
3. Bloczek pracuje w trybie transakcji Bloczek (właściwość TransactionHandling). W trybie Rekord nie ma transakcji, więc historii nie dałoby się zapisać razem z danymi – pakiet z aktywną historią po prostu się nie skompiluje.
4. Węzeł pisze do tego samego źródła danych co bloczek – tabele historii leżą w tej samej bazie, co zapisywane wiersze. Węzeł przestawiony na inne źródło (właściwość DataSourceName na adnotacji) zgłasza błąd kompilacji, o ile jego tabela jest opisana w modelu. Taki bloczek trzeba rozdzielić na dwa albo wyłączyć dla niego historię.

Ustawienia

Wszystkie ustawienia znajdują się w gałęzi History log we właściwościach bloczka zapisu.

Ustawienie	Znaczenie
Active	Włącza odkładanie historii dla tego bloczka. Wyłączone – bloczek zachowuje się tak, jakby mechanizmu nie było.
UserSource	Pole audytowe typu „użytkownik", z którego brany jest autor zmiany. Format Obiekt.Pole; lista wyboru rozwija się po skompilowaniu pakietu.
ConstantUser	Stały autor zmiany. Używany, gdy pole UserSource jest puste albo gdy żaden zapisywany wiersz nie zawiera wartości tego pola.
Uncovered	Co zrobić z zapisem do tabeli, której nie opisuje model danych: Error (błąd kompilacji, ustawienie domyślne) albo Skip (pomiń po cichu – wiersz zostanie zapisany, historia nie powstanie).
RecordDeletedValues	Czy przy usunięciu zapisywać wartości, które wiersz miał przed skasowaniem. Domyślnie wyłączone – w historii zostaje samo usunięcie, bez szczegółów pól, dokładnie tak jak robi to aplikacja webowa. Włącz, jeśli z historii ma dać się odczytać, co konkretnie zniknęło.
BusinessContext	Skąd wziąć notatkę o kontekście biznesowym, odkładaną przy zestawie zmian: Constant (z ustawienia poniżej – domyślnie) albo PackageAndBlock (nazwa bloczka i pakietu, ta sama, którą widać w logach przetwarzania).
ConstantBusinessContext	Stała treść tej notatki. Pusta domyślnie – kolumna zostaje pusta, tak jak przed wprowadzeniem tego ustawienia.

ostrzeżenie

Trzeba ustawić UserSource albo ConstantUser – bez żadnego z nich pakiet się nie skompiluje. Historia bez autora zmiany nie miałaby sensu.

Autor zmiany

Zasada wyznaczania autora zmiany jest następująca:

1. Jeżeli UserSource wskazuje pole, które zapisywane wiersze faktycznie zawierają – autor zostaje wzięty z pierwszego takiego wiersza w transakcji i użyty dla całego zestawu zmian.
2. W przeciwnym razie używany jest ConstantUser.

Lista wyboru przy UserSource zawiera wyłącznie pola audytowe typu „użytkownik" tych obiektów, do których ten bloczek faktycznie pisze – nie jest to katalog wszystkich obiektów systemu. Dopóki pakiet nie został skompilowany, lista jest pusta: dopiero kompilacja ustala, do których tabel bloczek sięga.

Co dokładnie zostaje zapisane

Jedna transakcja bloczka to jeden zestaw zmian w historii. Wszystkie zapisane w niej wiersze trafiają do niego razem, zachowując układ drzewa rekordów – dziecko wskazuje na swojego rodzica, tak jak w historii zmian z aplikacji webowej.

Dla każdego wiersza odnotowywane są: obiekt, którego dotyczy, rodzaj operacji i zmienione pola.

Operacja	Co trafia do historii
Dodanie	Nowe wartości pól objętych historią.
Modyfikacja	Stara i nowa wartość – tylko dla pól, które faktycznie się zmieniły. Pole przepisane tą samą wartością nie tworzy wpisu.
Usunięcie	Sam fakt usunięcia, bez pól – a po włączeniu RecordDeletedValues także wartości, które wiersz miał tuż przed skasowaniem.

Uwagi o wartościach:

• Daty zapisywane są w postaci znormalizowanej, niezależnej od ustawień regionalnych.
• Dane binarne (załączniki) zapisywane są jako skrót, nie jako treść. Historia pokazuje, że załącznik się zmienił, ale nie przechowuje jego kopii.
• Wpisy powstałe z pakietu są oznaczone źródłem VTS, co odróżnia je od zmian wprowadzonych przez użytkownika w aplikacji webowej.

Co widać przy kompilacji pakietu

Przy każdym węźle drzewa, który zapisuje do bazy, pojawia się komunikat:

Komunikat	Znaczenie
History log: recorded as data model object 'X'	Informacja – ten węzeł będzie odkładany do historii jako obiekt X.
History log: no data model object describes table '…'	Tabela nie jest opisana w modelu danych. Poziom komunikatu (błąd czy informacja) zależy od ustawienia Uncovered.
History log: the table name is known only at runtime	Nazwa tabeli pochodzi z wyrażenia, więc przy kompilacji nie da się jej dopasować do modelu. Traktowane jak tabela spoza modelu.
History log: this node writes to data source '…'	Błąd – węzeł zapisuje dane do innego źródła danych niż bloczek, podczas gdy historia jest zapisywana w tym samym miejscu co zapisywane wiersze. Patrz warunki wstępne, punkt 4.

Dzięki temu widać na drzewie, które zapisy zostawią ślad, a które nie – jeszcze przed uruchomieniem pakietu.

Wydajność

Przy modyfikacji mechanizm musi odczytać wiersz przed jego nadpisaniem – w przeciwnym razie nie byłoby możliwe zaprezentowanie „wartości poprzedniej". Oznacza to konieczność wykonania jednego dodatkowego zapytania dla każdego modyfikowanego wiersza. Operacja dodania nie wymaga odczytu.

Operacja usunięcia domyślnie również nie wymaga dodatkowego odczytu — ponieważ szczegóły pól nie są zapisywane w historii, odczytywanie wiersza, który i tak zostanie usunięty, byłoby bezcelowe. Włączenie RecordDeletedValues wprowadza konieczność odczytu każdego usuwanego wiersza, w związku z czym w przypadku pakietów usuwających duże ilości danych jest to decyzja wpływająca na przepustowość, a nie jedynie kwestia kosmetyczna.

W praktyce:

• Włączaj tam, gdzie ślad jest wymagany – korekty danych produkcyjnych, operacje na wniosek klienta, wsady podlegające audytowi.
• Nie włączaj dla masowych ładowań liczonych w setkach tysięcy wierszy – spadek przepustowości jest wprost proporcjonalny do liczby modyfikowanych i usuwanych rekordów.

Typowe problemy

Objaw	Przyczyna i rozwiązanie
Pakiet się nie kompiluje: History log requires BLOCK transaction handling	Bloczek pracuje w trybie transakcji Rekord. Przestaw TransactionHandling na Bloczek.
Pakiet się nie kompiluje: History log needs a change author	Nie ustawiono ani UserSource, ani ConstantUser.
Błąd kompilacji o tabeli spoza modelu danych	Dodaj tabelę do modelu danych albo – jeśli ten zapis świadomie ma zostać bez historii – ustaw Uncovered na Skip.
Lista wyboru przy UserSource jest pusta	Pakiet nie został jeszcze skompilowany, albo żaden z zapisywanych obiektów nie ma pola audytowego typu „użytkownik". Można wpisać wartość ręcznie.
Wpisy w historii powstają, ale bez żadnych pól	Pola nie mają włączonego zapisu historii w projektancie modelu danych.
Błąd kompilacji: this node writes to data source '…' while the block writes to '…'	Węzeł został przestawiony na inne źródło danych, a historia trafia tam, gdzie zapisywane wiersze. Rozdziel bloczek na dwa albo wyłącz dla niego historię.
W konfiguracji bloczka nie ma gałęzi History log	Instalacja bez modułu VBP – w takim środowisku mechanizm nie istnieje.
Autor zmiany jest inny, niż oczekiwano	UserSource wskazuje pole, którego zapisywane wiersze nie niosą – użyty został ConstantUser.

Zapis do MongoDB

Zapis do MongoDB odbywa się za pomocą bloczka Zapis do bazy danych.

1. Przeciągnij bloczek Zapis do bazy danych i we właściwościach bloczka wybierz bazę danych typu MongoDB.

2. Dane zapisywane są do bazy w postaci dokumentów BSON.
3. Zapis każdego dokumentu jest atomową operacją, lecz nie ma możliwości powiązania kilku operacji w jedną – nie ma czegoś takiego jak transakcja.
4. Korzeniem zapisywanego dokumentu jest rekord oznaczony adnotacją Zapis rekordu do bazy danych. Nazwa tego rekordu jest nazwą kolekcji, do której dokument zostanie zapisany, chyba że na rekordzie jest adnotacja Nazwa tabeli/kolumny. Na rekordach poniżej takiego rekordu mogą wystąpić adnotacje Zapis rekordu do bazy danych lecz nie oznaczają one zwykle korzenia nowego dokumentu.

Elementy oznaczone adnotacją Dane techniczne nie są uwzględniane przy zapisie. Jeżeli tą adnotacją zostanie oznaczony rekord to ani on ani podrzędne rekordy nie wejdą w skład zapisywanego dokumentu. Jeżeli dodatkowo ten lub podrzędny rekord będzie oznaczony adnotacją Zapis rekordu do bazy danych to taki oznaczony rekord stanie się korzeniem innego dokumentu również zapisywanego do bazy.

Korzeń dokumentu może mieć jedną z następujących operacji:

1. None - Pominięcie zapisu dokumentu.
2. Skip - Pominięcie zapisu dokumentu.
3. Insert - Zapisanie dokumentu do bazy.
4. Update - Zmodyfikowanie istniejącego dokumentu. Modyfikowane są wszystkie znalezione dokumenty.
5. Replace - Zastąpienie dokumentu, jeśli istnieje.
6. AUTO_InsertUpdate - Operacja UPSERT – zmodyfikowanie dokumentu jeśli istnieje i zapisanie go jeśli nie.
7. Delete - Usunięcie dokumentu. Usuwane są wszystkie znalezione dokumenty.

1. Przy operacjach Update, AUTO_InsertUpdate i Delete konstruowany jest dokument zapytania służący do wyszukania dokumentów do modyfikacji.
2. Za pomocą adnotacji Klucz główny należy wskazać pola, które mają być użyte przy wyszukiwaniu. Jeżeli w rekordzie jest pole _id to zostanie ono automatycznie użyte, chyba że jest na nim adnotacja Dane techniczne lub w rekordzie inne pole zostało oznaczone adnotacją Klucz główny. Jeżeli jakieś pole ma być brane pod uwagę zarówno w wyszukiwaniu i modyfikacji to należy oznaczyć je za pomocą adnotacji Klucz główny oraz dodać nowe pole o innej nazwie i z adnotacją Nazwa tabeli/kolumny, w której to należy podać nazwę pola do zmodyfikowania.
3. Pola rekordów mapowane są na pojedyncze wartości a rekordy na dokumenty. Domyślnie nazwa pola/rekordu jest nazwą pola w dokumencie, które będzie miało przypisaną wartość/poddokument. Można to zmienić za pomocą adnotacji Nazwa tabeli/kolumny.
4. Rekordy wielokrotne mapowane są na tablice dokumentów lub pojedynczych wartości. W pierwszym przypadku elementami tablicy będą dokumenty – jest to standardowe zachowanie. W drugim – wartości z wybranego pola rekordu wielokrotnego. Aby rekord został zapisany jako tablica pojedynczych wartości należy oznaczyć jedno jego pole adnotacją Typ danych MongoDB. Adnotacją tą można oznaczyć również podrekord rekordu wielokrotnego – wtedy elementami tablicy będą dokumenty odpowiadające temu podrekordowi.

Przy operacjach modyfikacji (Update, AUTO_InsertUpdate) można wybrać w jaki sposób mają być modyfikowane tablice przez umieszczenie na rekordzie wielokrotnym dodatkowej adnotacji Zapis rekordu do bazy danych.

Poszczególne typy operacji mają następujące efekty:

Typ operacji bazodanowej	Efekt
Insert	Dodanie wszystkich elementów do istniejącej w dokumencie tablicy.
Update lub Replace	Zastąpienie istniejącej w dokumencie tablicy.
AUTO_InsertOnly lub AUTO_InsertUpdate	Dodanie do istniejącej tablicy elementów, których jeszcze w niej nie ma.
Delete	Usunięcie z istniejącej tablicy elementów.

Domyślnie typy danych mapowane są na typy MongoDB w następujący sposób:

Typ	Typ MongoDB (BSON)
Wartość logiczna	Boolean
Data/czas	DateTime
Liczba lub Liczba naukowa	Double
Tekst	String
Binarny lub Identyfikator (GUID)	Binary

ważne

MongoDB nie ma typu decimal.

Adnotacja Typ danych MongoDB pozwala wybrać mapowanie typu danych gdy występuje więcej niż jedna możliwość. Wartość AUTO oznacza domyślne mapowanie, pozostałe możliwości są następujące:

Typ	Możliwe typy danych MongoDB
Liczba	Int32 lub Int64 lub Double
Liczba naukowa	Int32 lub Int64 lub Double
Binarny	Binary lub ObjectId

Jeżeli pole typu tekstowego lub binarnego oznaczymy adnotacjami Autogeneracjai Typ danych MongoDBz typem ObjectId to zostanie wygenerowana i zapisana w tym polu nowa wartość typu ObjectId.

Przykłady mapowań dokumentów:

Schema	Nazwa kolekcji: Dokument
Rekord A zostanie zapisany do kolekcji o nazwie "Rekord A".	"Rekord A": { "Pole 1": "a" }
Rekord B zostanie zapisany jako poddokument rekordu A.	"Rekord A": { "Pole 1": "a" "Rekord B": { "Pole 1": "a" } }
Na "Rekord B" jest adnotacja Dane techniczne, co powoduje, że rekord nie wejdzie w skład dokumentu nadrzędnego.	"Rekord A": { "Pole 1": "a" }
Na "Rekord B" jest adnotacja Dane techniczne, co powoduje, że rekord nie wejdzie w skład dokumentu nadrzędnego. Jednocześnie adnotacja Zapis rekordu do bazy danych powoduje, że rekord zostanie zapisany jako oddzielny dokument do kolekcji o nazwie "Rekord B".	"Rekord A": { "Pole 1": "a" } "Rekord B": { "Pole 1": "a" }
"Rekord B" jest wielokrotny, zostanie zapisany jako tablica dokumentów.	"Rekord A": { "Pole 1": "a" "Rekord B": [ { "Pole 1": "a" }, { "Pole 1": "b" }, { "Pole 1": "c" }] }
"Rekord B" jest wielokrotny i jednocześnie jedno z jego pól ma adnotację Element tablicy. Rekord zostanie zapisany jako tablica wartości wskazanego pola.	"Rekord A": { "Pole 1": "a" "Rekord B": ["a", "b", "c"] }
Wielokrotny rekord "Rekord B" zostanie zapisany jako tablica dokumentów. "Rekord C" będzie poddokumentem dokumentów w tablicy.	"Rekord A": { "Pole 1": "a" "Rekord B": [ { "Pole 1": "a" "Rekord C": { "Pole 2": "x" } }, { "Pole 1": "b" "Rekord C": { "Pole 2": "y" } }, { "Pole 1": "c" "Rekord C": { "Pole 2": "z" } }] }
Adnotacja Element tablicy na "Rekord C" powoduje że "Rekord B" zostanie zapisany jako tablica, której elementami są dokumenty "Rekord C". Żadne inne elementy "Rekord B" nie zostaną zapisane.	"Rekord A": { "Pole 1": "a" "Rekord B": [ { "Pole 2": "x" }, { "Pole 2": "y" }, { "Pole 2": "z" }] }

Bloczki plikowe - wspólne mechanizmy

Poniżej został zawarty opis wspólnych mechanizmów wszystkich bloczków plikowych.

Zapisywanie plików skompresowanych

1. Bloczki: Plik stałopozycyjny, Plik KVF, Plik CSV, Prosty plik XML, Typowane wyjście XML i Plik FWDK mają możliwość zapisywania danych w plikach skompresowanych w formacie zip lub gzip.
2. Aby zapisać plik wyjściowy w wybranym formacie należy podać nazwę pliku wyjściowego z rozszerzeniem „.gz” dla formatu gzip lub „.zip” dla formatu zip.
3. Wielkość liter rozszerzenia nie ma znaczenia. Nazwa pliku w archiwum zip będzie taka, jak nazwa archiwum po odcięciu rozszerzenia „.zip”, tzn. jeśli jako nazwę pliku wyjściowego podamy wynik.csv.zip, to w archiwum o nazwie wynik.csv.zip znajdzie się jeden plik o nazwie wynik.csv.

Zobacz również

Kategoria ogólna

Zadania

Bazy danych