Obsah

Všeobecný popis systému

Obecně
Struktura systému
Popis skriptovacího jazyka
Vysvětlivky k výkladu syntaxe
Komentáře
Bloky a skripty
bloky
skripty
Proměnné
Resultset
Chybové zprávy
Procedury, funkce
Výzazy (logický výraz , numerický výraz, textový výraz )
Matematické, logické a textové funkce
Operátory
Speciální jména

Inicializace

Příkazy

foreach
if ( ... ) else ...
echo
print, println
load ... into,
sync ... by ... into
save ... into
append ... into
break
exit
return
messages
in (.convertor , .format , .format.plain , .format.fixed , .format.fixed , .counter , .null, .skip, .condition, .style)
sql (.error, .error.exit, .error.display, .error.max, .isError, .setError, .timeout, .rows.max, .select, .execute, .getString, .getRow)
dsn (.select , .close , .load , .params )
out (.convertor , .trim , .format , .style , .null)
output (.clear , .get )
system (.execute , .priority , .gen , .setError , .isError , .message , .runEvent , .invoke , .exit, .zip, .unzip )
file (.load , .copy , .delete , .save , .append , .move , .isDirectory , .exists , .getName, .getParent, .getPath, .rename)
directory (.create, .list , .listFiles, .exists, .getName, .getParent, .rename)
form (.create, .getValue, .addItem, .display )
url (.load, .get, .post, .save ) 

Všeobecný popis systému 

Obecně

systém je určen:

• k údržbě heterogenních databází s velkým množstvím různorodých zdrojů dat (všechny známé databáze, textové soubory, binární soubory se známou strukturou a pevnou délkou věty, URL, WWW tabulky a stránky ...)

• k transferu dat libovolným směrem mezi těmito zdroji dat,

• k hromadnému zpracování, tvorbě pohledů přes všechny tyto datové zdroje ...),

• automatozaci činností (přenosy dat, pohledy, exporty, importy ...) pomocí skriptovacího jazyka trochu podobného perlu.

• dalším činnostem spojenám s daty.

Systém je nezávislý na platformě (testován je na všech verzích Windows 9x, NT, 2000, na LINUXu, na NOVELLu ...)

Struktura systému

Akce, které bude MSQL systém provádět se mu zadávají pomocí příkazů skriptovacíha jazyk (pracovně nazvaného msql). Veškeré akce, které uživatel požaduje (i ty, které jsou vybírány např. z menu grafického prostředí) jsou převáděny na příkazy tohoto „jazyka“.

Vlastní systém se zkládá z jádra (to příkazy vykonává) a různých interface (ty naopak příkazy formulují a předávají ke zpracování).

Jádro provádí vlastní příkazy, které obdrželo od některého z interface. Tomuto interface také vrací výsledky své činnosti a případné zprávy (chybové a jiné). Interface tyto výsledky a zprávy zobrazuje uživateli (nebo např. ukládá do souborů na serveru - to pokud použitý interface přímo nekomunikuje s uživatelem). Jádro neví, jakým způsobem byly příkazy zadány ani jak budou zpracovány zprávy, které samo vrací.

Interface zajiš'tují komunikaci mezi zadavatelem příkazů (podle typu interface to může být uživatel nebo např. proces na GapoServeru) a jádrem (které provádí vlastní příkazy).

V současnosti jsou k dispozici tyto interf ace:

• MSQL (MSQL_s):

grafický interface; kompletní údržba databází a DSN, tvorba SQL příkazů a skriptů.
Umožňuje přidávat, mazat a upravovat jednotlivá DSN, má v sobě grafický editor SQL příkazů a skriptů, dovoluje editovat SQL (MSQL) skripty, zvýrazňuje syntaxi SQL (MSQL) příkazů; soubory může načítat z lokálního disku nebo z GapoServeru atd.
Je dostupný i jako exe program pro Windows.

• MSQLInteractive

grafický interface. Dovoluje uživateli psát, ladit a spuštět SQL příkazy a skripty, nebsahuje však část pro údržbu databází a DSN ani grafickou tvorbu SQL příkazů.
Je dostupný i jako exe program pro Windows.

• MSQLr

grafický interpret skriptů; dovoluje pouze spouštět již připravené MSQL skripty bez možnosti změnit parametry a psát vlastní příkazy.
Je dostupný i jako exe program pro Windows.

• MSQLarts

: samostatný server (spouští se spolu s GapoServerem, poslouchá na určeném socketu; je možné se k němu připojit pomocí telnetu, funkčně shodný s MSQLinteractive) - viz popis GapoServeru.

• MSQLc

: interpret příkazů spouštěný z příkazové řádky. Funkčně shodný s MSQLInteractive , pro svůj chod však nevyžaduje grafické prostředí.

• MSQLs

: servlet interface. Běží jako servlet na libovolném WWW serveru; funkčně shodný s MSQLInteractive .

• MSQLrts

: interface pro klienta RTs systému (skripty se spouští na straně serveru)

Jednotlivé interface budou popsány v samostatných dokumentech. Následující dokument je pro všechny společný

Popis skriptovacího jazyka

Vysvětlivky k výkladu syntaxe:

• jména dávek

začínají @ (zavináčem).
Jména souborů, načítaných z lokální stanice mohou (v některých speciálních případech musí) začínat znakem % (procenta).
Jména souborů načítavých ze serveru, ukládaných na server nebo zpracovávaných na serveru MUSÍ začínat znakem ! (vykřičník).
pokud je skript načítán ze serveru, začíná příkaz @!

Příklady:
- skript načtený z lokálního disku: @c:\SQL\moje_davka.msql
- stejný skript načtený ze serveru: @!c:\SQL\moje_davka.msql
- příkaz OS, spouštěný lokálně: %cmd /c dir c:\ výpis root adresáře svazku c:
- příkaz OS, zaslaný na server typu UNIX: !ls / výpis root adresáře serveru

• v hranatých závorkách [ ] jsou volitelné položky

• v lomených závorkách < > je seznam položek, z nichž musí být zvolena alespoň jedna

• svislice | je použita k oddělení seznamu alternativ

• malá / velká písmena se zatím nerozlišují, pro kompatibilitu s budoucími vezzemi doporučujeme používat ve všech příkazech malá písmena, v SQL příkazech naopak velká.

• tučně

- příkazy systému (musí být napsány tak, jak jsou uvedeny zde)

• italikou

- údaje zadávané z venku (jména proměnných...)

• podtržené -

speciální jména (např. vnitřní proměnné); jsou to alternativy ke jménům oproměnných, některé ale mají speciální význam.
Musí být zadávýny přesně tak, kjak je zde uvedeno.

• VELKÝMI TUČNÝMI PÍSMENY -

SQL příkazy

Jinak jsou použita běžná syntaktická pravidla:

Komentáře

jsou stejné jako v jazyce c nebo Perl:

Začínají dvojicí znaků /* a končí */ . Veškerý text mezi těmito značkami je ignorován.

Jednořádkové komentáře začánají dvojicí znaků // (lomeno) - jako v jazyce c - a končí na konci řádku - je ignorován text od této značky do konce řádku.

Bloky a skripty

bloky

Blok je část programu uzavřená ve složených závorkách. Proměnné delkarované uvnitř bloku nejsou vidět vně bloku.

{

....

toto je blok

....

}

Jakýkoli text může být uzavřen do bloku.

skripty

Skript je uložena v samostatném souboru. Z běžícího programu je skript zavolán (spuštěn) příkazem

@úplná_cesta_k_souboru [parametr1 [parametr2] ... ]

Skripty lze načítat z lokálního filesystému (začínají "@") nebo ze serveru - začínají "@!" (na serveru musí být povoleno čtení z adresáře se skripty). Vždy se však skripty zpracovávají na lokálním počítači.

Skript může mít parametry. Předávají se na příkazové řádce za názvem skriptu, jsou oddělené mezerou nebo tabelátorem. Pokud má parametr obsahovat mezeru, musí být uzavřen v uvozovkách. Parametrz jsou při předání zpracovány a proměnné nebo výzazy mezi ${ ...} jsou nahrazeny hodnotami (viz příkaz echo ).

Příklad:

@c:\cesta_k_souboru_se_skriptem param_1 param_2 "param 3 s mezerami" param_4

Uvnitř skriptu se na parametry odkazuji pomocí speciálních proměnných $1, $2 ... až $n (existuje jich tolik, kolik parametrů bylo předáno - počet parametrů není omezen).
Parametry jsou normální textové proměnné, t. zn. že:

• mají textovou hodnotu (pokud je potřebujeme v matematickém výrazu, použujeme funkci num () ).

• platí pouze uvnitř těla skriptu

• lze změnit jejich hodnotu

Jinak je skript shodný s blokem (i kdyz její text nemusí být uzavřen v { ... } - to je dáno tím, že je v samostatném souboru).

Proměnné

• Jména všech proměnných

MUSÍ začínat $ (dolarem) - je to proto, aby systém byl schopen odlišit jeho vlastní proměnné od SQL příkazů (protože název SQL příkazů, direktiv ani jmen sloupců u většiny DB strojů obvykle nezačínají $)

• proměnné nemusí být deklarovány. Deklarují se automaticky prvním použitím. Jakmile je proměnné přiřazena hodnota určitého typu, nelze tento typ již změnit - t.zn, že této proměnné lze nadále přiřazovat pouze hodnoty shodného typu (jinak bude hlášena chyba).

