Ministerstwo Finansów Instrukcja programu epit WALIDATOR Grudzień
Historia modyfikacji Data Wersja Opis Autor 2003 1 Utworzenie dokumentu DI/NWK 2007 Aktualizacja RI/GST/JNM 2008 Aktualizacja RI/GST/JNM 2009 Aktualizacja DI/GST 2010 Aktualizacja DI/JNM 2011 Aktualizacja DI/JNM 2012 Aktualizacja DI/JNM 2013 Aktualizacja DI/JNM Aktualizacja IU/JNM Ministerstwo Finansów Strona 2/10
Spis treści 1. Wstęp 4 2. Instalacja programu - wymagania sprzętowe i programowe 4 2.1. Instalacja programu 5 2.1.1. Instalacja standardowa programu (pierwsza instalacja) 5 2.1.2. Instalacja dla zaawansowanych 6 2.1.3. Instalacja ręczna 8 3. Obsługa programu 8 3.1. Walidacja danych 9 3.2. Obsługa błędów 9 3.3. Kodowanie danych 10 4. Problemy 10 Ministerstwo Finansów Strona 3/10
Instrukcja programu epit Walidator 1. Wstęp Program epit Walidator wersja 1.0 został opracowany w Departamencie Informatyki Ministerstwa Finansów. Służy on do przeprowadzenia procesu walidacji danych przesyłanych przez Płatników do Urzędów Skarbowych. epit Walidator sprawdza zgodność zestawu danych w zakresie kompletności zestawu i struktury plików, zgodnie ze specyfikacją zawartą w dokumencie Format danych dot. rozliczenia podatku dochodowego od osób fizycznych (PIT11A, PIT40A). Program sprawdza dane odpowiadające zawartości formularzy PIT11A i PIT40A. Program epit Walidator został napisany w języku Java. Wymaga on do uruchomienia środowiska JRE (Java Runtime Environment), które jest dostarczane i instalowane razem z programem epit Walidator. Działanie programu jest kilkuetapowe: 1. Przeprowadzenie procesu walidacji danych (zapisanych w plikach wejściowych: PL9999999999, PO9999999999, DW9999999999 gdzie: 9999999999 oznacza NIP płatnika). 2. Utworzenie plików PL9999999999.wal, PO9999999999.wal, DW9999999999.wal z poprawnymi danymi. 3. W przypadku wystąpienia błędów wygenerowanie plików PL9999999999.bad, PO9999999999.bad, DW9999999999.bad. 4. Wygenerowanie pliku statystki PO9999999999.sta zawierającego informacje o ewentualnych błędach występujących w plikach PO9999999999 oraz DW9999999999. 5. Wygenerowanie zakodowanych plików z poprawnymi danymi. Pliki te zostają zapisane w podkatalogu ZAK, katalogu z danymi wyjściowymi 1. Dla jednego płatnika kompletny zestaw składa się z plików: PL9999999999, PO9999999999 i DW9999999999. UWAGA: Użytkownik programu musi przesłać do US wyłącznie pliki znajdujące się w podkatalogu ZAK, katalogu z danymi wyjściowymi. Dla jednego zestawu danych wejściowych (3 pliki) powstają 3 pliki wyjściowe. 2. Instalacja programu- wymagania sprzętowe i programowe Aby zainstalować program muszą być spełnione następujące wymagania: 1 Katalog z danymi wyjściowymi jest określany jako jeden z parametrów przy uruchomieniu programu epit 2013 Walidator (patrz dalsza część instrukcji). Ministerstwo Finansów Strona 4/10
Wymagania sprzętowe: Procesor: Min. Pentium 100 / zalecane: Pentium II; RAM: Min. 32 MB / zalecane: 64 MB; Karta VGA lub lepsza; Czytnik CD-ROM. Wymagania programowe: Windows 95/98/NT/2000; Zaleca się używanie polskich wersji Windows; 30 MB wolnego miejsca na dysku (na program epit Walidator + JRE). UWAGA: należy przyjąć, że podczas pracy programu minimalny wolny obszar na dysku twardym wynosi: 3 * rozmiar danych wejściowych (tj. plików PL9999999999, PO9999999999, DW9999999999) Program epit Walidator wersja 1.0 wraz z JRE dostarczany jest na płycie CD. 2.1. Instalacja programu Przewidziane są trzy drogi instalacji oprogramowania: standardowa, dla zaawansowanych, ręczna. Różnica pomiędzy dwoma pierwszymi instalacjami polega na tym, iż w przypadku instalacji dla zaawansowanych istnieje możliwość określenia dysku i katalogu docelowego dla programu epit Walidator. UWAGA: Zaleca się wybranie instalacji standardowej, jako zdecydowanie prostszej dla użytkownika programu. Rozpoczęcie procesu instalacji jest jednakowe w obydwu przypadkach i polega na uruchomieniu programu instaluj.bat, znajdującego się w katalogu głównym na płycie CD. Uruchomienia programu instalacyjnego należy dokonać z poziomu Tryb MS DOS w Windows 95/98 ( Wiersz Poleceń w Windows NT/2000) 2. Jest to szczególnie istotne, ponieważ program epit Walidator wykorzystuje długie nazwy plików (dlatego też kopiowania plików nie można przeprowadzić z poziomu takiego programu jak Norton Commander 5.0 i wcześniejszych). 2.1.1. Instalacja standardowa (pierwsza instalacja) Instalacja standardowa oprogramowania składa się z trzech automatycznie realizowanych kroków: 1. utworzenia katalogu dla programu epit Walidator oraz środowiska JRE, 2. zainstalowania pakietu JRE, 3. przegrania plików programu epit Walidator z nośnika CD na dysk twardy. 2 W celu uruchomienia tego trybu należy wybrać z menu Windows: Start Programy Tryb MS DOS (w Windows 95/98) lub Wiersz Poleceń (w Windows NT/2000) Ministerstwo Finansów Strona 5/10
W pierwszym etapie instalacji utworzone zostaną na dysku C: katalog o nazwie epit oraz podkatalog o nazwie jre12. Następnie uruchomiony zostanie (automatycznie) program jre-1_2_2_017-windowsi586-i.exe, instalujący pakiet JRE. Na tym etapie wymagana jest interakcja ze strony użytkownika. Polega ona na udzieleniu odpowiedzi na dwa pytania ze strony programu dotyczące licencji i lokalizacji plików. Dokładny przebieg instalacji JRE przedstawiają rysunki poniżej. Krok pierwszy: Pojawia się licencja oprogramowania dla JRE. Po zapoznaniu się z nią należy wybrać przycisk YES. Krok drugi: Pojawia się pytanie o miejsce instalacji JRE. Należy wybrać tutaj katalog C:\epit2010\jre12 i nacisnąć przycisk Next. W trzecim etapie instalacji nastąpi skopiowane plików programu epit Walidator do katalogu epit na dysku C:. UWAGA: Wymagane jest, aby przy instalacji standardowej pakiet JRE został zainstalowany w podkatalogu jre12, katalogu epit na dysku C:. 2.1.2. Instalacja dla zaawansowanych W przypadku, gdy nie można zainstalować w/w oprogramowania w domyślnym katalogu, istnieje możliwość przeprowadzenia procesu instalacji, podczas której ręcznie podaje się docelowy katalog. W celu wywołania instalacji dla zaawansowanych należy uruchomić instaluj.bat z parametrem tj.: instaluj <lokalizacja_docelowa> Ministerstwo Finansów Strona 6/10
gdzie: <lokalizacja_docelowa> oznacza dysk i katalog docelowy dla programu epit Walidator; <lokalizacja_docelowa> nie może być zakończona znakiem \. Następne dwa kroki tj. zainstalowanie środowiska JRE oraz przegranie plików programu epit Walidator są analogiczne jak przy instalacji standardowej. Ostatnią czynnością jest skonfigurowanie środowiska pracy tj. ustawienie ścieżek dostępu do JRE oraz programu epit Walidator. W tym celu modyfikowany jest automatycznie plik walid.bat. Po instalacji zaleca się skontrolowanie pliku walid.bat skopiowanego do <lokalizacji_docelowej> (w przykładzie poniżej do d:\epit). Należy tutaj skontrolować ścieżki dla zmiennych CLASSPATH oraz PATH (określone przez parametr <lokalizacja_docelowa>). Przykład: Jeżeli program epit Walidator ma zostać zainstalowany na dysku D: w katalogu epit wówczas wywołanie programu instaluj.bat ma postać: Instaluj d:\epit Fragment pliku walid.bat dla instalacji standardowej:. set KATALOG_WEJSCIOWY=c:\epit set wal=%katalog_wejsciowy%;%katalog_wejsciowy%\jre12\bin set path=%wal%;%path% set classpath=%katalog_wejsciowy%\jre12\lib\rt.jar;%katalog_wejsciowy%\epit2 014.jar java poltax.edi.walidator.plikplaski %1 %2 >> %KATALOG_WEJSCIOWY%\log.txt Fragment pliku walid.bat dla instalacji niestandardowej (po modyfikacjach): set KATALOG_WEJSCIOWY=d:\epit set wal=%katalog_wejsciowy%;%katalog_wejsciowy%\jre12\bin set path=%wal%;%path% set classpath=%katalog_wejsciowy%\jre12\lib\rt.jar;%katalog_wejsciowy%\epit2 014.jar java poltax.edi.walidator.plikplaski %1 %2 >> %KATALOG_WEJSCIOWY%\log.txt Ministerstwo Finansów Strona 7/10
2.1.3. Instalacja ręczna Poniżej przedstawiono ręczny opis instalacji programu epit Walidator. W celu jego zainstalowania na dysku twardym należy: 1. Utworzyć katalog dla programu epit Walidator (np. program instalujemy na dysku D: w katalogu o nazwie epit); 2. Utworzyć w nim podkatalog o nazwie jre12 będzie tam zainstalowany pakiet JRE; 3. Z CD-ROM należy uruchomić program o nazwie jre-1_2_2_017-windows-i586-i.exe (znajdujący się w katalogu Java) instalujący pakiet JRE; 4. Po zapoznaniu się z licencją należy odpowiedzieć YES i wskazać katalog d:\epit\jre12\; 5. Skopiować ręcznie wszystkie pliki znajdujące się w katalogu głównym na dostarczanym CD do katalogu gdzie jest instalowany program epit Walidator; 6. Zmodyfikować odpowiednio plik walid.bat tj. ustawić ścieżki dostępu do JRE oraz programu epit Walidator. UWAGA: Ze względu na długie nazwy plików kopiowania należy dokonać w programie je obsługującym (np. za pomocą programu Eksplorator Windows) Przykład: Jeżeli program epit Walidator ma zostać zainstalowany na dysku D: w katalogu walid wówczas krytyczny fragment pliku walid.bat ma postać: set KATALOG_WEJSCIOWY=d:\walid set wal=%katalog_wejsciowy%;%katalog_wejsciowy%\jre12\bin set path=%wal%;%path% set classpath=%katalog_wejsciowy%\jre12\lib\rt.jar;%katalog_wejsciowy%\epit2 014.jar java poltax.edi.walidator.plikplaski %1 %2 >> %KATALOG_WEJSCIOWY%\log.txt 3. Obsługa programu Program epit Walidator pracuje w trybie tekstowym i jest obsługiwany z linii poleceń. Istotne jest aby program epit Walidator uruchamiać z poziomu Trybu MS DOS (w Windows 95/98) lub Wiersza Poleceń (w Windows NT). Związane jest to z wykorzystywaniem długich nazw plików przez program. Dlatego również nie można wykorzystywać tutaj nakładek w postaci np. programu Norton Commander 5.0 i wcześniejszych. W celu ułatwienia pracy przygotowany został plik walid.bat, automatyzujący cały proces. Wywołanie programu epit Walidator ma postać: Ministerstwo Finansów Strona 8/10
walid <katalog_z_danymi_wejściowymi> < katalog_z_danymi_wyjściowymi> [/L] gdzie: walid batch uruchamiający program walidacji <katalog_z_danymi_wejściowymi> - parametr obowiązkowy, istniejący na dysku katalog z danymi wejściowymi, przeznaczonymi do walidacji (argument wymagany) <katalog_z_danymi_wyjściowymi> - parametr obowiązkowy, istniejący na dysku katalog, w którym umieszczane są dane po walidacji (argument wymagany). [/L] parametr opcjonalny, jego użycie powoduje przekierowanie (zapisanie) komunikatów programu pojawiających się na ekranie do pliku tekstowego o nazwie log.txt (czyli zamiast na ekranie informacje przekazywane są do pliku). Plik ten tworzony jest w katalogu programu epit Walidator. W katalogu wejściowym należy umieścić zestaw/zestawy plików zawierających informacje do zweryfikowania. Każdy zestaw musi zawierać trzy pliki: PL9999999999, PO9999999999, DW9999999999. W innym przypadku, przy próbie uruchomienia programu, wygenerowany zostanie odpowiedni komunikat o błędzie i program zakończy działanie. UWAGA: Jeżeli po wywołaniu batcha walid pojawi się komunikat Brak miejsca na środowisko należy przed jego wywołaniem wydawać z poziomu linii poleceń komendę command /e:2048 (operację tą należy powtarzać przy każdym wywołaniu Trybu MS DOS ). 3.1. Walidacja danych Dla pliku PL9999999999 program epit Walidator odczytuje dane informacyjne płatnika. W przypadku stwierdzenia braku lub błędnej (niezgodnej ze specyfikacją) struktury pliku wejściowego program generuje odpowiedni komunikat na ekranie i kończy działanie. Jeżeli program nie znajdzie błędów w pliku PL9999999999, odczytuje on kolejno dane identyfikujące podatnika zawarte w pliku PO9999999999 oraz związane z nimi dane podatkowe pochodzące z pliku DW9999999999. Poprawne dane zapisywane są przez program odpowiednio w plikach: PO9999999999.wal oraz DW9999999999.wal. Jeżeli wystąpią na tym etapie błędy związane z niekompletnością danych lub niespełnieniem reguł walidacyjnych przez te dane, to program wygeneruje pliki PO9999999999.bad oraz DW9999999999.bad z błędnymi rekordami. Zarówno pliki zwalidowane jak i pliki z błędami są umieszczane w katalogu określonym przez drugi parametr wywołania programu epit Walidator (tj. <katalog_z_danymi_wyjściowymi>). 3.2. Obsługa błędów Jeżeli wystąpi błąd w pliku PL9999999999 wówczas: pojawia się odpowiedni komunikat o błędzie na ekranie użytkownika, generowany jest plik z rozszerzeniem bad zawierający komunikat o błędzie i błędny rekord, następuje pominięcie sprawdzania pozostałych danych i program przerywa działanie. Ministerstwo Finansów Strona 9/10
W przypadku, gdy chociaż jeden błąd związany ze złą strukturą lub długością rekordu wystąpi podczas walidacji plików PO9999999999 i/lub DW9999999999, bądź też dane w tych plikach są nieposortowane, wówczas generowany jest odpowiedni komunikat o błędzie i program przerywa walidację zestawu. W przypadku innego rodzaju błędów: generowany jest odpowiedni komunikat o błędzie, program przenosi poprawne dane do nowego pliku/plików (z rozszerzeniem wal ), błędne dane umieszczane są z odpowiednim komunikatem w pliku o rozszerzeniu bad, generowany jest plik PO9999999999.sta który zawiera statystykę błędów. 3.3. Kodowanie danych Po etapie walidacji danych następuje ich zakodowanie. Jest to operacja wykonywana całkowicie automatycznie przez program. Proces kodowania danych odbywa się wyłącznie dla plików zawierających pełen zestaw danych poprawnych, tj. zawierający pliki PL9999999999.wal, PO9999999999.wal, DW9999999999.wal. W wyniku działania programu dla każdego zestawu plików wejściowych powstaje komplet plików zakodowanych. Umieszczane są one w podkatalogu ZAK, katalogu określonego przy wywołaniu programu. Pliki zakodowane nie mają rozszerzeń. UWAGA: Kodowane są tylko dane poprawne (tj. umieszczone w plikach z rozszerzeniem wal ). Nie są natomiast kodowane błędne dane (tj. umieszczane w plikach z rozszerzeniem bad ). 4. Problemy W przypadku problemów z instalacją bądź obsługą programu prosimy kontaktować się z Departamentem Informatyki Ministerstwa Finansów (email: HelpDesk@mofnet.gov.pl). Prosimy o wcześniejsze przygotowanie następującego zestawu informacji: Konfiguracja komputera (wersja Windows, procesor, pamięć, CD); Zawartość (wydruk) plików autoexec.bat, config.sys, walid.bat; Miejsce zainstalowania programu epit Walidator (dysk i katalog); Dokładny opis błędu (wydruk pliku statystyki PO9999999999.sta oraz komunikatu z pliku log.txt + komunikaty o błędach zawarty w plikach z rozszerzeniem bad ). W przypadku kontaktu za pomocą maila prosimy o maksymalnie dokładne opisanie problemu oraz podanie kontaktu zwrotnego. Ministerstwo Finansów Strona 10/10