Požadavek do-export

Účel a dopady

Naplánuje exportní úlohu, která spustí jeden nebo více SQL dotazů (select), výsledek volitelně protáhne XSL transformací a uloží jako soubor do exportní složky. Požadavek samotný jen zaeviduje úlohu do plánovače (cronu) a vrací se okamžitě – skutečný export (dotazy do databáze i zápis souboru) proběhne asynchronně v jiném vlákně, případně opakovaně dle repeat. Vedlejší účinky: založení záznamu naplánované úlohy a později (při běhu úlohy) zápis exportního souboru na disk.

Dostupnost, kontext, oprávnění apod.

• Vyžaduje aktivovanou vlastnost uživatele p_export (interně roli r_export) nebo p_admin (r_admin).
• Nastavit repeat nebo failsafe na jinou hodnotu než none/prázdnou vyžaduje navíc p_repeat (r_repeat) nebo r_admin.
• Atribut run-as vyžaduje r_admin, nebo r_impersonate u volajícího a úspěšné ověření vůči cílovému uživateli.
• Server oprávnění ověřuje znovu při každém skutečném spuštění úlohy (i při opakování).
• Podléhá standardnímu transakčnímu zpracování obálky <request> (přeskočení/odvolání transakce) – viz obálka požadavku.

XML požadavek (syntax + popis)

  <request>
   <do-export
    validity="{string}"
    repeat="{string}"
    failsafe="{string}"
    sched-from-end="{bool}"
    when-off="{bool}"
    run-as="{number}"
    by-action="{bool}"
    db-log="{bool}"
    rel-folder="{string}"
    file-ext="{string}"
    file-caption="{string}"
    extend-caption="{string}"
    file-type="{string}"
    >
    <sql-query
     opt-roles="{string}"
     >
     <select
      type="{string}"
      setting="{number}"
      user="{number}"
      opt-roles="{string}"
      >
      {string}
     </select> +
    </sql-query>
    <xsl:stylesheet ... /> ?
   </do-export>
  </request>

Parametry a pravidla (atributy, potomci)

Plánovací atributy sdílené s ostatními do-* požadavky

Základní tvar odpovídá sdílenému typu do-task; ten ale v době revize neuvádí run-as, by-action ani db-log (viz poznámka na konci této stránky). Skutečné chování:

• validity - Platnost úlohy - Řídí první spuštění (once/today/still/from-...;to-...). (typ: string; nepovinný; chybí-li, chová se jako okamžité jednorázové spuštění)
• repeat - Opakování - Syntaxe viz Nastavení plánovače úloh; nastavení na cokoliv jiného než none/prázdné vyžaduje r_repeat nebo r_admin. (typ: string; nepovinný; výchozí: bez opakování)
• failsafe - Opakování při chybě - Syntaxe stejné rodiny jako repeat; stejná privilegovaná podmínka. (typ: string; nepovinný)
• sched-from-end - Plánování od konce běhu. (typ: bool; nepovinný; výchozí: false)
• when-off - Doběhnutí po výpadku. (typ: bool; nepovinný; výchozí: false)
• run-as - Zastoupení uživatele - Vyžaduje r_admin, nebo r_impersonate a úspěšný test zastoupení; neplatná hodnota => úloha se vůbec nezaloží. (typ: number; nepovinný)
• by-action - Založeno akcí - Promítá se do job/@by-action v job-list. (typ: bool; nepovinný; výchozí: false)
• db-log - Log úlohy do databáze. (typ: bool; nepovinný; výchozí: false)

Vlastní atributy do-export

• rel-folder - Podsložka exportní složky - Volitelná podsložka exportní složky dle nastavení serveru. (typ: string; nepovinný)
• file-ext - Přípona - Přípona exportovaného souboru. (typ: string; nepovinný)
• file-caption - Název - Základ názvu souboru. Zároveň se tato hodnota stává názvem úlohy (atribut job/@name v job-list). (typ: string; nepovinný)
• extend-caption - Číslování souboru - true doplní vzestupné číslo, file doplní číslo o jedna vyšší než nejvyšší existující, date doplní datum, time doplní datum a čas; jakákoli jiná/chybějící hodnota znamená bez doplnění. (typ: string; nepovinný; výchozí: bez doplnění; povolené hodnoty: true, file, date, time)
• file-type - Typ exportu - Jediná rozpoznávaná hodnota je "xml" (case-insensitive); jakákoli jiná hodnota, včetně chybějící, znamená textový export. (typ: string; nepovinný; výchozí: text; povolené hodnoty: xml, text)

Pozor: oproti do-importu do-export nemá atribut doc-type. Předchozí verze této stránky jej uváděla mylně.