• proměnné jsou platné od místa deklarace (t. j. od místa prvního použití - pokud nejsou explicitně deklarovány) do konce bloku, uvnitř kterého vznikly a jsou viditelné i ve vnořených blocích.
  Pokud je uvnitř vnořeného bloku změněna hodnota proměnné, tato změna je viditelná i v nadřízených blocích, pokud je tam viditelná proměnná.
  Volání skriptu se z tohoto pohledu

považuje za samostatný blok, i když text skriptu není uzavřen v { ... }

• Proměnné lze deklarovat explicitně příkazem

var $jméno_proměnné [ = hodnota];

Pokud proměnná se jménem $jméno_proměnné již existovala v nadřízených blocích, bude skryta a místo ní bude do konce tohoto bloku používána proměnná zde deklarovaná (včetně vnořených bloků).
Pokud by proměnná stejného jména existovala v tomto bloku, vznikne chyba. Pokud je proměnné přiřazena hodnota, vznikne proměnná toho typu, jaký typ hodnoty se jí přiřadí. Jinak se typ proměnné určí prvním přiřazením hodnoty.

Resultset

představuje speciální typ proměnné. Vznikne jako výsledek SQL příkazu select:

SAVE SQL_SELECT INTO $jméno_resultsetu FROM ...

volání procedury SQL serveru:

SAVE result INTO $jméno_resultsetu jméno_SQL_procedury [parametry procedury]

nebo může být explicitně vytvořen:

SAVE textový_výraz INTO $jméno_resultsetu

Jeho hodnotu nelze změnit ani jej nelze použít ve výrazech (proměnná se jménem $jméno_resultsetu může být explicitně deklarována ve vnořených blocích, nebude to však již resultset a původní resultset se tím stane v tomto bloku nepřístupným).

K resultsetu lze přidávat záznamy, které musejí mít stejnou strukturu jako záznamy, které již v resultsetu jsou (pokud by tomu tak nebylo, vznikla by při zpracování takového resultsetu chyba):

APPEND SQL_SELECT INTO $jméno_resultsetu FROM ...
APPEND result INTO $jméno_resultsetu jméno_SQL_procedury [parametry procedury]

nebo

APPEND textový_výraz INTO $jméno_resultsetu

textový_výraz musí být řádek textu , kde jednotlivé položky jsou odděleny čárkou, textové údaje uzavřeny v apostrofech a NESMÍ KONČIT KONCEM ŘÁDKU (znaky s ASCII/UNIkódem 10 nebo 13)

Resultset lze použit v příkazech LOAD (hromadbý impo rt do tabuklky) nebo v příkazu cyklu foreach. Lze jej jako celek zapsat do souboru nebo URL.

Jako jméno resultsetu lze napsat jméno textového souboru (nebo obecného souboru popsaného pomocí in.format.plain ) - data pak budou čtena z tohoto souboru.

Resultset nebo textový soubor má jednotlivé záznamy na samostatných řádcích, řádky jsou ukončeny znakem CR nebo LF nebo oběma.
Sloupce jsou odděleny čárkami, textové údaje jsou uzavřeny v apostrovech (tzv. CSV formát souboru).

První řádek resultsetu nebo souboru může obsahovat informace o sloupcích v tomto tvaru:

#!jméno_sloupce_1, jméno_sloupce_2, ...., jméno_sloupce_n

Počet položek (oddělených čárkami) musí být stejný jako počet sloupců s daty, jinak je teno řádek ignorován.

Pokud tento řádek existuje a má správný formát a počet položek, jsou jména z něj zpracována jako jména sloupců resultsetu a lze se na ně odkazovat např. v příkaze foreach.
Jinak budou v cyklech k dispozici pouze čísla sloupců ($col1, $col2 ...)

Chybové zprávy

Při behu skriptů mohou vzniknout různé chyby. Pokud se tak stane, skript bude ukončen a o chybě je podána zpráva (vyjímkou jsou chyby při SQL operacích - to lze nastavit pomocí sqp.error.max , sqp.error.exit , sqp.error.display ).

Zprávy o chybách vzniklých při zpracování příkazů, skriptů... jsou zobrazovány do výstupního kanálu. Všechny chybové zprávy začínají prefixem '> Error ' (místo '> ' bude prefix pro zprávy vracené serverem; lze nastavit v msql.properties ). Pak může následovat text v závorce, který určuje kategorii chyby, dále vlastní text chybové zprávy. Kategotie chyb jsou následující:

• '> Error (SQL)'
  jde VŽDY o chybu vracenou příslušným ovladačem databáze - MSQL ji pouze zobrazuje. Na dalších řádcích je text chybové zprávy tak, jak jej vrátil ovladač databáze. Chybové zprávy tohoto typu nemají jednotný formát - každý výrobce ovladačů má svůj způsob zobrazování chybových zpráv. Výpis těchto zpráv lze zakázat příkazem 'sqp.error.display '

• '> Error (SCRIPT)'
  obvykle chybaná syntaxe skriptu

• '> Error (I/O)'
  chyba vznikla při čtení ze vstupu / zápise do výstupu (cyklus, export dat a pod.)

• '> Error (SECURITY)'
  uživatel se pokusil o operaci, ke které nemá právo

• '> Error (RUNTIME)'
  Chyby přímo související s během skriptu (nesprávné přiřazení proměnných...)

• '> Error '
  ostatní chyby, které se nevešly do předchozích kategorií

• '> Warning '
  varování, které nemá za důsledek přerušení skriptu.

Procedury, funkce

zatím nejsou...

Výzazy

Výzazy se mohou vyskytnout:

• při přiřazení na pravé straně operátoru '='

• v příkazu

print , println

• v podmínce (pouze logický výraz)

• v SQL příkazu; zde ale musí být uzavřeny mezi ${ výraz } - $ na začátku označuje, že jde o výraz který má být vyhodnocen, za ním musí následovat otvírací složená závorka a výraz končí uzavírací složenou závorkou.
  V SQL příkazech jsou výrazy a proměnné nahrazeny jejich hodnotami a pak předány databázi ke zpracování.
  NEJSOU vyhodnoceny texty u unozovkách - ty jsou ponechány beze změny (včetně uvozovek).
  Texty v apostrofech JSOU vyhodnoceny a výrazy / proměnné v apostrofech jsou nahrazeny hodnotami.
  Pokud je nutné aby text obsahova $, lze jej zdvojit. Dvojice $$ je nahrazena jedním znakem $ a následující text NENÍ považován za proměnnou.
  Pokud nelze výraz vyhodnotit nebo pokud text za $ není proměnná, je text ponechán beze změny tak, jak je zadán.

• v příkazu echo - platí sejné podmínky jako pro SQL příkaz

Je několik typů výrazů - podle typu hodnoty, kterou vrací:

logický výraz

• výsledkem je logická hodnota (nabývá hodnot false nebo true)

• operátor musí být některý z logických operátorů (viz popis operátorů)

• operandy musí být typu podle použitého operátoru

• lze jej použít při vyhodnocování podmínek (if , while), ale i mimo podmínky

numerický výraz :

• výsledkem je numerická hodnota

• operátor musí být některý z operátorů pro numerické výrazy

• oba jeho operandy tohoto výrazu musí mít numerické hodnoty nebo numerické výrazy

textový výraz :

• výsledkem je textová hodnota

• operátor musí být některý z operátorů pro textové výrazy

• nejméně jeden operand je má textovou hodnotu nebo je to textový výraz

• v textových výrazech jsou zpracovávány dvojice znaků \t, \n, \r a nakrazeny hodnotami (tabelátor, konec řádku, návrat vozíku) a \uNNNN (kde NNNN je hexadecimální číslo) je nahrazen UNICODE znakem s touto hodnotou.

Příklad:

Matematické, logické a textové funkce

Ve výrazech lze použít tyto funkce:

Matematické - jejich parametry jsou numerické a vracejí (převážně) numerickou hodnotu.

textové funkce

Ostatí funkce

Operátory

Speciální jména

Systém má několik speciálních proměnných, ve kterých jsou uloženy indormace o aktuálním stavu systému, výsledky operací, počty záznamů a pod. Jsou pouze pro čtení - jejich hodnoty nastavuje systém a nelze je měnit. Jinak je lze použít jako normální proměnné.
Všechny vnitřní proměnné nemusí existovat vždy - např. $rowcount vznikne až po provedení prvního SQL příkazu a hodnota platí do dalšího SQL příkazu;

*         Tyto proměnné NEZAČÍNAJÍ znakem '$'
**       platí pouze pokud použitý interface podporuje ukládání SQL příkazu. Pokud interface
           podporuje také editaci resultsetu (např. grafické MSQL), bude použit výsledek ve stavu
           ve kterém je v okamžiku volání tohoto příkazu včetně uživatelem změněných hodnot.

***    pokud byl nastaven formát některám z příkazů in.format.plain, in.format.fixed nebo in.style.

Inicializace systému

Při staru každého interface je nejprve načten a interpretován soubor s konfigurací. Podle toho, který interface je použit, načítají se inicializační informace z různých konfiguračních souborů (viz následující tabulka):

** inicializační soubor lze nastavit v konfiguraci serveru

