Věcný obsah, základní pojmy - AbraOLE

Nezbytnou podmínkou pro provoz otevřeného rozhraní je, aby byla tato část systému nainstalována a licencována.

• Otevřené rozhraní je součástí jádra systému, tudíž je instalováno v rámci instalace jádra - viz Instalovatelné součásti.
• Otevřené rozhraní je licencováno samostatně - viz Licencované celky (licencované moduly a vlastnosti).

  Dále se hned po spuštění kontroluje:

  • existence licence na jádro (viz Test existence platné licence jádra) - Je-li výsledek negativní, OLE aplikace se nespustí.

Dále viz OLE rozhraní a přístupová práva.

Práce s otevřeným rozhraním ABRA Gen může být realizována dvěma způsoby:

• přes program AbraOLE.exe
• přes knihovnu AbraOLELib.dll

V obou případech se jedná o OLE Automation serverABRA Gen. Je možno je používat jako lokální (COM) OLE Automation server, ale i jako vzdálený (DCOM) OLE Automation server (příslušný script využívající otevřené rozhraní, však musí být napsán odpovídajícím způsobem pro vzdálené použití).

AbraOLELib.dll obsahuje totéž co AbraOLE.exe, ale pracuje jako tzv. inproc server (in process server, tj. forma *.dll) , kdežto AbraOLE.exe pracuje naopak jako outproc server (out process server, tj. forma *.exe). Využití AbraOLELib.dll s externím exe doplňkem tvoří jeden proces. Tudíž všechna volání přes AbraOLELib.dll jsou rychlejší (celkově může práce s otevřeným rozhraním přes knihovnu být rychlejší až cca o 20-30%). Kdežto při využití AbraOLE.exe pro napojení externích doplňků jsou doplněk i AbraOle.exe samostatnými procesy (jistou výhodou tohoto řešení je nezávislost procesů - "upadnutí" jednoho neznamená, že automaticky je "shozen" jiný).

AbraOLELib.dll byl v systému zaveden později. Důvodem, proč existují obě možnosti, je hlavně zpětná kompatibilita (mohou existovat různé externí aplikace navázané na AbraOLE.exe).

AbraOLElib.dll obsahuje téměř stejnou typovou knihovnu - liší se jen v tomto:

• jiný název (místoAbraOLE je to AbraOLELib)
• jiný GUID (GUID typové knihovny), aby byla možná registrace odděleně od AbraOLE.exe
• jiný GUID CoClass NxStrings a Application

- set mG3 = CreateObject("AbraOLE.Application")
- set mG3 = CreateObject("AbraOLELib.Application")

Chovají se jako klientská část aplikace ABRA Gen, která komunikuje s aplikačním serverem (tedy obdobně jako jakýkoliv jiný klient ABRA Gen). (Pojem klientská část viz kap. Technologie zpracování dat.)

Jelikož jde o COM (resp. DCOM) OLE Automation server, je jeho použití omezeno na operační systém MS Windows. Jedná se o klientskou část aplikace ABRA Gen, tedy i když máte síťovou část instalace na Linuxu a chtěli byste využívat Otevřené rozhraní, je třeba počítat s tím, že AbraOLE.exe resp. AbraOLELib.dll musí běžet na některém z windowsových klientů.

Registrace COM objektů pro otevřené rozhraní:

Registrace neprobíhá nijak automaticky při instalaci ABRA Gen. Tedy musíte registraci spustit ručně.

Možnosti registrace:

• Jejich registrace pro danou instalaci ABRA Gen se provede automaticky spuštěním programu AbraOLE.exe s parametrem /regserver.

• AbraOLELib.dll lze zaregistrovat (resp. přeregistrovat) kdykoliv ručně a to např. pomocí příkazu "RegSvr32 AbraOLELib.dll" (bez uvozovek) do aktuálního adresáře, příp. do zadaného adresáře, je-li uvedeno s plnou cestou.

  Pro registraci AbraOLELib.dll se volá externí program regsvr32.exe, tudíž po provedení registrace je nutné potvrdit hlášení o úspěšné registraci, které generuje regsvr32. (Regsvr32.exe není součástí instalace ABRA Gen, jedná se o soubor OS Windows.)

• Registrace potřebných součástí pro provoz otevřeného rozhraní (AbraOLE.exe i AbraOLELib.dll) na klientském počítači je rovněž možno provést v rámci agendy Nastavení klienta z dané stanice a zatržením volby instalace otevřeného rozhraní.

  Na počítači s OS Windows, u kterých se pro obdobné akce vyžadují administrátorská oprávnění, je třeba mít pro zdárné provedení dané akce požadovaná oprávnění. Pro zdárnou registraci je třeba spustit ABRA Gen funkcí "Spustit jako Správce". ABRA Gen rozpoznává, zda běží na OS Windows 7 či vyšším a vyžaduje přechod do režimu Administrátora, aby mohla registraci bezchybně dokončit.