Uzel sql-query a select

Vzhledem podobný uzlu z sql-query, ale s odlišným a užším chováním:

• sql-query je povinný a musí obsahovat alespoň jeden select, jinak se úloha vůbec nezaloží.
• sql-query/@opt-roles - Výchozí volitelná role pro vnořené select, které ji sami nepřepíšou. (typ: string; nepovinný)
• select/@type, select/@setting, select/@user, select/@opt-roles mají stejný význam jako u sql-query. Neplatné/záporné user/setting se nahrazují 0 (ne -1 jako u samostatného sql-query).
• select zde nemá atributy archive, avoid-xml ani measure-time – nečtou se, export nikdy nepracuje s archivní databází a text SELECTu je vždy automaticky doplněn o " FOR XML RAW" bez možnosti to vypnout.
• Prázdný text select => úloha se vůbec nezaloží.
• Řetězec -!- v textu SELECTu se při běhu nahradí číslem efektivní role (stejný mechanismus jako u sql-query, bez varianty pro archivní režim).

Uzel xsl:stylesheet

• Nepovinný. Pokud je uveden, musí jít o syntakticky platný XML dokument; jinak se úloha vůbec nezaloží. Server rozpoznává jen doslovný název uzlu xsl:stylesheet; jmenný prostor http://www.w3.org/1999/XSL/Transform se nevynucuje.
• Atributy a potomci uzlu nejsou serverem nijak omezeny – validuje se jen výsledná XML platnost celého bloku.

Příklady požadavku

(Zatím bez ověřeného příkladu; viz ukázky exportu.)

Zpracování a vedlejší účinky

• Založení úlohy s uvedeným xsl:stylesheet volá při zakládání MSXML komponentu (IXMLDOMDocument3/IXSLTemplate) k okamžitému ověření platnosti šablony – chyba na této úrovni má vlastní chybovou odpověď (viz níže), odlišnou od ostatních do-* požadavků.
• Skutečné spuštění dotazů, transformace a zápis souboru probíhá až při běhu úlohy (asynchronně), ne v okamžiku přijetí požadavku.
• Text požadavku (celý uzel do-export včetně potomků) se serializuje a ukládá k naplánované úloze v databázi, pokud jde o novou (nikoli znovunačtenou) úlohu.

XML odpověď (syntax + popis)

  <response>
   <do-export
    status="ok|error"
    id="{number}"
    next-run="{string}"
    detail="{string}"
    />
  </response>

Kořenový element odpovědi má vždy stejný název jako uzel požadavku (do-export), ne do-task-result – ten je jen typový popis tvaru atributů, viz sdílený typ do-task-result (pozor: tento typ v době revize neuvádí next-run, viz poznámka na konci stránky).

• status - Výsledek zaevidování - ok, pokud byla úloha úspěšně založena, jinak error. (typ: enum; povolené hodnoty: ok, error)
• id - Id úlohy - Číslo přidělené serverem nové úloze. Přítomno jen při status="ok". (typ: number)
• next-run - Nejbližší spuštění - Formát YYYY-MM-DD HH:MM:SS (místní čas serveru). Přítomno jen při status="ok". (typ: datetime)
• detail - Popis chyby - Přítomno jen při status="error". (typ: string)

Příklady odpovědi

(Zatím bez ověřeného příkladu.)

Chyby a reakce

Odpověď je vždy jediný samouzavírající uzel do-export (žádný vnořený error). Na rozdíl od ostatních do-* požadavků má do-export tři různé texty selhání při zakládání:

• status="error" detail="Nemate patricna opravneni" – volající nemá r_export ani r_admin.
• status="error" detail="XSL-T sablonu se nepodarilo rozpoznat" – uvedený xsl:stylesheet se podařilo naparsovat jako XML, ale selhalo jeho navázání jako XSLT šablony (stylesheet->putref_stylesheet).
• status="error" detail="Pozadavek se nepodarilo rozpoznat" – jakákoli jiná chyba validace: chybějící/prázdný sql-query, žádný nebo prázdný select, neplatné XML v xsl:stylesheet.
• status="error" detail="Systemova chyba pri vkladani pozadavku" – selhání zápisu úlohy do databáze po úspěšné validaci.
• status="skip" detail="Transakce byla preskocena" / status="error" detail="Transakce byla odvolana" – požadavek byl přeskočen/odvolán v rámci transakčního zpracování obálky – viz obálka požadavku.

Související požadavky

• job-list – seznam naplánovaných úloh včetně exportů.
• undo – zrušení naplánované/opakované úlohy.
• sql-query – samostatné spuštění SQL dotazů se širší sadou atributů select.
• do-import, do-force-import – další plánované úlohy práce se soubory.