Struktura všech těchto souborů je stejná a je popsána dále. Všechny cesty k souborům a adresářům mohou být napsány s "unix" tvaru (oddělovač '/') nebo "windows" (odělovač '\'; pokud je použit v textové proměnné, musí být zdvojen: " .. \\ .." ). V konfiguračních souborech lze použít nekolik proměnných:

Proměnná ${basePath}

Další proměnné: (některé platí pouze s určitýni interface - je to u nich uvedeno).

Příklad inicializačního souboru:

Příkaz " scripts.path=..." nastaví adresáře, ve kterých se budou hledat skripty.

Příkaz " scripts.path.onlyAllowed=true" zaká že spouštět skripty mimo tyto adresáře

Příkaz " scripts.load=" načte dva skripty. První z bude v systému známý pod jménem "muj " (t. j. pokud napíšu příkaz "@muj", spustí se tento skript), druhý bude mít jméno "pokusnySkript " (ten by se normálně nedal vůbec spustit protože neleží na povolené cestě).

Příkazy

příkazy určují, co má MSQL dělat. Aby měl skript smysl, musí obsahovat alespoň jeden příkaz.

Popis příkazů

foreach

cyklus pro všechny řádky resultsetu, souboru, URL nebo stringu který je považován za resultset.

syntaxe:
foreach <$lokální_jméno | record> in <$ jméno_resultsetu | memory | jméno_souboru_na_disku | URL | jméno_proměnné | ${ výraz }> příkaz...;

Pokud je jako zdroj dat použit přímo název textové proměnné, bude MSQL tuto proměnnou považovat pžímo za zdroj dat a z ní bude data načítat.
Pokud mají být data načítána ze souboru nebo URL a jeho název je nutné získat vyhodnocením výrazu, lze to provést dvěma způsoby:

• pokud může výraz zažínat konstantním stringem, lze psáz : “konstantní_část_1” + $proměnná_1 + “konstantní_část_2” ...
  tento zápis dovoluje pouze složení konstant a proměnných, ne však použití funkcí...

• nebo musí být výraz uzavřen mezi ${ ... }; zde lze použít cokoli.
  
  
  

Pokud je nutné použít pro jako zdroj dat cyklus výsledek výrazu, je nutné tento výraz nejprve uložit do proměnné a tu poak použít jako zdroj dat.

příklad 1:
Vytvoří resultset jménem $locVar výběrem z tabulky, následující cyklus vypíše hodnoty ze sloupců NAME a VALUE pro všechny řádky tohoto resultsetu.

SAVE ID, NAME, VALUE INTO $locVar FROM MY_TABLE;
foreach $radek in $locVar {
    echo Jméno je '$radek.NAME', hodnota je '$radek.VALUE';
}

příklad 2:
Jako v předchozím příkladě, ale vypíše pouze ty řádky, jejichž ID > 10 (funkce num() je použita proto, že všechny hodnoty resultsetu jsou typu text)

SAVE ID, NAME, VALUE INTO $locVar FROM MY_TABLE;
foreach $radek in $locVar {
    if (num($radek.ID) > 10)
    echo Jméno je '$radek.NAME', hodnota je '$radek.VALUE';
}

příklad 3:
jako název zdroje dat je použita textová proměnná “$vysledekSQL”, ve které je uloženo jméno souboru s daty;
tento soubor bude načten a bude zobrazen první sloupec dat. Pokud by $vysledekSQL nebyl mezi ${ a }, načítaly by se data přímo
z této proměnné; nikoli ze souboru jehož jméno je v proměnné uloženo.

foreach $promCyklu in ${$vysledekSQL}
    echo první sloupec vysledku SQL je $promCyklu.col1;

příklad 4:

foreach record in memory
    echo první sloupec výsledku SQL uloženém v globální promìnné je $col1.;

příklad 5:

// nejprve vytvorim textovou promennou jako “virtualni” tabulku o 3 sloupcich a 4 radcich
$promenna =
“Row1_Col1,Row1_Col2,Row1_Col3\n” +
“Row2_Col1,Row2_Col2,Row2_Col3\n” +
“Row3_Col1,Row3_Col2,Row3_Col3\n” +
“Row4_Col1,Row4_Col2,Row4_Col3”;
// a pak zobrazim jeji radky
$cnt = 0;
foreach record in $promenna
    echo Data řádku ${$cnt++} tabulky jsou: $data;

Poznámka:
foreach lze použít k procházení resultsetů, textových souborů v CSV formátu, i textových souborů s pevnou délkou věty (po nastavení formátu věty příkazem in.format )

if ( ... ) else ...;

Podmínka. Text v závorkách za if se vyhodnotí jako logický výraz (jeho výsledkem musí být false nebo true)

syntaxe:
if (logický_výraz) příkaz_při_spnění_podmínky [ else [if (logický_výraz) příkaz [ else [ if ]... ] ] příkaz_při_nespnění_podmínky ] ;

 příklad:

$a = 10;
if ($a == 10)
    println("proměnná $a má hodnotu 10");
else if($a > 11)
    println("proměnná $a je větší než 11");
else
    println("proměnná $a není 10 a je menší než 11");

Poznámka:

echo

vypíše textovou zprávu do výstupu (u MSQLc je to obrazovka, u MSQL výstupní - dolní - okno). Text je "vyčištěn" o netisknutelné znaky (mezery, tanelátory, konce ří¨ásku ...), které nejsou uzavřeny v apostrofech nebo uvozovkách. Za proměnné jsou dosazeny jejich hodnoty, výrazy mezi ${ ... } jsou vyhodnoceny.

Pokud je celý text uzavřen v uvorovkách, netisknutelné znaky nejsou odstraněny a proměnné a výrazy nejsou vyhodnocovány.

syntaxe:
echo ["] text pro zobrazení ... [$ proměnná] ... text ... [${výraz}] ... ["]

Poznámka:

příkaz echo vyhodnocuje prom ěnné a výrazy stejně, jak by byly vyhodnoceny v SQL příkazu. Proto je příkaz echo vhodný např. pro ladění SQL příkazů např. unvitř cyklů foreach , while ...

print, println

vypíší obsah proměnné nebo výsledek výrazu do výstupu. println přidá navíc na konec znak nového řádku.

syntaxe:
print (< proměnná | výraz | $resultset | memory>)
println (< proměnná výraz | $resultset | memory>)

příklad:

Poznámka:

Load ... into
Load ... into ... sync by ( .... )

načte data z externího zdroje (soubor, URL), resultsetu nebo stringu do databáze. Data mohou být v libovolném formátu (formát s oddělovači, formát s pevnou délkou, binární formát), sloupce nebo řádky mohou být odděleny libovolným textem, data mohou být být kódována v libovolné znakové sadě...
Formát dat a znaková sada se nastavuje PŘED voláním tohoto příkazu. Formát dat se nastaví příkazem in.format (pro formát s oddělovači), in.format.fixed (pro formát s pevnou délkou věty) nebo in.format.plain (pro binární formát).
Znaková sada vstupních dat (kódování) se nastaví příkazem in.convertor .

Varianta se “sync by ( ... )” synchronizuje data v databázu s načítanými daty tak, že se pokusí nejprve provést update načítaných dat podle klíčů a pokud neuspěje, vloží nový záznam.

soivisející:

in.format , in.format.plain , in.convertor , save , append

syntaxe:
load < * | (seznam_sloupců ) > from < $resultset | memory | jméno_souboru | URL > into jméno_tabulky [ sync by ( seznam_klicu ) [ noinsert ] ]

load < (seznam_sloupců ) > from < $resultset | memory | jméno_souboru | URL > INTO jméno_tabulky AS SELECT slq_příkaz_SELECT, $data

Typ dat a názvy jednotlivých sloupců importovaných dat (t.j. to, jestli text bude dáván při vytvoření SQL příkazu do apostrofů nebo ne) je dán:

• záhlavprvním datového zdroje (pokud v něm jsou datové typy a / nebo názvy uloženy)

• prvním řádkem importovaných dat

• přímo určen v příkaze LOAD (jméno každého sloupce může být ukončeno typovým označením”:TXT”, “:NUM”, které určuje jak má být s daty v tomto sloupci
  naloženo

• může být pro jednotlivé sloupce explicitně určen příkazem in.style.

Pokud je styl nastaven několika způsoby současně, platí podle tohoto pořadí (nižší číslo = vyšší priorita):

1. hodnoty přímo uvedené v příkaze load

2. hodnoty nastavené příkazem in.sytle

3. hodnoty ze záhlaví zdroje dat

Pokud je použit pžíkaz v kombinaci se selectem ( ... AS SELECT ... ), je pro každý vkládaný řádek nejprve proveden příkaz SELECT tak, jak je zadáno, přičemž $data a $col1 .. $colN je nahrazeno hodotami pro aktuální řádek (načtenými ze vstupního zdroje a zformátovanými podle výše uvedených pravidel).
Sezna importovaných sloupců ( seznam_sloupců ) musí v tomto případě obsahovat jak slouce použité v příkaz SELECT, tak sloupce obsažené ve vstupních datech

 
Příklad 1:

// nacte data ze souboru do tabulky “MYTABLE”
load (ID, JMENO, PRIJMENI, DAT_NAR) from c:\data\mytable.dat into MYTABLE

Příklad 2:

// nacte data ze souboru do tabulky “MATABLE”; soubor musí obsahovat záhlaví
// se seznamem sloupců (byl vytvořen např. příkazen “save”)
load * from c:\data\mytable.dat into MYTABLE

Příklad 3:

// nacte data ze souboru do tabulky “MYTABLE”, procemz vygeneruje ID jako nejvyssi
// hodnotu z tabulky zvetsenou o 1. Predpokladam ze soubor “ c:\data\mytable.dat ”
// obsahuje data pro sloupce “JMENO”, “PRIJMENI” a “DAT_NAR” (NEobsahuje “ID”).
load (ID, JMENO, PRIJMENI, DAT_NAR) from c:\data\mytable.dat
into MYTABL AS SELECT MAX(ID)+1 AS ID, $data FROM MYTABLE;

sync ... by (...) into ...

Synchronizuje SQL data (data v SQL tabulce) s vnějším zdrojem (soubor, URL, resultset ..).
Provedení příkazu je obdobné jako provedení příkazu load.

syntaxe:
sync < * | (seznam_sloupců ) > by ( seznam_klíčů ) from < $resultset | memory | jméno_souboru > INTO jméno_tabulky

sync (seznam_sloupců ) by ( seznam_klíčů ) from < $resultset | memory | jméno_souboru > INTO jméno_tabulky AS SELECT slq_příkaz_SELECT, $data

Příkaz synchronizuje data v SQL tabulce s vnějším zdrojem tak, že se nejprve pokusí provést update dat podle klíčů zadaných v sekci seznam_klíčů a pokud tento update není úspěšný, pokusí se data do tabulky vložit

Ostatní chování příkazu a popis parametrů jsou shodné s příkazem load .

Příklad:

// synchronizuje data v tabulce “MYTABLE” se souborem
sync (ID, JMENO, PRIJMENI, DAT_NAR) by(id) from c:\data\mytable.dat into MYTABLE

poznámka:
Příkaz NIKDY NEMAŽE ŽÁDNÁ DATA. Pokud je potřeba po synchronizaci vymazat nebo změnit (např. nastavit příznak “neaktivní”) data, která ve vnějším zdroji nebyla, je možno vytvořit v tabulce sloupec, do kterého se vloží např. aktuální čas nebo jiný jednoznačný údaj, který se nevyskytuje v řádcích které nebyly importována; po synchronizaci se vymažou / nastaví ty řádky, které mají tento údaj odlišný od importovaného. Např:

sync (ID, JMENO, PRIJMENI, DAT_NAR, SYNC_COL:${1}) by(id) from c:\data\mytable.dat into MYTABLE;
update MYTABLE set IS_ACTIVE='N', SYNC_COL=0 WHERE SYNC_COL=1;

save ... into

Provede SQL příkaz a (SQL dotaz nebo volání procedury) jeho výsledek uloží do zadaného objekto - podle varianty příkazu to může být do:

- proměnné (resultsetu)
- souboru s daným formátem (s pevnou délkou, oddělovači ...) - viz out.format.fixed , out.format.default , out.format.static .
- URL (WWW stánka ...)
- SQL tabulka (v aktuální nebo jiné databázi – DSN); ta může být vytvořena pokud neexistuje nebo vymazána pokud existuje

Příkaz save vždy vyčistí resultset, do kterého bude ukládat data. Pokud resultset zadaného jména neexistuje, bude vytvořen. Pokud existuje, bude vyprázdněn. Příkaz má tři varianty které se liší tím, co a jakám způsobem ukládá.
Při ukládání do souboru nebo URL lze před provedením příkazu nastavit kódovou stránku ve které bude výsledek uložen příkazem „out.convertor a formát výstupních dat příkazem out.format.

Varianta 1: provede SQL příkaz a výsledek uloží do souboru, URL nebo do resultsetu

Syntaxe 1:  (příkaz SELECT)
save [ DISTINCT ] seznam_sloupců into výstup FROM jméno_tabulky ... dále_pokračuje_SQL_příkaz [ header | noheader ]

Syntaxe 2: (volání stored procedury)
save  result  into < output | memory | $resultset |  jméno_souboru >  volání_ SQL_stored_ precedury  [ parametry_procedury ]  [ header | noheader ]

přičemž výstup je určuje, kam bude uložen výsledek SQL příkazu:

Ostatní parametry mají význam:

příklad:

save (ID, JMENO, PRIJMENI, DAT_NAR) into $clovekInfo FROM CLOVEK_DATA WHERE PRIJMENI LIKE 'Novák%'
save result into ~/vysledekProcedury.txt call mojeProcedura ;

Varianta 2: uloží obsah resultsetu nebo výstupního okna do textového souboru. V případě resultsetu bude soubor mít CSV formát, texty budou v apostrofech.

syntaxe:
save < $resultset | memory | output > into < jméno_souboru >

příklad:

save $clovekInfo into c:\data\clovekInfo.txt

Varianta 3: uloží jeden řádek (konstantní hodnotu) do resultsetu. Text (proměnné, výrazy a speciální znaky) je před vložením zpracován jako v příkaze echo. Vkládaný řádek je vyčištěn od všech mezer, které nejsou uvnitř apostrofů nebo uvozovek.

syntaxe:
save ["] text pro zobrazení ... [$proměnná ] ... text ... [${výraz}] ... ["] into < $resultset >

příklad:

save 10, 'Novák', 'František', '21.11.1973' into $clovekInfo

Poznámka:

append ... into

stejná syntaxe, varianty i zpracování jako příkaz save s tím zozdílem, že pokud resultset nebo soubor již existuje, není přepsán ale je doplněn o vkládané záznamy.

Při vkládání do resultsetu nebo do souboru, který bude později jako resultset zpracováván, musí mít vkládané záznamy stejnou strukturu jako ty záznamy, které již v resultsetu / souboru jsou (jinak by při jeho dalším zpracování vznikla chyba). V principu lze ale přidat cokoli.

Příkaz append implicitně nevkládá záhlaví s informacemi o sloupcích, to však lze změnit pro každý jednotlivý příkaz pomocí direktivy "header" na konci příkazu.

break

ukončí provádění cyklu

syntaxe:
berak

exit

ukončí provádění celého skriptu (programu) i všech, ze kterých byl spuštěn.

syntaxe:
exit [návratová_hodnota ]
exit ( návratová_hodnota )

return

ukončí provádění vnořenho (vyvolaného) skriptu nebo procedury a vrátí řízení do místa, odkud byla procedura nebo skript zavolána. Může předat hodnotu, která bude vrácena volajícímu.

syntaxe:
return [návratová_hodnota]
return ( návratová_hodnota )

messages

zapne / vypne vypisování zpráv bo výst. okna

syntaxe:
messages <on | off | off all | sql | final >

Poznámka:

Tento příkaz neovlivní vypisování chybových zpráv. To lze učinit příkazem " sql.error.display" (chyby syntaxe skriptů jsou vypisovány vždy a nelze je zakázat).

in

Skupina příkazů pro nastavení parametrů vstupů (použijí se při příkazech load, foreach, sync).
Většina těchto příkazů platí pro jeden (první následující) příkaz load nebo foreach, který následuje po jejich volání. Po provedení příkazu jsou nastavení vynulována (nebo nastavena na default hodnoty). Pokud je potřena použít stejná nastavení pro váce vstupů, je nutné volat příkazy před každám vstupem znovu (např. při vnořených cyklech „foreach“, pokud je ve vnitřním cyklu použit některý z těchto příkazů).

in.convertor

nastaví konvertor, kterým budou konvertová na data při importu z disku (příkaz load , foreach).

související:

in.convertor.default , in.convertor.static , out.convertor

syntaxe:
in.convertor(< jménoKonvertoru > ). Popis viz out.convertor

in.convertor.default

viz out.convertor.default – ale platí pro vstup

in.convertor.static

viz out.convertor.static – ale platí pro vstup

in.style

nastaví styl sloupců pro následující import příkazem load . Nastavení stylu lze použít pouze po předchozím nastavení formátu příkazem in.format . Syntaxe a vlastnosti příkazu jsou stejné jako při nastavení stylu výstupu - viz out.style .

in.counter

nastaví výchozí hodnotu pro počítání záznamů. Po volání tohoto příkazu bude directiva ":COUNTER" v nastavení formátu nebo systémoová proměnná $rownum při příkazech load , forech ... vracet aktuální číslo záznamu zvětšené o tuto hodnotu.
Po provedení kteréhokoli I / O příkazu ( load , save , append , foreach ) je tato hodnota vynulována.

syntaxe:
in.counter(výchozí_hodnota)

in.format

nastaví formát dat pro následující import pro vstupní soubor typu CSV. Popis viz out.format .
Vstupní soubor předpokládá jako textový soubor s oddělovači.

in.format.fixed

Nastavení formátu vstupních dat pro následující import ze souboru s pevnou délkou věty. Tento formát bude použit při následujícím příkaze load ... Předpokládá se, že data budou čtena z textového souboru s pevnou délkou věty a každý záznam bude na samostatném řádku ukončeném znakem CR, LF nebo dvojicí CR - LF,

Formát může ukazovat na absolutní pozice na řádku souboru, nebo může být nastaven přírůstkově (vždy počet znaků od předchozího konce) - viz syntaxe.

související:
in.format.plain , out.format , in.convertor

syntaxe:
in.format(formátovací_string [, první_záznam[, počet_záznamů]]);

formátovací_string je string (textová proměnná nebo text v uvozovkách / apostrofech) popisující formát importovaného souboru. Skládá se z popisu jednotlivých sloupců (tokenů):

token [ ; token [ ; token [ ... ] ] ]

POZOR !!! Oddělovačem tokenů ve formátovacím stringu je STŘEDNÍK !!!

kde token je část dat z právě importovaného řádku souboru, má hodnotu zadaného typu která vzniklne zpracováním znaků od začátku tokenu (od jeho první pozice) do konce tokenu (podle jeho definice).
Token může mít některý z následujících tvarů:

jménoSloupce

pokud je zadáno, bude sloupce vystupovat pod tímto jménem (i v případě, že v datovém zdrojï jsou obsaženy i názvy sloupců).

TYP_DAT v předchozí tabulce může být

** Tyto formáty jsou k dispozici pouze u příkazu in.format.fixed

příklad 1:

in.format.fixed("1-5:TXT;6-8:NUM,9-10:NUM;COUNTER;45-*:EXPR(substring($_token, 1, 10))");

příklad 2:
Nastaví stejný formát jako příklad 1 ale jiným způsobem.

in.format.fixed ("1-5:TXT;4:NUM;2:NUM,COUNTER;*:EXPR(substring($_token, 1, 10))");

Poznámka:
POZOR !!! Oddělovačem tokenů ve formátovacím stringu je STŘEDNÍK !!!
Nastavení formátu se RUŠÍ po provede ní příkazu load .. - t.j. pokud potřebuji importovat více souborů se stejným formátem, musím příkaz in.format použít před každým importem znovu.

in.format.plain

Roršířené nastavení vstupního formátu pro import. Nastaví formát vstupních dat pro následující import příkazem load (podobně jako in.format..). S pomocí tohoto příkazu lze importovat libovolné soubory se známou strukturou a pevnou délkou záznamu - včetně binárních (např. DBF ... - i když na DBF je lepší nástroj).
Takto nastavený formát bude použit při následujícím příkazu load a pak bude formát zrušen (stejně jako u in.format ).

související:
in.format , in.format.fixed , out.format , in.convertor

syntaxe:
in.format.plain(formátovací_string, délka_záznamu [, pozice_od [, počet_záznamů]]);

příklad:

in.format.plain("1-5:TXT,6-8:NUM,9-10:NUM,COUNTER,45-*:EXPR($_token.substring(1, 10))", 64, 650, 10);

Poznámka:
Nastavení formátu se RUŠÍ po provedení příkazu load .. - t.j. pokud potřebuji importovat více souborů se stejným formátem, musím příkaz in.format.plain použít před kažbým importem znovu.

in.null

nastaví hodnotu pro sloupce, jejichž hodnota při načítáni by byla NULL. Tato (nastavená) hodnota bude vracena místo NULL.

syntaxe:
in.null ( text_pro_NULL )

Varianty:

• in.null.default,
  nastaví null hodnotu pro všechny vstupy od místa volání do konce skriptu.

• in.null.static
  nastaví null hodnotu pro všechny vstupy od místa volání do konce skriptu a pro nově vzniklé instance interpreteru

in.skip

nastaví počet ŘÁDKŮ (záznamů), které budou přeskočeny na začátku importu.

Řádky jsou nejprve načteny s pomocí nastaveného formátování, formátu stránky atd .... Kompletně připravené řádky, které by byly již byly zpracovány jako SQL příkaz, jsou pak teprve přeskočeny.

syntaxe:
in.skip ( pocet_řádků )

in.condition

nastaví podmínku, která bude vyhodnocena pro každý řádek načtených dat . Pokud bude výsledek podmínky „true“, budou data použita. Pokud bude výsledek „false“, bude řádek ignorován (přeskočen).

Podmínka je vyhodnocena těsně před zformulováním SQL příkazu (až po případném přeskočení řádků nastavených pomocí in.skip(...) ),

V podmínce jsou k dispozici hodnoty sloupců z právě načítaného řádku jako proměnné, které NEZAČÍNAJÍ !!! znakem „$“ a všechny ostatní proměnné a funkce MSQL tak, jak jsou nastaveny v okamžuku vyhodnocení podmínky (zdroj dat musí obsahovat názvy sloupců, nebo musí být názvy sloupců zadány např. jako součíst formátu nebo příkazem „“).

syntaxe:
in.condition ( textový_výraz_s_podmínkou_pro_filtr_dat )

příklad:

provede update sloupce „DDP“ v tabulce „HVLP_C“ podle dat ze souboru „Q:/data/Aislp/latin/KL.DAT“, pokud hodnota sloupce „DDP“ v načítaných datech není NULL (t.j. pokud sloupec „DDP“ má hodnotu).
Soubor KL.DAT je binární soubor s pevnou délkou věty; formát dat v tomto souboru je popsán řádkem „in.format.plain(...)“.

in.format.plain("1-5:KOD:TXT;31:NAZEV:TXT;113-120:DDP:NUM", 177, 177);

in.condition("DDP <> NULL");

load (DDP, KOD) FROM "Q:/data/Aislp/latin/KL.DAT" INTO HVLP_C SYNC BY (KOD) NOINSERT;

in.style

nastaví styl (a případně názvy) sloupců ve vstupních datech. Příkaz lze použít

• pro změnu datových typů nebo názvů sloupců na jiné, než jaké jsou v datovém zdroji

• pro zadání datových typů a názvů sloupců, pokud v datovém zdroji nejsou uvedeny

syntaxe:
in.style ( formátovací_string )

formátovací_string představuje textový výraz s popisem stylů a názvů. Má tvar:

kde TYP_DAT je stejný jako typ dat u příkazu in.format.fixed. a jménoSloupce (pokud je uvedeno) udává jméno, pod kterým bude sloupec vystupovat v načítaných datech (a to i v pžípadě, že jména sloupců jsou ve vstupních datech uvedena)

(viz formátovací string u příkazu „in.format.fixed“).

sql

skupina příkazů nastavuje podmínky, za kterých se budou provádět SQL příkazy

sql.error , sql.error.exit , sql.error.display , sql.error.max , sql.isError , sql.setError , sql_timeout , sql.rows.max ,  sql.select , sql.execute, sql.getString, sql.getRow

sql.error

zakáže / povolí ukončení provádění skriptu po chybě a zároveň vypisování chybových zpráv při zpracování SQL příkazu. Tento příkaz je kombinace volání sql_error_exit (...) a sql.error.display (...).

syntaxe:
sql.error (< false | true > )

sql.error.exit

zakáže / povolí ukončení provádění skriptu po chybě při zpracování SQL příkazu. Defaulně je nastaveno na true (=>skript končí po SQL chybě).

syntaxe:
sql.error.exit (< false | true > )

Poznámka:
Příkaz sql.error.exit vynuluje příznak SQL chyby. Pokud je potřeba zachovat informaci o tom, že v části skriptu ve které bylo zakázáíno ukončení po SQL chybě tato chyba nastala, je nutné použít pomocnou proměnnou do které se stav příznaku uloží ještě před voláním příkazu sql.error.exit ; např. takto:

$stavChyby = sql.isError ;
....
sql.setError($stavChyby);

sql.error.display

zakáže / povolí vypisování chybových zpráv zzniklých přu zpracování SQL příkazů. Text těchto chybových zpráv vytváří databázový stroj, který příkaz zpracovává. Proto tyto zprávy nejsou jednotné.
Default hodnota je true (vypisování zpráv je povoleno).

syntaxe:
sql.error.display ( < false | true > )

Poznámka:

sql.error.max

Nastaví maximální počet SQL chyb, které ještě program ignoruje při importech (příkazem load ). Po překročení tohoto počtu chyb import zkončí.

syntaxe:
sql.error.max ( číslo )

Default hodnota: 0 (=> import končí po první SQL chybě)

Poznámka:
Hodnota je po každém provedeném importu příkazem load znovu nastavena na nulu.

sql.isError                                                                                                                

vrátí stav příznaku SQL chyby jako logickou hodnotu.

syntaxe:
sql.isError

sql.setError

nastaví příznak SQL chyby. Systém se bude chovat, jakoby nastala SQL chyba (kromě případného ukončení skriptu; běžící skript se voláním příkazu sql.setError neukončí)

syntaxe:
sql.setError ( < false | true > )

sql.timeout

nastaví tomeout, po kterém bude ukončen SQL příkaz, pokud do zadaného času nezkončil sám

syntaxe:
sql.timeout ( doba_v_sekundách )

Default hodnota: 60 sec

Poznámka:
Tento parametr funguje jenom s některými databázemi (příkaz je odeslán před zpracováním SQL příkazu databázi, nekteré databáze jej však ignorují - nutno vyzkoušet).

sql.rows.max

Nastaví maximílní počet vracených záznamů na hodnotu.

syntaxe:
sql.rows.max ( hodnota )

sql.select

Provede SQL příkaz SELECT podle parametru v vrátí první sloupec prvního řádku jako textovou proměnnou.

syntaxe:
sql.select ( příkaz_select_bez_klíčového_slova_SELECT [ , DSN_pro_příkaz] )
Pokud je " DSN_pro_příkaz" zadáno, bude použito tot DSN (pokud existuje) bez ohledu na aktuální DSN

sql.execute

provede SQL příkaz (jakýkoli příkaz včetně volání stored procedur) a vrátí resultset s výsledkem jako proměnnou.

syntaxe:
sql.execute( SQL_příkaz [ , DSN_pro_příkaz ] )
Pokud je " DSN_pro_příkaz" zadáno, bude použito tot DSN (pokud existuje) bez ohledu na aktuální DSN

poznámka:
tento příkaz nikdy nevrací chybu. Pokud nemůže být SQL příkaz zpracován nebo vrácen výsledek, je výsledkem tohoto příkazu prázdný resultset. Stav chyby lze zjistit pomocí proměnné $sqlResult nebo funkce sql.isError .

sql.getRow

Provede SQL příkaz podle prvního parametru v vrátí první řádek výsledku tohoto SQL příkazu jako resultset o jednom sloupci (provede jakoby "transpozici" prvního řádku výsledku do jednoho sloupce resultsetu). Všechny proměnné vraceného resultsetu budou typu text BEZ apostrofů.

poznámka:
tento příkaz nikdy nevrací chybu. Pokud nemůže být SQL příkaz zpracován nebo vrácen výsledek, je výsledkem tohoto příkazu prázdný resultset. Stav chyby lze zjistit pomocí proměnné $_sqlResult nebo funkce sql.isError .

syntaxe:
sql.getRow( příkaz_SQL_vracelící_resultset [ , DSN_pro_příkaz] )
Pokud je " DSN_pro_příkaz" zadáno, bude použito tot DSN (pokud existuje) bez ohledu na aktuální DSN

sql.getString

Provede SQL příkaz podle parametru v vrátí první položku výsledku (první sloupec prvního řádku) jako textovou proměnnou.

syntaxe:
sql.getString( příkaz_select_bez_klíčového_slova_SELECT [ , DSN_pro_příkaz] )
Pokud je " DSN_pro_příkaz" zadáno, bude použito tot DSN (pokud existuje) bez ohledu na aktuální DSN

poznámka:
tento příkaz nikdy nevrací chybu. Pokud nemůže být SQL příkaz zpracován nebo vrácen výsledek, je výsledkem tohoto příkazu prázdný string. Stav chyby lze zjistit pomocí proměnné $_sqlResult nebo funkce sql.isError .

dsn

Skupina příkazů pro práci s datovými zdroji.

dsn.select

nastaví DSN zadaného jména pro další práci s daty.
Od tohoto místa v programu až do další změny DSN (dalšího volání dsn.select ( ... ) ) budou SQL příkazy zasílány ke zpracování databázi, která je pod tímto DSN zaregistrována. Příkaz má dvě varianty:

Pokud je použit druhý parametr (false / true), nenastavuje se DSN ue seznamu dostupných DSN, ale přímo z ODBC (pouze pro Windows nebo ty systémy, kde existuje ODBC)

Varianta 1:

nastaví DSN ze seznamu DSN zaregistrovaných v aktuální DSN (t.j. té, která je aktivní v okamžiku startu systému - proti které se také ověřují data uživatele; aktuální DSN může být změněna příkazem dsn.load )

syntaxe:
dsn.select (<jméno_DSN | $default > [, < false | true > ] )

Varianta 2:

nastaví DSN přímo ze seznamu ODBC zdrojů (t. j. tato DSN nemusí být registrována v databázích aktuální DSN). Druhý parametr (false nebo true) určuje, jestli se bude k databázi přistupovat přímo na stanici klienta nebo přes server (v tomto případě musí tato databáze být registrována v ODBC zdrojích serveru, ke kterému se klient připojuje.)

syntaxe:
dsn.select (jméno_ODBC, < false | true > )

příklad:

viz příklad k příkazu dsn.load

Poznámka:

dsn.close

uzavře spojení s databází; v případě některých ODBC databází (EXCEL, ACCESS, FOXPRO, DBF...) je tím uvolní pro používání jinými programy.

syntaxe:
dsn.close

Poznámka:

Příkaz lze použít pouze pro databáze, ke kterým se pripojoje klientská stanice přímo (v definici DSN mají nastaveno "Direct connection" na "Yes") nebo to jsou přímo připojené ODBC zdroje (nastaveny příkazem dsn.select (jmeno_DSN, true) ; )

dsn.load

nastaví zadanou DSN jako aktuální.
Všechna další jména datových zdrojů (DSN) (a tedy všechny informace potřebné pro přihlašování k databázím - jména, hesla, URL a typy databází ...) budou brána z této (nově nastavené) DSN

syntaxe:
dsn.load (jméno_DSN | $default)

Příklad:

Předpokládejme že systém byl spuštěn s aktuální DSN s názvem DSN1, které ukazuje na databázi v ACCESSU (připojenou přes ODBC). Je to systémová databáze a jsou v ní dále zaregistrovány DSN DATAB1 (ukazuje na databázi v postgresu) a DATAB2 (ukazuje na databázi v SYBASE11).
Databáze DATAB2 je rovněž systémová (=> obsahuje systémové tabulky se seznamem dalších DSN, uživatelů ... a proto ji lze použít v příkaze dsn.load) a obsahuje tyto DSN: MYDATA (soubor c:\data\mydata.mdb - typ ACCESS přes ODBC) a SYBDATA (sybase).

Po startu systému budou dostupné databáze zaregistované v DSN1, tedy samotná DSN1, dále DATAB1 a DATAB2. Budu moci provést např.

// vybere DSN "DATAB1" pro dalsi praci
    dsn.select(DATAB1);
// dale vlozi jeden radek do tabulky "TABULKA_Z_DATAB1" (tato tabulka musi existovat v
// databázi, která je pod jmenem "DATAB1" definována - zde je to postgres)
    INSERT INTO TABULKA_Z_DATAB1 (SLOUPEC1, SLOUPEC2 ...) VALUES (hodnota1, hodnota2 ...);
// zmenim databazi, kterou budu dale pouzivat pro SQL prikazy na "DATAB2" (sybase)
    dsn.select(DATAB2);
// ulozim neco z teto databaze do rsultsetu ....
    save * into $myRes from TABULKA_Z_DATAB2 ;

Poté provedu příkaz

    dsn.load(DATAB2);

a od tohoto okamžiku již nejsou dostupné databáze registrované v DSN1 (t. j. DSN1, DATAB1 a DATAB2); tedy pokus o některý z příkazů

dsn.select(DATAB1);
    dsn.select(DSN1);

zkončí chybou. Budou ale přístupné databáze registrované pod DATAB2, t. j.

dsn.select(MYDATA);

proběhne správně a od tohoto okamžiku budu moci provádět SQL dotazy dat daty z tabulek v MYDATA (v souboru MSACCESS - t. j. v souboru c:\data\mydata.mdb)

Příkazem

dsn.load($default);

nastavím jako aktuální opět tu DSN, se kterou systém startoval (v tomto příkladě DSN1) a dále budu moci pracovat s daty v databázích DSN1,DATAB1, DATAB2.

Poznámka:

pro změnu aktuální DSN je nutné, by uživatel, který je právě přihlášen, měl účet se stejným heslem v cílové DSN (t.j. té, která má být nastavena). Pokud ne, bude v grafickém interface vyzván k přihlášení, ostatní (commandline, servlet atd) zahlásí chybu.

dsn.params

Nastaví "connected string" (speciální parametry, předávané databázi). Příkaz je nutné volat po změně DSN (voláním dsn.select (), ), pro které tyto parametry mají platit., ale před prvním přístupem k datů pro která má tato nastavení platit.

syntaxe:
dsn.params ( text )

text = text, který bude předán ovladači databáze jako speciální parametr

Poznámka:
speciélní parametry jsou závislé na konkrétní použité databázi. Jestli jsou potřebné a jaké mají názvy a hodnoty je nutné zjistit v dokumentaci k příslušnému ovladači (JDBC driveru), který databáze používá.

dsn.list

Vypíše informace zvoleného druhu o aktuální DSN.

syntaxe:
dsn.list( typ_informace [, katalog ] )
kde typ_informace le některé z těchto klíčových slov (zadává se bez uvozovek nebo apostrofů):

a katalog (volitelně) je textová proměnná nebo výraz, určující katalog ze kterého bude požadovaný výpis proveden. Pokud není zadán, je proveden výpis z aktuálního katalogu (obvykle databýze, která je specifikována v jdbc suffixu) 

out

Skupina příkazů nastaví parametry výstupů (použijí se při příkazech save , append )

out.convertor

nastaví konvertor, kterým budou konvertována data při exportu na disk (příkaz save , append )

související:
out.convertor.default , out.convertor.static , in.convertor

syntaxe:
out.convertor(< jménoKonvertoru > )
kde jménoKonvertoru je některé z následujících (musí být zadáno přesně včetně malých / velkých písmen)

Poznámka:
Konverze vstupních souborů do editoru MSQL by měla probíhat automaticky podle platformy, na které je MSQL spuštěno.

out.convertor.default

Nastaví konvertor, který bude používán pro všechny výstupy (příkazy save , append ) od místa nastavení do konce běhu skriptu. Parametry viz out.convertor .

out.convertor.static

Nastaví konvertor, který bude používán pro všechny výstupy (příkazy save , append ) od místa nastavení do konce běhu skriptu a pro všechny nové instance příkazového interpretu. Lze volat i v instanci vytvořené staticky (mapř. inicializace ..). Parametry a detailní popis viz out.convertor .

out.trim

nastaví informaci o tom, které sloupce SQL dotazu (bezprostředně následujícího po volání této funkce) budou ořezány z obou stran o mezery a netisknutelné znaky (nové řádky, tabelátory ...).

související:
out.trim.default ,

syntaxe:
out.trim (hodnota [, hodnota [, hodnota] ... ] )

Poznámka:
Počet hodnot předávaných příkazu musí být stejný jako bude počet sloupců v následujícím SQL dotaze; jinak nebude toto nastavení použito.

out.trim.default

povolí / vypne čištění záznamů (vracených SQL příkazy) o mezery na začátku a na konci textu (pro všechny typy záznamů - text, numerické ...)

syntaxe:
out.trim.default (< false | true >)

out.style

Nastaví styl sloupců pro následující export příkazem save , append provedeného SQL příkazem.
Styl určuje, jestli bude údaj vkládán jako text (=> bude uvozen uvozovačem textu specifikovaným v nastavení formátu), nebo jako číslo => vždy bez uvození. Nastavení stylu má vyšší prioritu než údaje o typu sloupců z databáze. Příkaz má smysl tam, kde např. datanáze není schopná vrátit informace o typu datových polí (MS SQL při voláná stored procedur a pod.). Počet sloupců v příkaze nesmí být menší než počer sloupců výsledku SQL příkazu, může být větší => zbytek je ignorován. Nastavení stylu sloupců je zrušeno provedením exportu.
Nastavení stylů je zrušeno rovněž nastavením formátu příkazem out.format => nejprve je nutné nastavit formát a potom styly sloupců.

Jiný způsob změny stylu sloupce pro export je přípona :TXT nebo :NUM za jménen sloupce v příkaze save , append .

související:
out.format

syntaxe:
out.style( [styl_sloupce_1 [ , styl_sloupce_2 [ .... , styl_sloupce_n ] ] ] )
kde styl_sloupce_1 až styl_sloupce_n je:

out.format

Nastaví formát exportu pro následující operaci "save" nebo "append". Příkaz má dvě varianty, které určuje první parametr. Pokud je to text v uvozovkách nebo apostrofech, jde o variantu a), pokud je to číslo, jde o variantu b) (viz out.format.fixed ). Nastavením formátu bude zrušeno případné nastaení stylu sloupců (viz out.style )

