COM Interfaces

Ein Interface im Sinne von COM beschreibt die Eigenschaften (Properties) und Methoden, welche ein COM Objekt zur Verfügung stellt.

Beachten Sie, dass die Beispiele in Visual Basic for Applications (VBA) geschrieben sind. Um dieselben Beispiele als Vertec-interne Scripts (VBScript) zu verwenden, müssen z.B. alle Typangaben bei Deklarationen (dim) entfernt werden, da VBScript keine Objekttypen unterstützt.

Beispiel VBA Syntax:

dim leistungen as IVtcObjectList

Beispiel VBScript Syntax:

dim leistungen

IVtcSession

Dies ist das Standard-Interface des Vertec COM Servers. CreateObject("Vertec.App") bzw. die VBScript Variable vertec liefert als Ergebnis eine IVtcSession Referenz. Ausgehend von IVtcSession können andere Objekte angefordert werden (Anmerkung: Bis zur Vertec Version 5 hat dieses Interface Tim.App geheissen. Es handelt sich dabei um die gleiche Referenz).

EigenschaftBeschreibung
ArgObject property vom Typ IDispatch. Liefert das zur Zeit aktuelle Objekt (aktueller Eintrag) in Vertec. Dies ist der Eintrag, welcher im aktiven Fenster von Vertec als Haupteintrag ausgewählt ist, bzw. der Eintrag in der Liste, von dem aus der Aufruf erfolgt. Der eigentliche Typ des zurückgegebenen Interfaces entspricht dem Typ des aktuellen Objekts. Für die meisten Vertec Objekte, welche kein spezielles Interface haben, wird IVtcObject zurückgegeben.
User property vom Typ IDispatch. Liefert den aktuell eingeloggten Benutzer als COM Objekt (Interface).
Eval(expression as string) function vom Typ Variant.

Diese Funktion wertet eine beliebige OCL-Expression aus. Das Ergebnis wird als Variant zurückgegeben und kann je nach OCL-Expression als String, Integer, Float, Boolean oder Object interpretiert werden. Beispiel:

dim list as IVtcObjectList
Set list = vertec.Eval("projektbearbeiter->select(aktiv)")

liefert eine IVtcObjectList mit allen Vertec Bearbeitern, welche als aktiv markiert sind.

EvalToVariable(root as IVtcObject, expression as string, varname as string)

Damit können Werte in Variablen geladen werden, die dann global von überallher in OCL-Expressions verwendet werden können. Insbesondere können Ergebnisse von Expressions, welche nur durch die Expression entstehen und nicht in Vertec vorhanden sind, in eine Variable geschrieben werden (beispielsweise das Ergebnis einer Summierung, ein Datumswert mittels encodedate etc.)

Zum Beispiel sollen in einem Excel-Report die Leistungen ab einem bestimmten Zeitpunkt angezeigt werden. Statt nun die Leistungen in der Art "offeneLeistungen->select(datum >=" & encodeDate(2008, 08, 01) & ") " zusammenzusuchen, kann zuerst eine Variable gesetzt und dann verwendet werden:

Vertec.EvalToVariable Vertec.argobject, "encodeDate(2008,08,01)", "varVon"

und dann in OCL verwendet:

offeneLeistungen->select(datum >= varVon)

Die Expression wird auf dem angegebenen Root-Objekt ausgewertet. Es kann also auch eine Expression der Art:

Vertec.EvalToVariable Vertec.argobject, "projekt.rechnungen->reject(proforma)", "xArgObject"

angegeben werden.

SetObjVariable(Variablenname, Wert)

Setzt eine Objektvariable in OCL. Auf diese kann anschliessend global in OCL-Expressions via Variablenname zugegriffen werden. Beispiel:

Vertec.SetObjVariable "myProjekt", proj

anschliessend OCL auf Liste von offenen Leistungen:

self->select(projekt=myProjekt)->size

Der Unterschied zu EvalToVariable (siehe oben) besteht darin, dass hier einfach ein Objekt übergeben wird, ohne Auswertung einer Expression.