Zaregistrují se s cestou do adresáře instalované ABRA Gen. Pokud již jsou ve Windows registrech registrovány s nějakou cestou (např. z dřívější registrace téhož z jiné instalace), pak je nové provedení registrace přeregistruje do svého adresáře. (Odinstalováním dané ABRA Gen se záznamy v registrech neruší, nicméně odkaz do daného adresáře již nemusí být samozřejmě platný).

Poté je již možno jej provozovat. Příslušné komunikační prográmky mohou být např. programy ve VisualBasic, scripty v MS Excel apod.

Ikona programAbraOLE je po jeho spuštění viditelná v oznamovací oblasti Windows. Levým tlačítkem myši se zobrazí okno AbraOLE, pravým tlačítkem místní nabídka s možnostíAbraOLE ukončit.

Příklad zobrazení programu AbraOLE.exe v oznamovací oblasti s místní nabídkou.

V okněAbraOLE je možné zobrazovat i informace o tom, co se děje, tzv. log. Log je možno uložit do souboru. Logování je ve výchozím stavu vypnuto.

Tento odstavec rozšiřuje informace z předchozího bodu a je uveden pro úplnost. Běžný uživatel se jím nemusí nijak zabývat.

Kromě výše zmíněných dvou možností AbraOLE.exe a AbraOLELib.dll je k dispozici ještě knihovna iAbraOLE.dll. Slouží k tomu, aby bylo možné používatAbraOLE přímo uvnitř systému ABRA Gen. Je to interní rozhraní poskytované systémem. Může být však využito pouze procesy, o kterých systém tzv. "ví" (čili uživatel je pro napojení svých doplňků využít nemůže). Interní iAbraOLE rozhraní je využito např. pro integraci:

• vývojového a skriptovacího rozhraní
• dll háčků (v současnosti např. pro cenotvorbu na míru)

Oproti napojení přes AbraOLE.exe resp. AbraOLELib.dll má iAbraOLE řadu výhod:

• je rychlejší (není třeba načítat číselníky, ale lze využít už existující cache (na obrázku naznačeno jako modré kolečko (lze si představit jako jakési "jadérko")))
• není třeba při napojení řešit přihlašování do systému, zjišťování aktivního uživatele atd.
• atd.

Rámcové schéma dokumentující možnosti využití otevřeného rozhraní. Doplněk exe napojený přes AbraOLELib.dll tvoří jeden proces, kdežto při využití AbraOLE.exe je každé exe samostatným procesem (výhody a nevýhody viz výše).

Modře jsou znázorněny napojení přes interní rozhraní iAbraOLE. Interní rozhraní lze použít pouze pro procesy, o kterých ABRA Gen "ví".

V obrázku je zakreslena i možnost využití interního iAbraOLE na napojení externí aplikace. V tomto případě se jednalo o externí řešení workflow M/Team bridge napojeného na systém ABRA Gen. Od v.14.51 byla tato funkcionalita zrušena. Nicméně v obrázku zůstává zakreslena, jelikož je dobrým příkladem demonstrujícím možnosti využití interního iAbraOle.
U aplikace Workflow je kromě napojení přes interní rozhraní (označeno jako A1) pro srovnání znázorněno i napojení přes AbraOLE.exe (označeno jako A2). Obojí je možné, ale interní napojení je samozřejmě výhodnější (výhody iAbraOle viz výše). Externí aplikace pro workflow byla řešena integrací přímo do systému ABRA Gen (to znamenalo, že obdoba uživatelského rozhraní externí aplikace (tj. obdoba MtbGUI.exe), byla integrována do ABRA Gen jako jedna z agend ABRA Gen). Při startu agendy Worklfow bylo objektům externí aplikace (MtbOleEngines) poskytnuto interní rozhraní iAbraOle a příslušný progpoint. Objekty externí aplikace byly uzpůsobeny tak, že "uměly" toto rozhraní akceptovat. Skripty, v nichž byly definovány vlastní scénáře workflow a které řídily vlastní přechody ze stavu do stavu a vykonávání souvisejících akcí, byly realizovány tak, že defaultně hledaly daný progpoint, a byl-li k dispozici, využily napojení přes iAbraOle. Tudíž nebylo třeba v rámci skriptů řešit např. přihlašování uživatele a nové načítání číselníků do cache atd. při každém přechodu do nového stavu workflow, které by jinak bylo nutné při napojení přes AbraOLE.exe. Celý proces přes iAbraOLE tudíž byl i rychlejší.