související:
out.format.fixed , out.format.default , out.format.static , in.format

syntaxe:
out.format([oddělovač] [ , uvoz_txt [ , konec_řádku [, začátek_řádku [, závěr [, úvod [, null_hodnota [ , text_za_položkou [ , text_před_položkou ] ] ] ] ] ] ] ] [, záhlaví_sloupců ])

Nastaví formát s oddělovači popsaný dalšími parametry.

Parametry (kromě posledního - záhlaví_sloupců ) jsou texty uzavřené v uvozovkách nebo apostrofech, řídící znaky (\r, \n, \t, \uxxxx ..) se převádí na hodnoty.

První parametr (oddělovač ) je povinný, ostatní nepovinné. Pokud má mít některý parametr default hodnotu ale následující má být nastaven, na jeho místě parametru s default hodnotou se použije pouze čárka bez textu (pro tento chybějící parametr bude použita jeho default hodnota).

Příklad 1:
nastaví oddělovač na středník, konec řádku na "CR-LF" (pro Windows soubory) a konec textu na ASCII hodnotu 1B (hex). Ostatní bud edefault.

out.format(";", , "\r\n", , "\u001B");

Příklad 2:
nastaví oddělovač na středník, a do záklaví vloží názvy slopců; ostatní bude default

out.format(";", true);