CreateObject(classname as string) function vom Typ IDispatch. Erzeugt ein neues Objekt in Vertec. Als Parameter muss der Klassenname des Objekts übergeben werden. Als Ergebnis liefert die Funktion eine Interface-Referenz des neu erzeugten Objekts.
GetWithSQL(className as string, SQLWhere as string, SQLOrder as string)

Liefert das Ergebnis einer SQL-Abfrage auf einer bestimmten Vertec Klasse. Das heisst es werden per SQL alle Objekte einer bestimmten Klasse nach den angegebenen Kriterien (SQL Select, Where Clause) ausgewählt und in einer Liste zurückgegeben.

Vorsicht: Eval mit einer OCL-Expression lädt alle zu ihrer Berechnung notwendigen Objekte aus der Datenbank. In gewissen Fällen kann dies zu Performance-Problemen oder grossem Memory-Bedarf führen. Für Abfragen aus grossen Mengen gleicher Objekte ist GetWithSQL vorzuziehen.Im Gegensatz zu Eval werden nur die der SQL-Bedingung entsprechenden Objekte aus der Datenbank geladen. Beispiel:

dim list as IVtcObjectList
Set list = vertec.GetWithSQL("adresseintrag", "name like 'isel%'","name")

GetPlugin(name as string) function vom Typ IDispatch. Liefert das Interface eines Plugins.
ExecutePlugin(name as string, arg as variant, raiseexception as boolean) funcion vom Typ Variant. Erlaubt es, ein bestimmtes Plugin auszuführen.

ExecuteFileReport
(templatepath As String,
rootObj As IVtcObject,
[optarg As IVtcObject],
[filename As String],
[subject As String],
[text As String],
[linkToRoot As Boolean = Falsch], [linkToOptarg As Boolean = Falsch],
[showWord As Boolean = Wahr]) As Object

Diese Funktion erlaubt es, einen Office-Report aufzurufen. Dabei muss der Pfad angegeben werden (templatepath) sowie das Vertec Objekt, aufgrund dessen der Report aufgerufen werden soll (rootObj). Die anderen Parameter sind optional; zu beachten ist, dass optarg mit "nothing" angegeben werden muss und nicht einfach leer gelassen werden kann.

Argumente:

  • templatepath: Pfad zur Vorlage.
  • rootObj: Das Vertec Objekt, für das der Report ausgeführt werden soll.
  • optarg: Entspricht der optionalen Adresse auf dem Druckdialog. Optionales Argument. Wenn nicht verwendet, Parameter mit nothing angeben.
  • filename: Speicherpfad des neu erzeugten Dokuments. Optional. Ist ein Filename angegeben, wird das Dokument gespeichert, sonst nicht. Die Verknüpfung (linkToRoot und linkToOptarg) kann nur erfolgen, wenn ein Filename angegeben ist.
  • subject: Entspricht dem Betreff auf dem Druckdialog. Optional.
  • text: Entspricht dem Kommentar auf dem Druckdialog. Optional.
  • linkToRoot: Verknüpft das Dokument mit dem Hauptobjekt (Häkchen "auf Hauptobjekt" auf dem Druckdialog). Optional. Standard: Nein. Die Verknüpfung kann nur erfolgen, wenn ein Filename (filename) angegeben ist.
  • linkToOptarg: Verknüpft das Dokument mit der (optionalen) Adresse (Häkchen "auf Adresse" auf dem Druckdialog). Optional. Standard: Nein. Die Verknüpfung kann nur erfolgen, wenn ein Filename (filename) angegeben ist.
  • showWord: Öffnet das erstellte Dokument im Word und zeigt es auf dem Bildschirm an. Optional. Standard: Ja.

Der Aufruf in einem Skript ist beispielsweise wie folgt:

dim dok
dim root
set root = Vertec.argobject
set dok= Vertec.ExecuteFileReport("C:\Programme\Vertec\Reports\Deutsch\Rechnung.dot", root, nothing)

