8.3. Program extrszb

Program extrszb jest tekstowym narzędziem służącym do odczytywania danych z bazy w formacie SzarpBase i konwersji ich do postaci, która może być wczytana przez arkusz kalkulacyjny.

Program extrszb pozwala na wczytanie danych z bazy w formacie SzarpBase do arkusza kalkulacyjnego. Jest to narzędzie uruchamiane z linii poleceń. Argumentami programu są nazwy parametrów, dla których mają zostać odczytane dane. Program wypisuje wyniki działania na standardowe wyjście lub do zadanego pliku. Na wyjściu program produkuje tabelę, której kolumny odpowiadają parametrom, a w wierszach znajdują się kolejne wartości próbek parametrów - wiersze są posortowane po czasie. Odczytywanie parametrów z bazy można przerwać przez wciśnięcie Ctrl-C. Opcje i argumenty mogą być podane w dowolnej kolejności, chyba że coś innego wynika z ich opisów. Możliwe są następujące:

• Wybór parametrów

  Wyboru parametrów można dokonać na jeden z dwóch sposobów:

  • Podając pełne nazwy parametrów jako argumenty do programu. Można podać dowolną liczbę parametrów. Ponieważ w większości wypadków nazwy parametrów zawierają spacje, trzeba zamknąć je w cudzysłowy.

  • Używając opcji --file=<NAME> lub -f <NAME>, której argumentem jest nazwa pliku zawierającego nazwy parametrów, po jednej nazwie na linię. Opcję można podać wiele razy i można ją łączyć z podawaniem parametrów za pomocą argumentów programu.

  Program sprawdza czy parametry o podanych nazwach istnieją w konfiguracji, jeżeli nie, wypisuje komunikat o nazwie błędnego parametru i kończy działanie z błędem. Konieczne jest podanie przynajmniej jednego parametru, za pomocą dowolnego z powyższych sposobów. Niepodanie żadnego parametru powoduje zakończenie programu z błędem.

• Wybór zakresu czasowego

  Zakres czasu dla jakiego mają być wypisane dane można określić na jeden z dwóch sposobów - albo podając czas początkowy i końcowy, albo określając miesiąc dla jakiego mają być wypisane dane. Podanie zakresu czasowego na jeden z tych sposobów jest wymagane.

  • Opcja --date-format=<STRING> lub -D <STRING> określa format, w jakim ma być podana data dla opcji -s i -e. Format powinien być zgodny z zawartym w opisie funkcji strptime (zobacz man strptime). Domyślnie jest to "%Y-%m-%d %H:%M", czyli data podawana jest w postaci np. "2004-03-11 23:50". Format dotyczy opcji które występują w linii komend za nim, a przed kolejną zmianą formatu. W ten sposób można podać różne formaty dla daty początkowej i końcowej (dwukrotnie używając opcji -D).

  • Opcja --start=<DATE> lub -s <DATE> określa datę i czas pierwszej próbki, jaka zostanie odczytana z bazy. Podana data może ulec zaokrągleniu zależnie od zażądanego typu średniej (np. jeżeli chcemy średnie miesięczne, liczyć się będzie tylko podany rok i miesiąc). Jeżeli podamy tą opcję, wymagana jest także opcja -e. Format daty jest określany przez opcję -D lub domyślny (zobacz wyżej). Podany czas jest interpretowany zgodnie ze strefą czasową ustawioną w systemie operacyjnym.

  • Opcja --end=<DATE> lub -e <DATE>określa datę i czas pierwszej próbki, która nie zostanie uwzględniona przy odczytywaniu danych. W przypadku próbek 10-minutowych należy więc podać czas o 10 minut późniejszy niż ostatnia dana, jaką chcemy odczytać. Podany czas musi być późniejszy niż podany czas pierwszej próbki, także po zaokrągleniu wynikającym z typu zażądanej średniej. Zobacz też uwagi do poprzedniej opcji.

  • Opcja --month=<YYYYMM> lub -m <YYYYMM> umożliwia podanie zakresu dat w alternatywny sposób. Jej argumentem jest napis składający się z sześciu cyfr określających kolejno rok a następnie miesiąc, który nas interesuje - np. "200311" to listopad 2003 roku. Inaczej niż w przypadku poprzednich opcji, czas nie jest interpretowany względem ustawionej strefy czasowej. Wypisywana jest zawartość pliku bazy SzarpBase odnosząca się do próbek z podanego miesiąca, a więc czas odnosi się do strefy Greenwich. Stąd też zależnie od tego czy mamy do czynienia z czasem letnim czy zimowym, na wyjściu możemy otrzymać próbki np. od godziny 1:00 pierwszego dnia miesiąca, do godziny 0:50 pierwszego dnia następnego miesiąca (bo daty na wyjściu podane są w lokalnej strefie czasowej).

  Opcji -s i -e nie można łączyć z -m - należy wybrać jeden ze sposobów określania zakresu czasowego.