Příklad 3:
nastaví oddělovač na středník, ostatní bude default

out.format(";");

Varianty:

• out.format.default
  Nastaví default formát exportu, který bude používán pro všechny exporty od místa volání do konce skriptu.

• out.format.static
  Nastaví default formát exportu, který bude používán pro všechny exporty do konce skriptu a pro nově vzniklé instance interpreteru. Lze volat i ze statické instance (např. v inicializaci …)

out.format.fixed

Nastaví formát s pevnou délkou věty pro vásledující export. Příkaz out.format.fixed je synonymum pro příkaz out.format , který začíná číslem - varianta b) .

syntaxe:
out.format( dékla_sloupce_1 [ , délka_sloupce_2 [ , délka_sloupce_3 [ ... [ , délka_sloupce_n ] ] ] ] [ , oddělovač [ , výplň_čísel [ , výplň_textu] ] ] )

Nastaví formát s pevnou délkou věty.

Default hodnota:
formát s oddělovači nastavený takto:

• oddělovač

= čárka

• uvoz_txt

= uvozovka,

• konec_řádku

= "\n" (znak LF)

• úvod

a závěr není

• záhlaví_sloupců

se neexportuje

Poznámka:

• Výstupní formát je po provedení příkazu

save nebo append nastaven na defaultní hodnoty. Proto je nutné jej před každou operací, která vyžaduje jiný než defaultní formát, nastavit znovu.