Der gesamte Aufruf mit allen Parametern wäre wie folgt:

set dok = Vertec.ExecuteFileReport("C:\Programme\Vertec\Reports\Deutsch\Rechnung.dot", root, nothing, "", "", "", False, False, True)

Das Dokument wird dann in der Voransicht angezeigt. Soll es direkt ausgedruckt werden, kann an obiges Script folgende Zeile angehängt werden:

dok.PrintOut

UpdateDatabase

Schreibt alle nicht gespeicherten Daten in die Datenbank. Speichert Änderungen in die Datenbank und validiert neuerstelle Objekte. Diese sind, sofern sie keine Regeln verletzen, danach nicht mehr ungültig.

Vertec.UpdateDatabase

GetExtension(name: string) function vom Typ IDispatch. Liefert das Interface einer Extension.
Translate(string) function vom Typ string. Übersetzt den String anhand der aktuell eingestellten Sprache mit Hilfe der MLD Übersetzungstabelle.
SetResourcePlanValue(bearbeiter, projekt, phase, datum, intervalTyp, value) Ab Vertec Version 5.7.0.16. Ermöglicht das Setzen von Ressourceplanwertenvia Script.
  • intervalTyp: 0 = Tag, 1 = Woche, 2 = Monat
  • value: Wert in Minuten.
  • datum: Es wird die Periode mit dem Value gefüllt, in der das Datum ist. Am besten nimmt man das Datum am Anfang der Periode, dann gibt es keine Unklarheiten.
ShowForm(objekt)

Methode zum Aufrufen des Detailfensters des als Argument übergebenen Vertec-Objekts.

Wird diese Methode in einem Script verwendet, gilt es zu beachten, dass sich mit dem Aufruf des Detailfensters das argobject, also das aktuelle Objekt in Vertec, ändert.

Beispiel:

set obj = vertec.eval("projekt->first")
vertec.showform obj

CreateList (Klassentyp) Erstellt eine neue leere Liste für Einträge des angegebenen Typs. Damit kann in VBA weitergearbeitet werden.
Login(user, passwort): boolean Meldet einen Benutzer an. Gibt true zurück, falls das Login erfolgreich war, und false, falls irgendetwas schief gegangen ist (Passwort falsch etc.)
BeginSystemContext / EndSystemContext Schaltet Vertec innerhalb dieser beiden Befehle auf erweiterte Berechtigungen. Kann via COM nur angewendet werden, wenn Vertec mit dem Parameter /SUPER gestartet wurde und der Administrator eingeloggt ist. Sonst führt der Aufruf zu einem Fehler.
DisableEvents / EnableEvents Schaltet das Eventscript System vorübergehend aus (siehe: Event Scripts). Kann via COM nur angewendet werden, wenn Vertec mit dem Parameter /SUPER gestartet wurde und der Administrator eingeloggt ist. Sonst führt der Aufruf zu einem Fehler.
HasGui: boolean

Ab Vertec 5.6. Im Vertec Webserver dürfen Scripts keine Dialoge anzeigen, sonst bleibt der Webserver hängen. Damit via Script herausgefunden werden kann, ob es auf dem Server läuft, gibt es das HasGui Attribut.

Bei Webserver gibt HasGui False zurück, bei einem normalen Client True.Der Aufruf erfolgt via: vertec.eval("timsession->first.hasgui")

ProcessMessages

Ab Vertec 5.5. Ruft Vertec dazu auf, seine Windows Messages Queue abzuarbeiten. Der periodischer Aufruf von ProcessMessages kann ein Problem mit langlaufenden Excel-Reports lösen: Der Excel Report wird von Vertec via COM-Aufruf (Excel.Application.Run) gestartet. Dieser Aufruf kehrt erst zurück, wenn das Report Makro in Excel durchgelaufen ist. Wenn diese lange dauert (z.B. 20 min und mehr) dann bricht der Report manchmal mit einem COM Error ab. Das Problem wird gelöst, wenn im Excel Report Makro periodisch an geeigneter Stelle