Jiným případem je např. napojení dll háčků (DLLHooks, označeno jako B). Externí dll může obsahovat funkce, které pro vrácení požadovaného výsledku potřebují zjistit řadu informací, které si mohou zjistit právě díky kontaktu přes iAbraOLE na běžící ABRA Gen.

Otevřené rozhraní podporuje jak práci s pevnými položkami danými výrobcem, tak s definovatelnými položkami. Je tedy možné prostřednictvím otevřeného rozhraní zadávat a opravovat i definovatelné položky.

Přihlásit se přes otevřené rozhraní a používat jej mohou pouze uživatelé, kteří mají přidělené privilegium Otevřené rozhraní, případně privilegium Supervisor.

V rámci OLE se aplikují práva k objektům a pokud je v OLE aplikaci použito i "vizuálno" systému ABRA Gen, pak také práva k funkcím. V opačném případě se práva k funkcím neaplikují.

Pokud je součástí OLE aplikace nějaká akce, která interně znamená použití SQL příkazů SELECT resp. EXECUTE do databáze systému ABRA, musí mít uživatel právo k funkci NxSQLSelect resp. právo k funkci NxSQLUpdate a nesmí mít zakázáno použití konkrétních tabulek ve skriptovacích funkcích. Jinak mu není povoleno takovou akci provést.

V této části je uvedeno několik poznámek týkajících se práce s otevřeným rozhraním.

K využití metod UpdateValues(), CreateNewFromValues() atd.

Typicky se jedná o případ opravy dokladu přes otevřené rozhraní - tj. načtení existujícího dokladu přes otevřené rozhraní přes GetValues, oprava a uložení přes UpdateValues.

Jsou zavedena následující pravidla:

• Naplněnou instanci třídy ObjectData je možné uložit metodou UpdateValues() pouze tehdy, byla-li instance ObjectData vytvořena voláním GetValues(). Po volání UpdateValues() je instance ObjectData označena a další volání UpdateValues() s touto instancí ObjectData vyvolá výjimku.
• Taktéž po volání CreateNewFromValues() je instance ObjectData označena a její použití při volání UpdateValues() vyvolá výjimku. Nicméně volat CreateNewFromValues() s jednou instancí ObjectData je možné.
• Při ukládání se ve vrstvě otevřeného rozhraní kontroluje ObjVersion. Sice jde o duplicitní kontrolu (problém by "odchytila" databáze), ale předejdeme časově náročnému pokusu o uložení.

K pořadí hodnot, v jakém se plní položky u některých objektů:

Typicky se jedná o případ, kdy se chce přes otevřené rozhraní zadat nový PV, a na řádce zadávat TAmount a TAmountWithoutVAT (defaultně je způsob zadávání TAmountWithoutVAT a VATAmount). Způsob zadávání částek na řádky lze v hlavičce nastavit, ale tomu je třeba přizpůsobit i pořadí, v jakém se uloží položky řádků (pokud by se položky v řádcích uložily v jiném pořadí, došlo by interně k nežádoucímu přepočtu).

Jelikož u některých objektů záleží na pořadí hodnot, v jakém se plní, jsou zavedena následující pravidla:

• Při naplňování hodnot do instancí třídy ObjectData se pamatuje, v jakém pořadí se do jednotlivých vlastností zapisovaly hodnoty. Do Business objektůABRA Gen se pak hodnoty předávají ve stejném pořadí, tudíž by neměl nastat problém s ukládáním vlastností.
• Do Business objektů se předávají pouze ty hodnoty, které byly skutečně změněny. Např. pokud se při opravě změní pouze datum, toto jediné datum se pošle do BO.
• Pořadí, v jakém byla data modifikována, které se zohledňuje při ukládání dat do objektu se uplatňuje nejen u jednoduchých položek, ale i u položek typu kolekce a vlastněné objekty.
• Pozor! U nových objektů je pořadí aktualizace nastaveno voláním PrefillValues(). Z toho plyne, že pořadí je pak dané podle definované struktury v BO, takže pozor. Když do takto předvyplněné instance ObjectData začneme zapisovat svoje data, pořadí aktualizace hodnot do BO se bude samozřejmě měnit.

K zadání firmy resp. provozovny na doklad

Aby bylo možné přes OLE vystavovat doklady (takové, které mají firmu a provozovnu), jsou k dispozici dva postupy:

• První možnost je, že se zadá firma a provozovna se nenastavuje. Pak musí být nastaven parametr Předvyplňovat firemní provozovny ve Firemních nastaveních na hodnotu Ano.
• Druhá možnost je, že se zadá firma, z firmy se získají provozovny, jedna se vybere a nastaví na doklad. Do dokladu se pak vlastnosti nastavují v pořadí firma, provozovna. Globální parametr předvyplňovat provozovny nemusí být v tomto případě nastaven na Ano.

Přepnutí na jiné spojení

AbraOLE.exe umožňuje vytvořit více objektů Application, přičemž každý může být pro jiné spojení. Díky tomu je možné v jednom programu využívajícíAbraOLE pracovat s daty, která příslušejí různým spojením na databázi (connections).

Dim ZLO 
Dim ZLD 
Dim G3
Set G3 = CreateObject("AbraOLE.Application")
Set ZLO = G3.CreateObject("@IssuedDepositUsage")
Set ZLD = G3.CreateValues("@IssuedDepositUsage")
ZLD.ValueByName("DepositDocument_ID") = "7700000101"
ZLD.ValueByName("PDocumentType") = "03"
ZLD.ValueByName("PDocument_ID") = "A900000101"
ZLD.ValueByName("PDisKind") = 1
ZLD.ValueByName("PAmount") = 1
ZLD.ValueByName("Amount") = 1
ZLD.ValueByName("PaymentDate$Date") = "2.7.2003"
ZLD.ValueByName("AccDate$DATE") = "2.7.2003"
ZLD.ValueByName("CreatedBy_ID") = "SUPER00000"
ZLO.CreateNewFromValues ZLD....

Set mStdOut = WScript.StdOut
Dim mApplication 
Set mApplication = CreateObject("AbraOLE.Application")
'mApplication.LogIn "Supervisor", ""
Set mDynSQL = mApplication.CreateCustomCommand("40SBPEINEFD13ACM03KIU0CLP4") ' FV
Set mCond = mDynSQL.ConstraintByID("Period_ID")
mCond.UsedKind = 1
mCond.Value = "'" & "1000000101" & "'"
mCond.ValueBag = "{IsNegation}=1"
Set mDataset = mDynSQL.RowsetByName("MAIN")
mDataset.UsedFields = "Period_ID" 
mDataset.Used = True
mDynSQL.Execute
mStdOut.WriteLine "Výsledek:" & CRLF
while not mDataset.EOF
mStdOut.WriteLine "asa"
'' mStdOut.Write mDataset.FieldByName("ID") & " "
mDataset.Next
wend

Parametry pro číselníky (filtr pro číselníky)

Přes otevřené rozhraní je možno používat některých funkcí číselníku. Za tímto účelem se do číselníků mohou předávat parametry pro filtrování. Těmito parametry lze číselník filtrovat za určitý výčet klíčových hodnot, kterým se rovná klíč nadefinovaný v DynSQL nebo výraz daného klíče.

• '@' ['!'] Výraz_klíče = dtString
  Filtr podle výrazu klíče (typicky Výraz klíče = Název položky (Field)). Pokud je před výrazem uveden znak '!', pak se do výběru zařadí záznamy, pro které hodnota parametru neplatí.
