Vecný obsah, základné pojmy - AbraOLE

Nevyhnutnou podmienkou používania otvoreného rozhrania je, aby bola táto časť systému nainštalovaná a licencovaná.

• Otvorené rozhranie je súčasťou jadra systému, tzn. že sa inštaluje v rámci inštalácie jadra - viď Inštalovateľné súčasti.
• Otvorené rozhranie je licencované samostatne - viď Licencované celky (licencované moduly a vlastnosti).

  Ďalej sa hneď po spustení kontroluje:

  • existencia licencie na jadro (viď Test existencie platnej licencie jadra - Ak je výsledok negatívny, OLE aplikácia sa nespustí.

Ďalej viď OLE rozhranie a prístupové práva.

Práca s otvoreným rozhraním ABRA Gen môže byť realizovaná dvoma spôsobmi:

• pomocou programu AbraOLE.exe
• pomocou knižnice AbraOLELib.dll

V oboch prípadoch ide o OLE Automation serverABRA Gen. Je možné ich používať ako lokálny (COM) OLE Automation server, ale aj ako vzdialený (DCOM) OLE Automation server (príslušný script využívajúci otvorené rozhranie, však musí byť napísaný zodpovedajúcim spôsobom pre vzdialené použitie).

AbraOLELib.dll obsahuje to isté, čo AbraOLE.exe, ale pracuje ako tzv. inproc server (in process server, tzn. forma *.dll) , kým AbraOLE.exe pracuje naopak ako outproc server (out process server, tzn. forma *.exe). Využitie AbraOLELib.dll s externým exe doplnkom tvorí jeden proces. To znamená, že všetky vyvolania pomocou AbraOLELib.dll sú rýchlejšie (celkovo môže práca s otvorením rozhraním pomocou knižnice byť rýchlejšia až cca o 20-30%). Kým pri využití AbraOLE.exe na napojenie externých doplnkov sú doplnok aj AbraOle.exe samostatnými procesmi (istou výhodou tohto riešenia je nezávislosť procesov - "spadnutie" jedného neznamená, že automaticky je "zhodený" iný).

AbraOLELib.dll bol v systéme zavedený neskôr. Dôvodom, prečo existujú obe možnosti, je hlavne spätná kompatibilita (môžu existovať rôzne externé aplikácie naviazané na AbraOLE.exe).

AbraOLElib.dll obsahuje takmer rovnakú typovú knižnicu - líši sa len 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")

Správajú sa ako klientska časť aplikácie ABRA Gen, ktorá komunikuje s aplikačným serverom (tzn. podobne ako ktorýkoľvek iný klient ABRA Gen). (Pojem klientska časť viď v kap. Technológia spracovania dát.)

Keďže ide o COM (resp. DCOM) OLE Automation server, je jeho použitie obmedzené na operačný systém MS Windows. Ide o klientsku časť aplikácie ABRA Gen, takže i v prípade, že máte sieťovú časť inštalácie na Linuxe a chceli by ste využívať Otvorené rozhranie, je potrebné počítať s tým, že AbraOLE.exe resp. AbraOLELib.dll musí bežať na niektorom z windowsových klientov.

Registrácia COM objektov pre otvorené rozhranie:

Registrácia neprebieha nijako automaticky pri inštalácii ABRA Gen. Teda registráciu musíte spustiť ručne.

Možnosti registrácie:

• Ich registrácia pre danú inštaláciu ABRA Gen sa vykoná automaticky spustením programu AbraOLE.exe s parametrom /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.

  Na registráciu AbraOLELib.dll sa vyvoláva externý program regsvr32.exe, takže po zrealizovaní registrácie je nutné potvrdiť hlásenie o úspešnej registrácii, ktoré generuje regsvr32. (Regsvr32.exe nie je súčasťou inštalácie ABRA Gen, ide o súbor OS Windows.)

• Registrácie potrebných súčastí na prevádzku otvoreného rozhrania (AbraOLE.exe i AbraOLELib.dll) na klientskom počítači je rovnako možné urobiť v rámci agendy Nastavenia klienta z danej stanice a začiarknutím voľby inštalácie otvoreného rozhrania.

  Na počítači s OS Windows, pri ktorých sa pre podobné akcie vyžadujú administrátorské oprávnenia, je potrebné mať pre úspešné vykonanie danej akcie požadované oprávnenia. 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ú sa s cestou do adresára inštalovanej ABRA Gen. Pokiaľ už sú vo Windows registroch registrované s nejakou cestou (napr. zo skoršej registrácie toho istého z inej inštalácie), nové vykonanie registrácie ich preregistruje do svojho adresára. (Odinštalovaním danej ABRA Gen sa záznam v registroch neruší, no odkaz do daného adresára už nemusí byť samozrejme platný).

Potom ich už je možné používať. Príslušné komunikačné programy môžu byť napr. programy vo VisualBasic, scripty v MS Excel a pod.

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.

Príklad zobrazenia programu AbraOLE.exe v oznamovacej oblasti s miestnou ponukou.

V okněAbraOLE je možné zobrazovat i informace o tom, co se děje, tzv. log. Log je možné uložiť do súboru. Logovanie je vo východiskovom stave vypnuté.

Tento odstavec rozširuje informácie z predchádzajúceho bodu a je uvedený kvôli úplnosti. Bežný užívateľ sa ním nemusí nijako zaoberať.

Okrem vyššie spomenutých dvoch možností AbraOLE.exe a AbraOLELib.dll je k dispozícii ešte knižnica iAbraOLE.dll. Slouží k tomu, aby bylo možné používatAbraOLE přímo uvnitř systému ABRA Gen. Je to interné rozhranie poskytované systémom. Môže byť však využité len procesmi, o ktorých systém tzv. "vie" (čiže užívateľ ich na napojenie svojich doplnkov využiť nemôže). Interné iAbraOLE rozhranie je využité napr. na integráciu:

• vývojového a skriptovacieho rozhrania
• dll háčikov (v súčasnosti napr. pre cenotvorbu na mieru)

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")))
• nie je potrebné pri napojení riešiť prihlasovanie do systému, zisťovanie aktívneho užívateľa atď.
• atď.

Rámcová schéma dokumentujúca možnosti využitia otvoreného rozhrania. Doplnok exe napojený cez AbraOLELib.dll tvorí jeden proces, kým pri využití AbraOLE.exe je každé exe samostatným procesom (výhody a nevýhody viď vyššie).

Modrou sú znázornené napojenia cez interné rozhranie iAbraOLE. Interné rozhranie je možné použiť len pre procesy, o ktorých ABRA Gen "vie".

V obrázku je zakreslená i možnosť využitia interného iAbraOLE na napojenie externej aplikácie. V tomto prípade išlo o externé riešenie workflow M/Team bridge napojeného na systém ABRA Gen. Od v.14.51 bola táto funkcionalita zrušená. Avšak v obrázku zostáva zakreslená, keďže je dobrým príkladom demonštrujúcim možnosti využitia interného iAbraOle.
Pri aplikácii Workflow je okrem napojenia cez interné rozhranie (označené ako A1) na porovnanie znázornené aj napojenie cez AbraOLE.exe (označené ako A2). Oboje je možné, ale interné napojenie je samozrejme výhodnejšie (výhody iAbraOle viď vyššie). Externá aplikácia pre workflow bola riešená integráciou priamo do systému ABRA Gen (to znamenalo, že variant užívateľského rozhrania externej aplikácie (tzn. variant MtbGUI.exe) bol integrovaný do ABRA Gen ako jedna z jeho agend ABRA Gen). Pri štarte agendy Worklfow bolo objektom externej aplikácie (MtbOleEngines) poskytnuté interné rozhranie iAbraOle a príslušný progpoint. Objekty externej aplikácie boli uspôsobené tak, že "dokázali" toto rozhranie akceptovať. Skripty, v ktorých boli definované vlastné scenáre workflow a ktoré riadili vlastné prechody zo stavu do stavu a vykonávanie súvisiacich akcií, boli realizované tak, že defaultne hľadali daný progpoint, a ak bol k dispozícii, využili napojenie cez 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 cez iAbraOLE teda bol aj rýchlejší.

Iným prípadom je napr. napojenie dll háčikov (DLLHooks, označené ako B). Externé dll môže obsahovať funkcie, ktoré pre vrátenie požadovaného výsledku potrebujú zistiť množstvo informácií, ktoré si môžu zistiť práve vďaka kontaktu cez iAbraOLE na bežiacu ABRA Gen.

Otvorené rozhranie podporuje ako prácu s pevnými položkami danými výrobcom, tak s definovateľnými položkami. Je teda možné prostredníctvom otvoreného rozhrania zadávať a opravovať aj definovateľné položky.

Prihlásiť sa prostredníctvom otvoreného rozhrania a používať ho môžu iba užívatelia, ktorí majú pridelené privilégium Otvorené rozhranie, prípadne privilégium Supervisor.

V rámci OLE sa aplikujú práva k objektom a ak je v OLE aplikácii použité aj "vizuálno" systému ABRA Gen, tak aj práva k funkciám. V opačnom prípade sa práva k funkciá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. Inak mu nebude povolené túto akciu vykonať.

V tejto časti je uvedených niekoľko poznámok týkajúcich sa práce s otvoreným rozhraním.

Na využitie metód UpdateValues(), CreateNewFromValues() atď.

Typicky ide o prípad opravy dokladu cez otvorené rozhranie - tzn. načítanie existujúceho dokladu cez otvorené rozhranie cez GetValues, oprava a uloženie cez UpdateValues.

Sú zavedené nasledovné pravidlá:

• Naplnenú inštanciu triedy ObjectData je možné uložiť metódou UpdateValues() iba vtedy, ak bola inštancia ObjectData vytvorená vyvolaním GetValues(). Po vyvolaní UpdateValues() je inštancia ObjectData označená a ďalšie vyvolanie UpdateValues() s touto inštanciou ObjectData vyvolá výnimku.
• Taktiež po vyvolaní CreateNewFromValues() je inštancia ObjectData označená a jej použitie pri vyvolaní UpdateValues() vyvolá výnimku. No vyvolať CreateNewFromValues() s jednou inštanciou ObjectData je každopádne možné.
• Pri ukladaní sa vo vrstve otvoreného rozhrania kontroluje ObjVersion. Síce ide o duplicitnú kontrolu (problém by "odchytila" databáza), ale predídeme časovo náročnému pokusu o uloženie.

K poradiu hodnôt, v ktorom sa plnia položky pri niektorých objektoch:

Typicky ide o prípad, kedy sa chce cez otvorené rozhranie zadať nový PV, a na riadku zadávať TAmount a TAmountWithoutVAT (defaultne je spôsob zadávania TAmountWithoutVAT a VATAmount). Spôsob zadávania čiastok na riadky je možné v hlavičke nastaviť, ale tomu je potrebné prispôsobiť aj poradie, v ktorom sa uložia položky riadkov (pokiaľ by sa položky v riadkoch uložili v inom poradí, došlo by interne k nežiaducemu prepočtu).

Nakoľko pri niektorých objektoch záleží na poradí hodnôt, v ktorom sa plnia, sú zavedené nasledovné pravidlá:

• Pri plnení hodnôt do inštancií triedy ObjectData sa pamätá, v akom poradí sa do jednotlivých vlastností zapisovali hodnoty. Do Business objektovABRA Gen sa potom hodnoty odovzdávajú v rovnakom poradí, takže by nemal nastať problém s ukladaním vlastností.
• Do Business objektov sa odovzdávajú iba tie hodnoty, ktoré boli skutočne zmenené. Napr. pokiaľ sa pri oprave zmení iba dátum, tento jediný dátum sa pošle do BO.
• Poradie, v ktorom boli dáta modifikované, ktoré sa zohľadňuje pri ukladaní dát do objektu sa uplatňuje nielen pri jednoduchých položkách, ale aj pri položkách typu kolekcia a vlastnené objekty.
• Pozor! Pri nových objektoch je poradie aktualizácie nastavené vyvolaním PrefillValues(). Z toho vyplýva, že poradie je potom dané podľa definovanej štruktúry v BO, takže pozor. Keď do takto predvyplnenej inštancie ObjectData začneme zapisovať svoje dáta, poradie aktualizácie hodnôt do BO sa bude samozrejme meniť.

Na zadanie firmy resp. prevádzky na doklad

Aby bolo možné cez OLE vystavovať doklady (také, ktoré majú firmu a prevádzku) sú k dispozícii dva postupy:

• Prvou možnosťou je, že zadáte firmu a prevádzkareň sa nenastavuje. Potom musí byť nastavený parameter Predvypĺňať firemné prevádzky vo Firemných nastaveniach na hodnotu Áno.
• Druhá možnosť je, že sa zadá firma, z firmy sa získajú prevádzky, jedna sa vyberie a nastaví na doklad. Do dokladu sa potom vlastnosti nastavujú v poradí firma, prevádzkareň. Globálny parameter predvypĺňať prevádzky nemusí byť v tomto prípade nastavený na Áno.

Prepnutie na iné spojenie

AbraOLE.exe umožňuje vytvoriť viac objektov Application, pričom každý môže byť pre iné spojenie. 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ýsledok:" & CRLF
while not mDataset.EOF
mStdOut.WriteLine "asa"
'' mStdOut.Write mDataset.FieldByName("ID") & " "
mDataset.Next
wend

Parametre pre číselníky (filter pre číselníky)

Cez otvorené rozhranie je možné používať niektoré funkcie číselníka. Za týmto účelom sa do číselníkov môžu odovzdávať parametre pre filtrovanie. Týmito parametrami je možné číselník filtrovať podľa určitého zoznamu kľúčových hodnôt, ktorým sa rovná kľúč nadefinovaný v DynSQL alebo výraz daného kľúča.

• '@' ['!'] Výraz_klíče = dtString
  Filtr podle výrazu klíče (typicky Výraz klíče = Název položky (Field)). Pokiaľ je pred výrazom uvedený znak '!', tak sa do výberu zaradia záznamy, pre ktoré hodnota parametra neplatí.
• '@#' ['!'] Výraz_klíče = dtString
  Řetězec s hodnotami oddělenými středníky, které lze vybrat. Pokiaľ má byť filter typu "množina hodnôt alebo nevyplnené", je v ňom potrebné uviesť 2x znak ; (Napr. @#ReservedForDoc_ID=1000000101;;). Pokiaľ je uvedený znak '!' (pred alebo za znakom #), tak sa do výberu zaradia záznamy, pre ktoré hodnota parametra neplatí.
• '@@' ['!'] Klíč = dtString
  Filtr podle jména (názvu) klíče. Pokiaľ je pred kľúčom uvedený znak '!', tak sa do výberu zaradia záznamy, pre ktoré hodnota parametra neplatí.
• '@@#' ['!'] Klíč = dtString
  Řetězec s hodnotami oddělenými středníky, které lze vybrat. Pokiaľ je uvedený znak '!' (pred alebo za znakom #), tak sa do výberu zaradia záznamy, pre ktoré hodnota parametra neplatí.

Takže:

@Výraz_kľúča=Hodnota1
@#Výraz_kľúča=Hodnota1;Hodnota2
@@Názov_kľúča=Hodnota1
@@#Názov_kľúča=Hodnota1;Hodnota2

Pre negáciu:

@!Názov_poľa=Hodnota1  
@#!Názov_poľa=Hodnota1;Hodnota2;; // Hodnota nesmie byť žiadna z uvedených ani nesmie byť nevyplnená
@@!Názov_kľúča=Hodnota1;Hodnota2
@@#!Názov_kľúča=Hodnota1;Hodnota2 // Hodnota nesmie byť žiadna 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)
' Doplnenie filtračných parametrov
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

Ďalší príklad viď popis Parametrov užívateľsky definovateľných položiek typu číselník. Tu sú uvedené i niektoré ďalšie aj tu použiteľné parametre ako napr. _Allowed, _Excluded.

Externým OLE aplikácie majú k dispozícii aj možnosť vyvolať tlač a export pomocou tlačových zostáv resp. definovateľných exportov definovaných v systéme ABRA Gen.

Vďaka tomu je možné o. i. napr.:

• automaticky vytlačiť doklad po jeho vytvorení externou aplikáciou (napr. pomocou online čítačky čiar. kódov)
• zostavovanie a rozosielanie automatických reportingov (napr. automatické rozosielanie upomienok, potvrdenia objednávok, …)
• generovanie exportov alebo sád exportov v pravidelných časoch
• a mnohé ďalšie.

Vyvolanie z OLE rozhrania podporuje podobné možnosti tlačí a exportov ako sú pri vizuálnom klientovi (tlač s ponukou číselníka zostáv, priama tlač s náhľadom, priama tlač bez náhľadu, export s ponukou číselníkov exportov, export s priamym vytvorením súboru s možnosťou prednastaviť ponúkané voľby na výber exportu, atď.), viď tiež Tlače resp. Exporty. Konkrétny popis príslušných metód viď dokumentácia (viď Ako vyvolať nápovedu - GenDoc.chm).

V rámci instalace ABRA Gen je dodáván doplněk pro aplikaci Excel NxTurnover.xla. Ide o jednu z možností, ako sa dajú získavať výstupné účtovné prehľady.

Ide o doplnok do MS Excel, ktorý funguje podobne ako NxABRA.xla pre účtovné výkazy, len s tým rozdielom, že funguje on-line nad dátami systému ABRA, tzn. pripája sa prostredníctvom ABRA OLE a načítava dáta on-line (podľa zadaných parametrov). (NxABRA.xla číta dáta z predpripravenej dátovej kocky). Viď Účtovné výkazy - vecný obsah.

• Výhody: on-line, lze omezit za střediska, zakázky, obchodní případy, ...
• Nevýhody: oproti výstupom s využitím dátovej kocky pomalšie, musí byť k dispozícii bežiaci systém ABRA, užívateľ musí mať dostatočnú licenciu a prístup. práva na otvorené rozhranie.

NxTurnover.xla disponuje funkcemi NxTurnover, NxTurnoverSimple a NxReal. Tieto funkcie sa pripoja prostredníctvom OLE rozhrania na systém ABRA a vracajú obraty z účtovníctva na základe odovzdaných parametrov.

• Funkcia NxTurnover vracia obraty z účtovného denníka a voliteľne aj z účtovných žiadostí. Má parametre Účet, Dátum od, Dátum do, Stredisko, Zákazka, Obchodný prípad a Projekt a príznaky, či sa majú tieto veličiny započítavať aj s podriadenými ako zvláštne parametre a či sa majú započítavať aj účtovné žiadosti. Zodpovedá metóde GetTurnover objektu BookEntry z OLE.
• Funkcia NxTurnoverSimple vracia obraty z účtovného denníka a z účtovných žiadostí. Má len dátumy od a do a ostatné obmedzenia sa zadávajú tretím parametrom vo forme reťazca. Pozor! Oddelenie jednotlivých podmienok (parametrov) nesmie obsahovať medzeru! Zodpovedá metóde GetTurnoverSimple objektu BookEntry z OLE.
• Funkcia NxReal vracia obraty z účtovného denníka a z účtovných žiadostí. Má parametre Účet, Dátum od, Dátum do, Stredisko, Zákazka, Obchodný prípad a Projekt, ale na rozdiel od NxTurnover neumožňuje nastaviť, že sa tieto veličiny majú započítavať vrátane podriadených (započítavajú sa vždy bez podriadených (hodnota "Vrátane podriadených" je vždy false) a neumožňuje nastaviť, že sa nemajú započítavať žiadosti (vždy sa započítavajú). Zodpovedá zjednodušenej metóde GetTurnover objektu BookEntry z OLE.

Zároveň je dodávaný aj súbor NxTurnoverExample.xls, ktorý demonštruje použitie funkcií.