Vertec.ProcessMessages

aufgerufen wird. Der Aufruf sollte alle paar Minuten erfolgen.

msgbox (prompt, [buttons], [titel]): integer

Ab Version 5.8. Zeigt eine msgbox an und ist aufgebaut wie die Standard msgbox Funktion von Visual Basic (VB).

  • prompt: String, der die Meldung enthält.
  • Buttons: optional. Ein Integer-Wert mit der gleichen Bedeutung wie in der VB Standard msgbox Funktion.
  • Titel: optional. String für den Fenster-Titel der MessageBox.

Der Rückgabewert gibt an, welcher Button geklickt wurde. Dies ist ein Integer-Wert mit der gleichen Bedeutung wie in der VB Standard msgbox Funktion.

Die Argumente Helpfile und Context der Standard-MsgBox-Funktion werden nicht unterstützt.

Eine detaillierte Beschreibung finden Sie im Artikel msgbox/inputbox: Beschreibung der Parameter.

inputbox (titel, prompt, defaultvalue): String

Zeigt einen Dialog mit Titel, Prompt-Text und Eingabefeld mit Defaultwert an.

Gibt den eingegebenen Wert zurück. Falls Abbrechen gedrückt, wird ein Leerstring zurückgegeben.

Eine detaillierte Beschreibung finden Sie im Artikel msgbox/inputbox: Beschreibung der Parameter.

IVtcObject

Dies ist das Standard-Interface für alle Vertec Objekte. Für gewisse Objekte sind detaillierte Interfaces definiert (z.B. Projekt, Rechnung, etc.). Diese erben vom IVtcObject, d.h. die Eigenschaften und Funktionen von IVtcObject sind auf allen Objekt-Interfaces vorhanden.

Für den Zugriff auf ein Vertec Objekt via IVtcObject sind weitere Informationen über den Aufbau des Objekts nötig, wie z.B. die Namen der Member.

EigenschaftBeschreibung
Member(membername: string)

array property vom Typ Variant. Liefert oder setzt ein bestimmtes Member eines Vertec Objekts. Ein Member kann ein Attribute (zahl, string, boolean) oder ein Link (Objekt oder Objektliste) sein. Beispiel:

dim obj As IVtcObject
....
name = obj.Member("name")

AsString property vom typ string. Liefert die String Representation des Objekts. Die String Representation ist eine kurze Charakterisierung des Objekts als String, z.B. bei einer Person Vorname und Name.
ClassName property vom typ string. Liefert den Klassennamen des Objekts, z.B. "Projekt", "Person" etc.
MemberCount property vom typ string. Liefert die Anzahl Members eines Vertec Objekts.
Zusatzfeld(zusatzfeldname as string)

array property vom Typ string. Liefert oder setzt den Wert des Zusatzfeldes mit dem entsprechenden Namen als String. NULL Werte entsprechen dabei dem Leerstring "". Bei Auswahlzusatzfeldern wird der String Wert verwendet. Beispiel:

dim obj as IVtcObject
....
wert = obj.zusatzfeld("name")

ZusatzfeldAsVariant
(zusatzfeldname as string)
array property vom Typ string. Liefert oder setzt den Wert des Zusatzfeldes als Variant. Bei Abfragen wird dabei der Typ des Zusatzfeldes als Variant geliefert. Bei Auswahlzusatzfeldern wird der Integer Wert verwendet. Falls ein Zusatzfeld den Wert NULL hat, so wird der Defaultwert für den Feldtyp geliefert (Zahlen 0 bzw. 0.00, String "").
Delete function (ohne Rückgabewert). Löscht das Objekt in Vertec. Liefert einen Fehler, wenn der eingeloggte Benutzer keine Berechtigung zum Löschen hat.
Eval(expression as string)

function vom Typ Variant. Wertet eine OCL-Expression auf dem Objekt aus. Im Unterschied zu IVtcSession.Eval wird versucht, die Expression aufgrund des Objekts zu berechnen. Beispiel:

dim obj as IVtcObject

PLZ = obj.Eval("defaultadresse.adresse.plz")

IsOfType(className as string)

function vom Typ boolean. Gibt an, ob das Objekt vom angegebenen Typ ist. Beispiel:

dim obj as IVtcObject

if obj.IsOfType("Adresseintrag") then
msgbox "Ist ein Adresseintrag"
end if

if obj.IsOfType("Person") then
msgbox "Ist sogar eine Person"
end if

EvalAsString(expression as string) function vom Typ string. Dasselbe wie Eval, ausser dass immer die String Representation des Ergebnisses geliefert wird.
MemberWithSql(membName:string; sqlWhere: string; sqlOrder: string) IVtcObjectList. Erlaubt es, bei persistenten Multilink Members mittels SQL Filter nur eine Auswahl der verknüpften Objekte zu laden.
DefaultInterface() IDispatch. Liefert bei Objekten mit speziellen Interfaces dieses, sonst IVtcObject.
LinkTo(target: IVtcObject; rolle: string) Macht eine Vertec Verknüpfung (via Linktyp) zum übergebenen Objekt mit der angegebenen Rolle.
Unlink(target: IVtcObject; rolle: string) Entfernt eine Verknüpfung zum übergebenen Objekt mit der angegebenen Rolle.
UnloadObject Entfernt das Objekt aus dem Vertec Objektspeicher. Muss mit Vorsicht verwendet werden, da anschliessende Zugriffe auf das entladene Objekt zu Fehlern führen können.
SetMemberOutOfDate
(membername as string)

Die Methode setzt ein bestimmtes Member "out of date", so dass bei dem nächsten Zugriff erneut auf die Datenbank zugegriffen wird und so der aktuelle Wert drin stehen sollte.

Anwendungsfall: bei selbstgebauten Nummergeneratoren vor dem Zugriff auf ein Member "SetMemberOutOfDate" aufrufen, dann z.B. eins hochzählen, dann sofort "UpdataDatabase" aufrufen, so ist die Wahrscheinlichkeit klein, dass 2x die gleiche Nummer vergeben wird.

Ab Version 5.6 Neu kann die Methode auch auf derived Attributen benutzt und damit eine erneute Berechnung ausgelöst werden, ohne dass sich etwas geändert hat (wie das sonst bei derived Attributen der Fall ist).

Will man zum Beispiel das Member Rechnung.PhasenAufRechnung von dem erneuten Zugriff neu berechnen lassen, erfolgt der Aufruf wie folgt:

Rechnung1.SetMemberOutOfDate "phasenaufrechnung"

ScriptExecute(scripttext, argobject=Nothing) Ermöglicht den Aufruf eines Vertec Scripts.
    • scripttext: Als Scripttext wird der eigentliche Code übergeben. Dies kann zum Beispiel der Text eines in Vertec registrierten Scripts oder aber auch ein Codetext selbst sein.
    • argobject: Mit diesem Parameter können Sie das Objekt angeben, auf dem das Script ausgeführt werden soll. Wird dieser Parameter weggelassen, wird das Script auf dem aktuellen Vertec-Objekt aufgerufen.

Dim Vertec As IVtcSession
Dim Script As IVtcObject
Dim Scripttext As String

Set Vertec = CreateObject("Vertec.App")
Set Script = Vertec.Eval("scripteintrag->select(bezeichnung = 'Projekt kopieren')->first")
Scripttext = Script.Member("scripttext")
Vertec.ScriptExecute (Scripttext)

GetMLValue(membername, language)

Die sogenannten Multilanguage-Attribute (mehrsprachige Attribute) können über diese Methode angesteuert werden (ab Version 5.4).

  • Membername: Name des Members
  • Language ist der jeweilige Languagecode (DE, FR, IT, EN).