• na místě jednotlivých parametrů (kromě prvního a kromě záhlaví_sloupců - logický) lze použít výrazy, vracející příslušné hodnoty.

out.null

nastaví hodnotu která bude vracena pokud databáze vrátí NULL. (default je „NULL“).

Varianty:

• out.null.default
  nastaví výstupní null hodnotu pro všechny výstupy od místa volání do konce skriptu.

• out.null.static
  nastaví výstupní null hodnotu pro všechny výstupy od místa volání do konce skriptu a pro nově vzniklé instance interpreteru

output

skupina příkazů pro práci s výstupním tokem

output.clear

vyprázdní obsah výstupu (pokud je to možné); komandline varianta vyprázbní vástupní bufffer, grafická varianta vymaže výstupní textové okno ...

syntaxe:
output.clear

output.get

vrátí obsah výstupního bufferu od posledního volání output.clear (pokud je to možné) jako textovou proměnnou;

system

skupina příkazů systémových příkazů (práce se zprávami, práce s hostitelským operačním systémem, generátor číselných řad ...)

system.execute , system.gen , system.priority , system.scriptPath , system.setError , system.isError , system.message , system.runEvent , system.invoke , system.invokeOut , system.edit

system.execute

provede příkaz hostitelského operačního systému a jeho výstup vrátí jako textovou proměnnou.