• '@#' ['!'] Výraz_klíče = dtString
  Řetězec s hodnotami oddělenými středníky, které lze vybrat. Pokud má být filtr typu "množina hodnot nebo nevyplněno", je třeba ve filtru uvést 2x znak ; (Např. @#ReservedForDoc_ID=1000000101;;). Pokud je uveden znak '!' (pred nebo za znakem #), pak se do výběru zařadí záznamy, pro které hodnota parametru neplatí.
• '@@' ['!'] Klíč = dtString
  Filtr podle jména (názvu) klíče. Pokud je před klíčem uveden znak '!', pak se do výběru zařadí záznamy, pro které hodnota parametru neplatí.
• '@@#' ['!'] Klíč = dtString
  Řetězec s hodnotami oddělenými středníky, které lze vybrat. Pokud je uveden znak '!' (pred nebo za znakem #), pak se do výběru zařadí záznamy, pro které hodnota parametru neplatí.

Tedy:

@Výraz_klíče=Hodnota1
@#Výraz_klíče=Hodnota1;Hodnota2
@@Název_klíče=Hodnota1
@@#Název_klíče=Hodnota1;Hodnota2

Pro negaci:

@!Název_pole=Hodnota1  
@#!Název_pole=Hodnota1;Hodnota2;; // Hodnota nesmí být žádná z uvedených ani nesmí být nevyplněná
@@!Název_klíče=Hodnota1;Hodnota2
@@#!Název_klíče=Hodnota1;Hodnota2 // Hodnota nesmí být žádná z uvedených

Sub SelectDialog()
Dim mApplication As New AbraOLE.Application
Dim mRoll As Roll
Dim mID As String
Set mRoll = mApplication.GetRoll("{A133BBE0-1FF0-11D2-9911-00E0ED0111A9}", 0)
' Doplnění filtračních parametrů
mRoll.Params.Add "@#DocumentType=03;04;00"
mRoll.Params.Add "@@#DocumentTypeAndCode=03FV;03FV2;04FP;00INT"
'mRoll.Params.Add "@#!DocumentType=03;04;00"
'mRoll.Params.Add "@@#!DocumentTypeAndCode=03FV;03FV2;04FP;00INT"
If mRoll.SelectDialog(True, mID) Then
MsgBox mID
End If
End Sub

Další příklad viz též popis Parametrů uživatelsky definovatelných položek typu číselník. Zde jsou uvedeny i některé další i zde použitelné parametry jako např. _Allowed, _Excluded.

Externím OLE aplikace mají k dispozici i možnost volat tisk a export pomocí tiskových sestav resp. definovatelných exportů definovaných v systému ABRA Gen.

Díky tomu je možné mj. např.:

• automaticky vytisknout doklad po jeho vytvoření externí aplikací (např. pomocí online čtečky čár. kódů)
• sestavování a rozesílání automatických reportingů (např. automatické rozesílání upomínek, potvrzení objednávek, …)
• generování exportů nebo sad exportů v pravidelných časech
• a mnohé další.

Volání z OLE rozhraní podporuje obdobné možnosti tisků a exportů jako jsou u visuálního klienta (tisk s nabídkou číselníku sestav, přímý tisk s náhledem, přímý tisk bez náhledu, export s nabídkou číselníků exportů, export s přímým vytvořením souboru s možností přednastavit nabízené volby pro výběr exportu, atd.), viz též Tisky resp. Exporty. Konkrétní popis příslušných metod viz dokumentace (viz Jak vyvolat nápovědu - GenDoc.chm).

V rámci instalace ABRA Gen je dodáván doplněk pro aplikaci Excel NxTurnover.xla. Jedná se o jednu z možností, jak získávat výstupní účetní přehledy.

Jedná se o doplněk do MS Excel, který funguje podobně jako NxABRA.xla pro účetní výkazy jen s tím rozdílem, že funguje on-line nad daty systému ABRA tzn. připojuje se přes ABRA OLE a načítá data on-line (dle zadaných parametrů). (Zatímco NxABRA.xla čte data z předpřipravené datové krychle). Viz Účetní výkazy - věcný obsah.

• Výhody: on-line, lze omezit za střediska, zakázky, obchodní případy, ...
• Nevýhody: pomalejší oproti výstupům s využitím datové krychle, musí být k dispozici běžící systém ABRA, uživatel musí mít dostatečnou licenci a přístup. práva na otevřené rozhraní.

NxTurnover.xla disponuje funkcemi NxTurnover, NxTurnoverSimple a NxReal. Tyto funkce se připojí přes OLE rozhraní na systém ABRA a vracejí obraty z účetnictví na základě předaných parametrů.

• Funkce NxTurnover vrací obraty z účetního deníku a volitelně i z účetních žádostí. Má parametry Účet, Datum od, Datum do, Středisko, Zakázka, Obchodní případ a Projekt a příznaky, zda se mají tyto veličiny započítávat i s podřízenými jako zvláštní parametry a zda se mají započítávat i účetní žádosti. Odpovídá metodě GetTurnover objektu BookEntry z OLE.
• Funkce NxTurnoverSimple vrací obraty z účetního deníku a z účetních žádostí. Má pouze data od a do a ostatní omezení se zadávají třetím parametrem ve formě řetězce. Pozor! Oddělení jednotlivých podmínek (parametrů) nesmí obsahovat mezeru! Odpovídá metodě GetTurnoverSimple objektu BookEntry z OLE.
• Funkce NxReal vrací obraty z účetního deníku a z účetních žádostí. Má parametry Účet, Datum od, Datum do, Středisko, Zakázka, Obchodní případ a Projekt, ale na rozdíl od NxTurnover neumožňuje nastavit, že se tyto veličiny mají započítávat včetně podřízených (započítávají se vždy bez podřízených (hodnota "Včetně podřízených" je vždy false) a neumožňuje nastavit, že se nemají započítávat žádosti (vždy se započítávají). Odpovídá zjednodušené metodě GetTurnover objektu BookEntry z OLE.

Zároveň je dodáván i soubor NxTurnoverExample.xls, který demonstruje použití funkcí.