Multilanguage-Attribute sind:
  • Taetigkeit.Text
  • Spesentyp.Text
  • Auslagetyp.Text
  • Zusatzfeldklasse.Bezeichnung (Bezeichnung von Zusatzfeldern)
  • GridColDef.Titel (Spaltentitel in Listeneinstellungen)

Beispiel

taetigkeit.GetMLValue("text", "DE") = "Fahrtspesen"

Wird das Member wie bisher abgefragt, entspricht der Rückgabewert der aktuellen Sprache:

taetigkeit.Member("text") = "Fahrtspesen"

    IVtcObjectList

    Alle Listenergebnisse (z.B. Rückgabewerte von Eval, Member etc.) werden durch ein IVtcObjectList Interface dargestellt.

    EigenschaftBeschreibung
    Count property vom Typ integer. Anzahl Objekte in der Liste.
    Objects(index as integer) array-property vom Typ IDispatch. Liefert unter Angabe eines Index ein Objekt aus der Liste. Beispiel:
    dim kommList as IVtcObjectList
    dim obj as IVtcObject

    ...weise Adresseintrag zu
    Set kommList = obj.Member("kommmittel")

    for i = 0 to kommList.count-1 do
    msgbox kommList.Objects(i).AsString
    next i
    Add(objekt as IVtcObject) function(ohne Rückgabewert). Fügt ein Objekt in die Liste ein. Falls es sich bei der Liste um ein Link-Member eines Vertec Objekts handelt, dann wird effektiv eine neue Verknüpfung erzeugt.
    Remove(objekt as IVtcObject) funcion (ohne Rückgabewert). Entfernt ein Objekt aus der Liste. Falls es sich bei der Liste um ein Link-Member eines Vertec Objekts handelt, wird effektiv eine Verknüpfung gelöscht.
    RemoveByIndex(index: integer) Entfernt ein Element aufgrund seines Indexes.
    AddList(list: IVtcObjectList) Fügt die übergebene Liste der aktuellen Liste hinzu.
    IndexOf(objekt as IVtcObject) property vom Typ integer. Gibt die Position des angegebenen Objekts in der Liste an. 0-basiert, falls nicht enthalten = -1.
    Includes(objekt as IVtcObject) property vom Typ boolean. Gibt an, ob ein Objekt in der Liste vorhanden ist.
    Eval(expression as string) function vom Typ Variant. Wertet die angegebene OCL Expression auf der Liste aus.
    EvalAsString(expression as string) function vom Typ Variant. Gleich wie eval, das Ergebnis wird als String zurückgegeben.

    Weitere Interfaces

    Die anderen Klassen wie ITimRechnung werden nur benutzt, wenn man spezielle Funktionen aufrufen will, z.B. bei Rechnung das "verbuchen" oder das "stornieren".

    Folgende Interfaces sind verfügbar. Sie haben die Funktionen und Eigenschaften von IVtcObject sowie zusätzlich folgende Methoden implementiert:

    InterfaceMethoden
    IAktivitaet SetPfad
    ITimAuslage MakeOffen, MakeVerrechnet
    ITimBearbeiter StartTimer, StopTimer
    ITimLeistung MakeOffen, MakeVerrechnet, UpdateSatz
    ITimRechnung Buchen, CreateBeleg, ImportZahlungen, MakeOffen, MakeVerrechnet, ManipulateToOriginalState, ManipulateToTotalBetrag, SetTotal, Stornieren
    ITimSpesen MakeOffen, MakeVerrechnet
    ITimWaehrung GetKursTo

    Anmerkung: Auf diesen konktreten Klassen könnten die einzelnen Eigenschaften auch direkt verwendet werden. Da sie aber vor allem aus Rückwärts-Kompatibilitätsgründen vorhanden sind, empfehlen wir, die Eigenschaften immer auf dem IVtcObject über .member oder .eval aufzurufen.


    26.06.2003 | 27.06.2016: Hinweis auf argobject bei ShowForm eingefügt.
    Produktlinien: Standard, Expert
    Module: Leistung & CRM