syntaxe:
system.execute(jméno_příkazu );

system.gen

podskupina příkazů pro práci s generátorem číselných řad.

next vygeneruje další číslo v řadě
    system.gen.next ( tabulka [ , sloupec [ , klíč ] ] )
sync nastaví generáto podle nejvyšší hodnoty v zadané tabulce
    system.gen.sync ( tabulka [ , sloupec [ , klíč ] ] )
set
    system.gen.set ( číslo, tabulka [ , sloupec [ , klíč ] ] )

kde

Poznámka:

generátor číselných řad je určen především pro generování unikátních ID, ale lze jej použít i pro jiné účely (pomocí vhodně zvolených jmen "tabulka", " sloupec", "klíč") - např. čísla výrobků a pod..

Generáto pro úlohy není v aktuální DSN , ale vždy jen jeden - v DSN, která je aktivní v okamžiku přihlášení uživatele. Pokud se úloha při své činnosti přepíná mezi více DSN a v několika z nich je nutné generovat unikátní ID (pro tabulky, ktere mají v různých DSN stejný název), je nutné tyto tabulky rozlišit pomocí třetího parametru ("klíč " ) - jeho hodnota by měla být právě jmého toho DSN, ve kterém tabulka leží.

system.priority

nastaví prioritu threadu.

syntaxe:

system.priority( [ + | - ] priorita)

kde priorita je číslo v rozsahu 1 - 10 určující novou prioritu threadu. Pokud číslu předchází znaménko + nebo -, je nová priorita threadu nastavena jako tento původní a zadaného čísla (výsledek nesmí být mimo meze 0 - 10). Default priorita threadu je 5.

system.scriptPath.add

přidá cesty k cestaám, na kterých se hledají skripty

