GgsExpr - plugin pro vyhodnocování TAGů a SQL dotazů do statistik

Funkce pluginu

řídící příkazy
výkonné příkazy
význam parametrů v příkazech

Přebírání proměnných od GgStatu

Popis zpracování SQL příkazů

Poznámky a upozornění

Instalace pluginu

Příklady použití

Doplnění počtu keší nad 1000 m do tabulky zajímavých čísel
Použití SQL

Funkce pluginu

GgsExpr je plugin pro program GgStat.exe, který podle předpisu provádí jednoduché výpočty s TAGy v databázi GeoGetu a výsledek předává v různém tvaru zpět ke zpracování programem GgStat.

Plugin se řídí příkazy z Template souboru podobně jako celý GgStat, který mu je předává. Příkazy jsou dvojího typu:

řídící - nastavují plugin do určitého režimu
výkonné - provádějí vlastní výpočty nebo výstupy

Plugin může používat své lokální proměnné ve tvaru %JMENO%, za JMENO si můžete dosadit vlastní pojmenování hodnoty.

Řídící příkazy

MATCH [ALL | FONUD]: říká pluginu, zda má vyhodnocovat všechny keše nebo jen ty nalezené (implicitní hondnota je FOUND)
TAGVALUETYPE [ASCII | NUM]: říká pluginu, zda má s hodnotami pracovat jako s texty nebo jako s čísly. Protože TAGy jsou v databázi uloženy jako textové řetězce, je implicitní hodnota ASCII - tedy jako text
PRECISION N: nastavuje počet desetinných míst pro práci s čísly
OUTVALUETYPE [ASCII | NUM]: říká pluginu, v jakém tvaru vypisovat hodnotu. V drtivé většině jsou vypisované hodnoty číselné, ale na příklad pro příkazy SQL_CMD se textová interpretace hodí třeba pro generování řádků tabulky, pro definici CSS a podobně.
ERRORMISSINGVARIABLE [YES | NO]: říká pluginu, jak pracovat s proměnnými, pro které nemá definici. Implicitní hodnota YES znamená, že bude hlášena chyba. Hodnota NO znamená, že text zůstane beze změny a je tak možné vrátit GgStatu text, v kterém použije svou proměnnou (např. %ALLCACHES%). Velmi doporučuji vypnout kontrolu až po odladění šablony, značně to usnadní hledání chyb. Příkaz lze použít opakovaně, ale stejně jako ostatní řídící příkazy platí vždy poslední nastavení a platí pro celé spuštění pluginu.
DB soubor: mění databázi, s kterou bude plugin pracovat. Implicitně je používána databáze, kterou nastavuje přes předávané parametry GgStat.exe, tímto příkazelm lze databázi změnit. Změna platí do další změny nebo do ukončení plugnu.

Výkonné příkazy

