5.2.8. Element define

W skład opisu parametru może też wchodzić element define. Jego obecność oznacza, że wartość parametru ma być wyliczana na podstawie podanej formuły. Jeżeli parametr, w którym element define wystąpił, występuje w elemencie defined (lista parametrów definiowalnych parcooka) lub drawdefinable (parametry definiowalne przeglądającego), to wartość parametru jest po prostu wyliczana na podstawie podanej formuły. Jeżeli zaś parametr jest "normalnym" parametrem ze sterownika (występuje w elemencie unit), to obecność formuły oznacza, że parametr jest niejako przedefiniowany - w bazie i na wykresach będzie obecna jego wartość wyliczona na podstawie formuły, zamiast tej otrzymanej ze sterownika. Konstrukcja taka jest używana najczęściej do wprowadzania różnego rodzaju poprawek do wartości parametrów.

Element define ma następujące atrybuty:

• type - typ formuły opisującej wartość parametru. Możliwe wartości to:

  • RPN - oznacza parametr wyliczany przez program parcook, zawarty albo w jednej z sekcji device albo defined (ale nie drawdefinable). Drugi atrybut - formula - powinien zawierać formułę zapisaną w odwrotnej notacji polskiej (ONP, RPN - reverse polish notation). Składnię dostępnych operatorów opisuje rozdział Sekcja 6.2.

    Opcjonalnie atrybut formula może zawierać wyrażenie null, wtedy element może zawierać podelement script, zawierający tekstowo formułę w języku LUA.

  • DRAWDEFINABLE (RPN) - oznacza parametr wyliczany przez program przeglądający, czyli zawarty w sekcji drawdefinable. Atrybut formula zawiera w takim przypadku formulę również w postaci RPN, ale z nieco innym zestawiem operatorów - zobacz Sekcja 6.1.

  • LUA - oznacza również parametr z sekcji drawdefinable, obliczany przez program przeglądający, ale zapisany jako formuła (skrypt) w języku Lua. Formuła może być zawarta albo w atrybucie formula, albo jako tekstowa zawartość podelementu script. Składnię formuł w języku Lua opisuje rozdział Sekcja 6.4.

• formula - formuła opisująca sposób wyliczania wartości parametru. Jej dokładna postać zależy od atrybutu type (patrz Rozdział 6).

Kolejne atrybuty wykorzystywane są tylko jeśli atrybut type ma wartość LUA :

• lua_formula - wymagany, określa sposób liczenia średnich danego parametru, możliwe wartości to av lub va. Pierwsza wartość oznacza, że najpiew liczone są średnie z wartości parametrów składowych, a następnie tak wyliczone wartości podstawiane są do formuły. Druga wartość oznacza, że liczymy wartość formuły dla wszystkich próbek, a następnie wyciągamy z nich średnią.

  Notatka: Wybór sposobu liczenia może zmieniać wyliczane wartości średnie. Przykładowo, załóżmy że mamy 2 parametry i w danym dniu każdy z nich był zbierany tylko przez część czasu, a formuła liczy sumę tych 2 parametrów. Przy ustawieniu sposobu obliczania av średnia dzienna będzie sumą średnich wartości tych parametrów w danym dniu. Ale jeżeli wybierzemy sposób va, to średnia dzienna będzie sumą średnich wartości parametrów, wybranych z momentów kiedy, oba parametry były zbierane naraz.

• lua_start_date_time - opcjonalny atrybut określający pierwszą datę i godzinę, dla której ma być wyliczany parametr. Dla parametrów LUA określenie zakresu czasowego w jakim parametr ma wartość jest w ogólnym przypadku niemożliwe. Podanie atrybutu może przyspieszyć obliczanie parametru, przez podpowiedzenie programowi, że przed daną datą nie należy go próbować obliczać. Wartość atrybutu musi być zgodna z formatem RRR-MM-DD gg:mm, godzinę podajemy w strefie czasowej GMT.

• lua_start_offset - opcjonalny atrybut jest alternatywnym sposobem określenia kiedy program ma zacząć obliczanie parametru. Wartość atrybutu to liczba sekund jaką należy dodać (lub odjąć jeśli liczba jest ujemna) od daty początkowej - albo wyliczonej automatycznie przez program pierwszej daty w bazie, albo podanej jako wartość atrybutu lua_start_date_time.

• lua_end_offset - opcjonalny atrybut podaje, kiedy mamy zakończyć obliczanie parametru, jako ilość sekund które należy dodać (odjąć jeśli liczba jest ujemna) od automatycznie wyznaczonej przez program daty końca danych w bazie.

  Notatka: Przykładem zastosowania tych atrybutów jest np. określenie parametru, który jest zależny od danych sprzed 7 dni, czyli może być wyliczany na tydzień w przyszłość, ale nie ma sensu go liczyć z pierwszego tygodnia danych w bazie. W takiej sytuacji możemy ustawić zarówno lua_start_offset jak i lua_end_offset na 604800 (7 dni = 7 * 24 h = 7 * 24 * 3600 s = 604800 s).

Ewentualnie zawarty w elemencie define element potomny script nie ma żadnych atrybutów, a formuła zapisana jest jako tekstowa zawartość elementu. Aby uniknąć konieczności zastępowania encjami XML znaków o specjalnych znaczeniach (takich jak & czy <) całą zawartość można zawrzeć w sekcji CDATA, np.

<script><![CDATA[
	if (p("gcie:Kocioł 4:Sterownik:Wydajność kotła", t, pt) < 0.25) then
		v = nan()
	else
		v = 4.0
]]></script>

Element define, podobnie jak wiele innych elementów w konfiguracji IPK, dopuszcza dodawanie elementów i atrybutów z obcych przestrzeni nazw (zobacz Sekcja 5.2.15). W szczególności w elemencie można umieścić element doc z przestrzeni nazw http://www.praterm.com.pl/SZARP/ipk-extra. Jego zawartość będzie wyświetlana jako część dokumentacji parametru w przypadku korzystania z serwera dokumentacji parametrów. Przykład:

<param name="Sieć:Sterownik:zmodyfikowana temperatura zewnętrzna" short_name="Tzew" draw_name="Temp. zewnętrzna"
	unit="°C" prec="2" xmlns:doc="http://www.praterm.com.pl/SZARP/ipk-extra">
	<define type="DRAWDEFINABLE" formula="(*:*:temperatura zewnętrzna) 150 -">
		<doc:doc>Pomiar temperatury zewnętrznej skorygowany o 1,5 stopnia ze względu na złe 
			umiejscowienie czujnika temperatury.</doc:doc>
	</define>
	<draw name="Temperatury sieciowe" min="-30" max="50"/>
</param>
<define type="DRAWDEFINABLE"