syntaxe:
scriptpath.add( string_1 [ , string_2 [ , string_3 [ , ... [ , string_n ] ] ] ]

system.scriptPath.set

nastaví sezna cest pro skripty

syntaxe:
scriptpath.set( string_1 [ , string_2 [ , string_3 [ , ... [ , string_n ] ] ] ]

system. setError

nastaví příznak o chybě (ten může otestovat interface, který příkaz vyvolal a podle něj provést / neprovést nějakou akci)

syntaxe:
system.setError ( < false | true >)

system. isError

vrátí stav příznaku chyby jako logickou proměnnou. Ten je nastaven při vzniku chyby nebo voláním funkce system.setError

syntaxe:
system.isError

system.message

příkazy pro odesílání zpráv (smtp - email, SMS, pager ...) a zobrazení zprávy do stavového řádku
Skupiny obsahuje tyto příkazy:

system.message.send

Odešle textovou zprávu zadaného typu

syntaxe:
system.message.send( typ_zprávy, komu_je_určená, krátký_text [ , od_koho [ , dlouhý_text [ , příloha [ , SMTP_server ] ] ] ]

typ_zprávy může být některý z textů: "smtp", "pager", "sms"

pro typ_zprávy = "smtp" => odešle email

pro typ_zprávy = "pager" => odešle zprávu na paget (prostřednictvím WWW rozhraní)

pro typ_zprávy = "sms" => odešle SMS zprávu prostřednictvím WWW rozhraní operátorů.

system.message.setServer

nastaví SMTP server, který bude používán pro další odesílání mailů.
Pokud server není nastaven, MSQL použije default server (podle nastavení v RTsSystem.properties nebo GapoServer.ini)

syntaxe:
system.message.setServer ("server");

system. message.setFrom

nastaví pole "from" pro emaily, které budou dále odesílány.

syntaxe:
system. message.setFrom("odesílatel")

system.message.display

zobrazí zprávu na displeji klienta. U grafického interface se zpráva zobrazí do dolního stavového řádku, u ostatních interface podle situace - obvykle do std. výstupu.

syntaxe:
system. message.display ( text_zprávy [ , počet_sekund_pro_zobrazení ] )

system.message.displayError

tobrazí chybovou zprávu na displeji klienta. Chybová zpráva je barevně odlišená, vše ostatní je stejné jako system.mesage.display .

system.message.alert

Zobrazí zprávu v samostatném okně (pokud to dovoluje použitý interface). V NEgrafických interface se zpráva zobrazí do výstupního toku dat jako normální zpráva.

syntaxe:
system. message.alert ( [ záhlaví , ] text_zprávy [ , typ_zprávy ] )

system.runEvent

vyvolá událost na serveru (události viz popis administrace serveru). Událost musí být definována v seznamu událostí pro aktuálnáí aplikační systém a musí být aktivní.

syntaxe:
system. runEvent (název_události [ , sync_mode ] )

system.invoke, system.invokeOut

vyvolá MSQL skript na serveru a výsledek (pokud vyvolaný skript vrací návratovou hodnotu) vrátí jako textovou proměnnou.
Pokud vyvolaný skript nevrací návratovou hodnotu, příkaz "system.invoke " vrací hodnotu "null".

Příkaz system.invokeOut vypisuje při běhu skriptu na serveru jeho standardní výstup na displeji klienta (lze použít pro zjišťování příčin chyb při ladění); příkaz system.invoke jej nevypisuje.
Obě varianty vypisují zprávy do stavového řádku (nebo jeho ekvivalentu u NEgrafických interface).

syntaxe:
system. invoke(název_skriptu [ , sync_mode ] [ , paramert_1 , parametr_2 [ , ... , parametr_n ] ] )

poznámka:

Příkaz system.invokeOut je určen především k diagnostice problému - ne pro rutinní používání. Pokud by vyvolaný skript  produkoval masívní tisk do standardního výstupu, mohlo by při použití tohoto příkazu dojít k přetečení paměti na serveru (celý standardní výstup skriptu se nejprve zapisuje do paměti a po zkončení skriptu je jako celek odeslán klientovi).

system.exit

Ukončí provádění všech příkazů a (pokud je to možné) ukončí celý systém a vrátí řízení operačnímu systému. Předává případnou návratovou hodnotu.

system.exit( [ návratová_hodnota ] )

system.edit

editace souboru. Vyvolá externí editor. Jako parametr dostane jméno souboru k editaci a (volitelně) program editoru.

system.zip

Příkaz pro manipulaci se ZIP soubory. Příkaz zabalí cílový soubor(y) / adresář(e) do ZIP archívu, jehož název je prvním parametrem. Jako poslední parametry mohou být uvedena klíčová slova modifikující činnost příkazu.

syntaxe:
system.zip(cílový_ZIP_Soubor, [prefix:]zdrojovýSoubor1 [, [prefix:]zdrojovýSoubor2 [ , ... ] ] [ , verbose ] [ , move ] [ , append ] [ , subdir ] [ , withParent ] )

Příklad:

// Do souboru „/tmp/cilovyZip.zip“ zabalí obsah všech souborů s příponou „java“ z adresáře
// „/home/gapo/mojedata“ a všech podadresářů. V zipu bude jako root obsah adresáře „/home/gapo/mojedata/“

// (ten sám tam nebude)
    system.zip("/tmp/cilovyZip.zip", "/home/gapo/mojedata/*.java", subdir)

// Do souboru „/tmp/spojenyZip.zip“ zabalí obsah všech souborů s příponou „class“ z adresáře
// „/home/gapo/mojedata“ a všech podadresářů a dále obsah ZIP souboru „/tmp/spojenyZip.zip“

// Ve výsledném zipu bude jako root adresář pro data z „/home/gapo/mojedata/“ tento adresář

// (bude tam vidět).
    system.zip("/tmp/ spojenyZip .zip", "/home/gapo/mojedata/*.class", "zip:/tmp/spojenyZip.zip", subdir, withParent)

system.unzip

file

skupina příkazů pro práci se soubory filesystému

file.load , file.copy ,

file.load

načte soubor nebo jeho část z filesystému a vrátí jako textovou proměnnou

syntaxe:

file.load(jméno_souboru, [konvertor]);

načte celý soubor

file.load(jméno_souboru, od_pozice, < počet_znaků | -1>, [konvertor]);

načte část souboru od ‚ od_pozice ‘ do ‚ do_pozice ‘

file.load(jméno_souboru, string_určující_začátek , < string_určující_konec >, [konvertor]);

načte část souboru mezi texty ‚ string_určující_začátek ‘ a ‚ string_určující_konec ‘

file.load(jméno_souboru, string_určující_začátek , < počet_znaků | -1 >, [konvertor]);

načte část souboru mezi texty ‚ string_určující_začátek ‘ a ‚ string_určující_konec ‘

Poznámka:

file.copy

kopíruje obsah souboru do jiného souboru

syntaxe:
file.delete

smaže soubor

  file.save

uloží proměnnou do souboru. Pokud soubor se zadaným jménem existuje, bude přepsán. Pokud neexistuje, bude vytvořen.

syntaxe:
file.save( < proměnná | výzaz > , jméno_souboru, [ , konvertor ] )
kde

file.append

Jako file.save, ale pokud soubor existuje, není přepdán ale data jsou přidána na jeho konec.

syntaxe:
file.move

přemístí soubor

syntaxe:
file.exists

testuje, jestli string je existující soubor. Vrací logickou proměnnou.

syntaxe:

file.exists( jméno_souboru )

file.getPath

vrátí úplnou cestu k souboru / adresářijako textovou proměnnou. U adresářů NEDÁVÁ na konec oddělovač (lomítko ...)

file.getName

vrátí jméno souboru / adresáře bez cesty jako textovou proměnnou

file.getParent

vrátí úplnou cestu k nadřízenému adresáři jako textovou proměnnou

file.isDirectory

testuje, jestli string je existující adresář. Vrací true pokud existuje a je adresář, jinak false.

syntaxe:
file. isDirectory( jméno_adresáře )

file.rename
přejmenuje soubor

syntaxe:
file.rename( starý_název, nový_název )

directory

skupina příkazů pro práci s adresáři (ve Windows: složkami) filesystému

directory.create
Vytvoří adresář zadaného jména

directory.delete
Smaže zadaný adresář

directory.copy
Kopíruje adresář (a případné podadresáře) na cílové místo

syntaxe:
directory.copy( výchozí_adresář , cílový adresář [ , filtr] [, recursive ] )

directory.list, directory.listFiles

Příkaz directory.list vrátí resultset s kompletním výpisem zadaného adresáře, přílaz directory.listFiles vrátí seznam souborů (NIKOLI adresářů) v tadaném adresáři.

syntaxe:
directory.list( výchozí_adresář [ , filtr] [, recursive ] )
directory.listFiles( výchozí_adresář [ , filtr] [, recursive ] )

Vrácený resultset má tyto 4 sloupce:

directory.remove
vymaže adresář nebo celou adresářovou strukturu

syntaxe:
directory.remove( rušený_adresář [ , filtr] [, recursive ] )

directory.exists
Vrátí true, pokud existujr zadané jméno na filesystému a je to adresář; jinak false;

syntaxe:
direcory.exists( jméno_adresáře )

directory.rename
přejmenuje adresář

syntaxe:
directory.rename( starý_název, nový_název )

url

skupina příkazů pro manipulaci s daty prostřednictvím URL / URI

url.load

načte obsah url do textové proměnné.

syntaxe:
url.load(url, [ , přihlašovací_informace ] [ , konvertor ] );

Poznámka:

Pokud se pozžije konvertor 'NoConvert', lze načítat binární data a ta pak (opět s konvertorem 'NoConvert') uložit do souboru, jiné URL, databáze a pod.

url.get

totéž jako url.load ;

url.save

url.post

uloží data do vybrané URL příkazem "post" a vrátí výsledek jako text. proměnnou

syntaxe:
url.post(url, co_se_posílá [, konvertor ])
kde

url = url, na které se data posílají

co_se_posílá = string, který je odeslán

url.timeout

nastaví timeoput pro práci s URL. Všechny operace musí proběhnout do nastavené doby, jinak bude příkaz stornován.

syntaxe:
url.timeout(čas_v_sekundách )

form

skupina příkazů pro práci s formulář i

form.create

vytvoří nový formulář

syntaxe:
form.create(jméno_formuláře, titul_nebo_zahlavi, parametry)

form.addItem

přidá položku do formuláře

syntaxe:
form.addItem(jméno_formuláře, typ_položky, pozice_položky_ve_formuláři, data_položky)

form.display

zobrazí vybraný formulář

syntaxe:
form.display(jméno_formuláře [, parametry_zobrazení])

Poznámka:

podle typu interface, pod kterým MSQL běží se formulář zobrazí v příslušném výstupním zařízení (v okně programu, do HTML stránky, na konzole …)

form.getValue

vrátí položku formuláře jako textovou proměnnou. Vrácená hodnota závisí na typu položky.

syntaxe:
form.getValue(jméno_formuláře, jméno_položky )
Jménu položky z vnořeného formuláře musí předcházet jméno tohoto (vnořeného) formuláře a tečka.

Příklad:

$a = form.getValue (“form1”, “vnoreny.polozka1”);

je totéž jako

$a = form.getValue (“vnoreny”, “polozka1”);