OUTVAR NAME TAGNAME TYPE [operator [VAL1 [VAL2 [... VALn]]]

vybere z databáze všechny keše s ohledem na TAG TAGNAME, příkaz TYPE a další podmínky (operator, ...). Výsledek předá programu GgStat tak, aby jej uložil do své proměnné NAME. Příkladem budiž ukázka, která v GgStatu nastaví proměnnou VYSOKO na počet keší s nadmořskou výškou nad 1000 metrů:

OUTVAR VYSOKO Elevation COUNT > 1000

LOCALVAR NAME TAGNAME TYPE [operator [VAL1 [VAL2 [... VALn]]]

identický příkaz jako předchozí, ale výsledná hodnota je uložena v proměnné pluginu pro další použití a výpočty

EVALOUTVAR NAME výraz

vyhodnotí výraz dosazením proměnných a výpočtem. Výsledek předá GgStatu tak, aby nastavil svou proměnnou PROCENTA. Příklad:

EVALOUTVAR PROCENTA %POCET%/%CELEM%*100

(Předpokládám, že dříve byl použit jeden z příkazů LOCALVAR nebo EVALLOCALVAR pro výpočet proměnných CELEM a POCET).

Výrazem může být i zjednodušený perlový test, který bude vracet jedinou hodnotu:
EVALOUTVAR PROCENTA return(%CELKEM%<=0 ? 0 : %POCET%/%CELEM%*100)

Upozorňuji, že perl má různé operátory porovnání pro čísla (==, <, ...) a pro textové hodnoty (ne, eq, lt, ...).

EVALLOCALVAR NAME výraz

totéž jako předchozí příkaz, ale výsledek je uložen do lokální proměnné pluginu

SETVARDEFAULT NAME výraz

otestuje existenci proměnné NAME a pokud není definovaná, definuje ji s hodnotou výraz. Výraz může obsahovat i výraz používající jiné lokální proměnné nebo to může být přímo hodnota.

HTML text

do textu dosadí všechny dříve vypočtené lokální proměnné a výsledek předá programu GgStat pro zpracování příkazem HTML

COMMAND text

v textu vyhledá všechny lokální proměnné %JMENO%, nahradí je uloženými hodnotami a předá GgStatu pro jeho příkaz COMMAND

SQLSTART

zahajuje definici a zpracování vlastního SQL příkazu. Pluginem je možné zpracovat uživatelem zadaný SQL dotaz a jeho výsledek pak zpracovat. Je tak možné přímo pluginem vytvořit třeba nějakou tabulku a není potřeba pro každou maličkost vytvářet samostatný plugin.

Plugin pracuje v tomto případě tak, že načte všechno až do příkazu SQLEND a až pak vše načtené zpracuje. Napřed vykoná SLQ dotaz zadaný příkazy SQL_SQL a pro každý řádek a sloupec odpovědi provádí postupně všechny příkazy zadané příkazem SQL_CMD v tom pořadí, jak byly načteny.

SQLEND

Ukončuje zpracování SQL příkazu

SQL_SQL

definuje SQL příkaz. Těchto řádků může být za sebou i více a plugin je spojí do jediného příkazu. U delších příkazů se rozdělením do samostatných řádků zachová relativní čitelnost příkazu.

SQL_CMD [ROWSTART | ROWEND | COLUMN] příkaz

Definuje jeden příkaz, který se vykoná na zečátku nebo na konci vyhodnocování řádku (ROWSTART, ROWEND) nebo při vyhodnocování sloupce COLUMN odpovědi na zadaný SQL dotaz. Jako příkaz lze použít libovolný příkaz pluginu (pochopitelně s výjimkou příkazů SQL*). Rychlost zpracování je podstatně ovlivněna počtem příkazů SQL_CMD - vykonává se prakticky M*N krát (M je počet řádků tabulky vrácené SQL dotazem a N je počet sloupců). Proto je výhodné vytvořit méně samostatných příkazů byť by byly podstatně komplikovanější - viz příklad u SQL_CMD_CONTINUE.

SQL_CMD_CONTINUE příkaz

Definuje pokračování příkazu uvedeného v předchozím SQL_CMD nebo SQL_CMD_CONTINUE. Tím se zachová přehlednost a přitom může být příkaz poměrně dlouhý. Výhoda se projeví na příklad při nastavování proměnné testováním různých hodnot, kdy není třeba mnoha různých SQL_CMD zpracovávanných postupně, ale vše lze napsat v jediném příkaze, což podstatně urychlí zpracování. Příkladem budiž nastavení jména souboru s ikonou podle typu keše:

      SQL_CMD COLUMN EVALLOCALVAR Gif return('%3%' eq 'Traditional Cache' ? '2.gif' :
      SQL_CMD_CONTINUE '%3%' eq 'Unknown Cache' ? '8.gif' :
      SQL_CMD_CONTINUE '%3%' eq 'Multi-cache' ? '3.gif' :
      SQL_CMD_CONTINUE '%3%' eq 'Virtual Cache' ? '4.gif' :
      SQL_CMD_CONTINUE '%3%' eq 'Event Cache' ? '6.gif' :
      SQL_CMD_CONTINUE '%3%' eq 'Earthcache' ? '137.gif' :
      SQL_CMD_CONTINUE '%3%' eq 'Letterbox Hybrid' ? '5.gif' :
      SQL_CMD_CONTINUE '%3%' eq 'Webcam Cache' ? '11.gif' :
      SQL_CMD_CONTINUE '%3%' eq 'Wherigo Cache' ? '1858.gif' :
      SQL_CMD_CONTINUE '%3%' eq 'Mega-Event Cache' ? '453.gif' :
      SQL_CMD_CONTINUE '%3%' eq 'Locationless (Reverse) Cache' ? '12.gif' :
      SQL_CMD_CONTINUE '%3%' eq 'Cache In Trash Out Event' ? '13.gif' :
      SQL_CMD_CONTINUE '%3%' eq 'Lost and Found Event Cache' ? '3653.gif' :
      SQL_CMD_CONTINUE  '')

Význam parametrů v příkazech

NAME jméno proměnné pro uložení výsledku

TAGNAME jméno TAGu, s jehož hodnotami bude pracováno.

TYPE

typ výpočtu (zacházení s hodnotami v tagu), výsledkem je jediná hodnota (na výstup bude vypsán příkaz GgStatu
COMMAND: SETVAR NAME hodnota). Možnosti jsou:

`AVG, MIN, MAX`	získá průměr, minimální nebo maximální hodnotu tagu
`COUNT`	získá počet keší s tagem
`SUM`	získá součet hodnot tagu.

operator porovnávací operátor pro klauzuli WHERE. Může být použit jeden z =, <,>, <=, >=, <>, LIKE, BETWEEN, IN (k poslednímu je nutné použít ještě VAL1 až VALn)

VAL1, VAL2 hodnoty pro výběr (pozor na použití prikazu TAGVALUETYPE)

Přebírání proměnných od GgStatu

GgStat načítá z template souboru některé hodnoty, které poskytuje volaným pluginům. GgsExpr většinu těchto hodnot načítá a za jistého předpokladu i poskytuje ke zpracování.

Proměnná GgStat	Proměnná v GgsExpr	Poznámka
`INCODING`	`$Incoding`
`OUTCODING`	`$Outcoding`
`CACHER`	`$Cacher`
`HOMECOORDINATES`	`$HomeLat, $HomeLon`
`MYCACHESOWNER`	`@aMyCachesOwners`
`OWNERCACHE`	`$Ownercase`
`OWNERID`	`@aOwnerid`
`BORDER`	`$Border`
`FRAME`	`$Frame`
`WIDTH`	`$Width`	šířka bloku, v kterém je volám plugin; pokud je volán uvnitř příkazu SPLIT 2, bude šířka poloviční než skutečná šířka statistik, pokud je volán za příkazem WIDTH_NEXT, bude to šířka individuální
`COLORSCALE`	`$Colorscale`
`COLORS`	`@aColors`	pole barev, pořadí je shodné s pořadím v Template souboru. Jedná se o aktuální barvy, tedy poslední nastavení před voláním pluginu.
`UNIT`	`$Unit`
`OWNERCASE`	`$Ownercase`
`DB`	`$DBFile`	ta je zároveň dostupná v interní proměnné %GGS_DB%

Když vezmeme v úvahu způsob zpracování příkazů uvnitř GgsExpr, můžeme zpřístupnit kteroukoli z uvedených hodnot způsobem uvedeným v následujících příkladech:

EVALLOCALVAR GG_BGCOLOR (return($aColors[0])) EVALLOCALVAR GG_WIDTH (return($Width))

Popis zpracování SQL příkazů

Protože se může zdát zpracování SQL bloku poněkud komplikované a rozdíl mezi příkazy SQL_CMD ROWSTART, ROWEND a COLUMN nejasný, uvádím zde trochu techničtější popis postupu zpracování celého bloku, který snad rozdíl ozřejmí.

napřed je celý blok mezi SQLSTART a SQLEND načten. Všechny příkazy SQL_SQL jsou spojeny do jediného (SQL komentáře nejsou na překážku). Každý SQL_CMD je uložen samostatně, je zachováno jejich pořadí
plugin vykoná SQL příkaz a získá tím tabulku "odpovědi"
pro každý řádek odpovědi postupně provede všechny uložené SQL_CMD. Před provedením každého z nich provede náhradu %x% za hodnotu v příslušném sloupci aktuálně zpracovávaného řádku odpovědi (cykl od %1% do %n%).
Ale pozor: příkazy ROWSTART jsou provedeny jen v případě, že právě dochází k náhradě %1% a ROWEND jen když právě dochazí k náhradě hodnoty z posledního sloupce, tedy %n%

Jak je vidět, v drtivé většině případů si lze vystačit s příkazem SQL_CMD COLUMN. Skoro bych řekl, že při správném poskládání příkazů vždy. Správným poskládáním mám na mysli postupné ukládání výstupu do lokální proměnné a posledním příkazem pak pomocí SQL_CMD COLUMN HTML hodnotu této proměnné vypsat.

Instalace pluginu

Instalace pluginu spočívá ve zkopírování souboru GgsExpr.exe někam do datového adresáře GeGetu. Umístění souboru pak musí být v souladu s příkazem PLUGINSTART v souboru Template.

Poznámky a upozornění

Pozor na porovnávání textových hodnot TAGu v číselném režimu. Pokud chcete pracovat s textovou hodnotou TAGU, vždy musí být použit příkaz TAGVALUETYPE ASCII

Pozor na jména tagů nebo hodnoty tagů obsahující mezeru. V tom případě je potřeba je uzavřít do uvozovek, např. při zjisťování počtu keší v Jabloneckém okrese:

TAGVALUETYPE ASCII MATCH ALL OUTVAR Jablonec "CZ okres" COUNT = "Jablonec nad Nisou"

Ukázky některých fint, které by vás třeba nenapadli

Převod čísla na textový řetěz - zde pořadové číslo měsíce:

EVALLOCALVAR JmenoMesice return(("Leden","Únor",..."Prosinec")[%CisloMesice%])

Protož od verze 1.3.11 obsahuje plugin modul Date::Calc, je možný snadný přístup ke kalendářovým hodnotám a funkcím:

EVALLOCALVAR PocetDniVMesici return(Days_in_Month(2000,2))
EVALLOCALVAR PocetDniMeziDaty return(Delta_Days(2002,3,12, 2011,5,12))

Ukázky použití pluginu

Na webu jsou k dispozici ukázkové šablony, jejichž vložení do souboru Template by mělo zajistit požadovanou funkci.