• Typ wypisywanych próbek

  • Opcja --probe=<TYPE> lub -p <TYPE> określa typ próbki (rodzaj średniej), jaka będzie wypisywana. Możliwe są następujące:

    • 10min - pojedyncza próbka, czyli średnia z 10 minut, jest to wartość domyślna.

    • hour - średnia godzinna.

    • 8hour - średnia z 8 godzin.

    • day - średnia z dnia.

    • week - średnia z tygodnia.

    • month- średnia z miesiąca.

    • liczba - długość próbki w sekundach, np. dla liczenia średnich 12 godzinnych powinniśmy podać wartość 60 * 60 * 12 czyli 43200.

    Typ wybranej próbki ma wpływ zarówno na interpretację ustawionej daty końca i początku danych, jak i na postać wypisywanej daty.

    Tabela 8-1. Typy próbek - wyjaśnienie

    Okres	Czas próbki	Zakres danych
    10 minut	12:00	(11:50,12:00>
    godzina	12:00	<12:00, 13:00)
    8 godzin	08:00	<08:00, 16:00)
    dzień	01.12	<00:00, 24:00)
    tydzień	pon-nd
    miesiąc	12.2020

    Notatka: W powyższej tabeli, dla zakresów dłuższych niż 10 minut, przedstawiony jest zakres próbek 10-minutowych, z których wyliczona jest średnia. Czyli przykładowo dla próbki godzinnej z 13:00, zakres danych <13:00, 14:00) oznacza, że średnia jest liczona z próbek 10-minutowych od 13:00 do 13:50 włącznie, czyli prawdziny zakres danych to (12:50, 13:50>.

• Format wyjścia Program umożliwia wypisywanie danych w jednym z kilku wybranych formatów. Domyślnie dane wypisywane są na standardowe wyjście w formacie CSV - pola tekstowe oddzielone przecinkami. Wiersze zawierające tylko wartości BRAK DANYCH nie są drukowane. Wartości te w pozostałych wierszach są zastępowane przez napis NO_DATA. Domyślne ustawienia można zmienić jedną z następujących opcji:

  • --csv lub -c ustawia format danych wyjściowych na CSV, jest to ustawienie domyślne.

  • --xml lub -x ustawia format danych na XML. Na wyjściu produkowany jest dokument o formacie określanym przez schemat RelaxNG z pliku resources/dtd/szbase-extr.rng. Format pliku jest dość prosty, oto przykład:

    <?xml version="1.0" encoding="ISO-8859-2"?>
    <extracted xmlns="http://www.praterm.com.pl/SZARP/extr" raw="no">
     <header>
      <param>Kocioł 1:Sterownik:temperatura zadana</param>
      <param>Kocioł 1:Sterownik:temperatura wody za kotłem</param>
     </header>
     <data>
      <row>
       <time>2003-11-02 10:00</time>
       <value>105.0</value><value>22.7</value>
      </row>
      <row>
       <time>2003-11-02 10:10</time>
       <value>105.0</value><value>22.6</value>
      </row>
      <row>
       <time>2003-11-02 10:20</time>
       <value>105.0</value><value>22.7</value>
      </row>
      <row>
       <time>2003-11-02 10:30</time>
       <value>105.0</value><value>22.7</value>
      </row>
      <row>
       <time>2003-11-02 10:40</time>
       <value>105.0</value><value>22.7</value>
      </row>
      <row>
       <time>2003-11-02 10:50</time>
       <value>105.0</value><value>22.7</value>
      </row>
     </data>
    </extracted>

  • --openoffice lub -O powoduje wygenerowanie pliku w formacie OpenOffice Calc (arkusza kalkulacyjnego z pakietu OpenOffice). Wybranie tego formatu zmusza także do określenia pliku wyjściowego (za pomocą opcji -o) - nie jest możliwe wypisanie pliku na standardowe wyjście.

  • --output=<FILE> lub -o <FILE> ustawia plik wyjściowy (zamiast standardowego wyjścia). Opcja ta implikuje -O (format wyjściowy OpenOffice Calc), chyba że zostanie ustawiony inny format za pomocą opcji -c lub -x.

  • --no-data=<TEXT> lub -N <TEXT> ustawia tekst, jaki będzie wypisywany zamiast wartości BRAK DANYCH, domyślnie jest to NO_DATA.

  • --delimiter=<TEXT> lub -d <TEXT> ustawia separator dla formatu CSV (domyślnie są to dwa znaki - przecinek i spacja). Użycie opcji implikuje format CSV, nie można jej więc łączyć z -O lub -x.

  • --empty lub -E powoduje, że wypisywane będą także wiersze zawierające same wartości BRAK DANYCH - domyślnie wiersze takie są opuszczane.

  • --raw lub -r określa, że wartości parametrów mają być wypisane bezpośrednio w takiej postaci, w jakiej znajdują się w bazie, bez konwersji wynikającej z zadeklarowanej precyzji parametrów. Domyślnie konwersja taka jest wykonywana.

• Wypisywanie postępu konwersji

  • Opcja --progress lub -P powoduje, że na stderr wypisywane będą informacje o postępach w konwersji w szczególności przybliżone procentowe zaawansowanie konwersji (określane na podstawie przedziału czasowego jaki pozostał). Po zakończeniu właściwej konwersji program może wypisać informację o kompresji pliku OpenOffice. Program informuje też o zakończeniu działania wypisując komunikat Completed.

• Ustawianie zmiennych libpar

  • Tradycyjnie dla programów SZARP opcja -D<name>=<value> pozwala na ustalenie wartości zmiennej biblioteki libpar. Zwykle będzie potrzeba wybrania bazy danych przez użycie opcji typu -Dprefix=prza.

• Pozostałe opcje

  • --debug=<LEVEL> - ustala poziom ważności wypisywanych komunikatów, od 0 (tylko poważne błędy) do 10 (wszystko), domyślnie jest to 2.

  • --help lub -? - wypisuje pomoc dla programu.

  • --usage - wypisuje skróconą pomoc dla programu - spis opcji i argumentów.

  • --version lub -V - wypisuje informację o wersji programu.

Program korzysta z biblioteki libpar, wczytuje za jej pomocą następujące parametry:

• IPK - ścieżka do pliku konfiguracyjnego z formacie IPK, parametr wymagany, czytany z sekcji globalnej.

• datadir - główny katalog z bazą w formacie SzarpBase, parametr wymagany, czytany z sekcji globalnej.

• oo_script - ścieżka do skryptu kompresującego podany plik XML do dokumentu OpenOffice'a. Parametr jest czytany z sekcji extrszb, nie jest wymagany, ale bez niego nie będzie można generować dokumentów OpenOffice.