ERCC (http://eriedel.info)

VTOOL.EXE: Beschreibung


Übersicht

VTOOL (VTOOL.EXE) ist ein COM-Modul von ERCC, entwickelt, um Windows Scripting (insb. VBS) zu unterstützen. Es bietet einige visuelle Benutzerkomponenten, z.B. eine Listenauswahl, und Funktionen für den Zugriff auf INI-Dateien. Eine beispielhafte Verwendung findet sich im VB-Script für Datensicherungskopien (BakCopy), welches ursprünglich auch den Anlass darstellte, VTOOL zu schreiben.

Die aktuelle VTOOL-Version 1.3.2 (02/2017) stellt die nachfolgend beschriebenen Objekte zur Verfügung.


Objekte

Clipboard

Mit diesem Objekt kann Text von und zu der Zwischenablage (Clipboard) von Windows kopiert werden. Hierzu wird einfach die Eigenschaft Text verwendet.
Das folgende Beispiel demonstriert dies unter Beteiligung des Windows-Texteditors Notepad.

Set CLP = CreateObject("VTool.Clipboard")
CLP.Text = "Ein Text ist ein Text ist ein Text." & vbNewLine
MsgBox "Sie können den Zwischenablage-Text nun einfügen und ändern ...", _
        , "Aufruf von NOTEPAD"
Set WSS = WScript.CreateObject("WScript.Shell")
WSS.Run "notepad", , vbTrue
MsgBox CLP.Text, , "Zwischenablage-Text:"

DriveList

DriveList erzeugt eine Liste aktuell verfügbarer Laufwerke (Laufwerksbuchstaben), in der der Benutzer eine Auswahl treffen kann. Die Funktion Selection(default, title) öffnet ein Listbox-Fenster und liefert die ausgewählte Laufwerksspezifikation (Buchstabe mit Doppelpunkt) zurück.
Verwenden Sie den Parameter default um eine gültige Laufwerksbezeichnung vorzugeben.
Mit dem optionalen Argument title kann ein Fenstertitel definiert werden.

Set obj = CreateObject("VTool.DriveList")
var = obj.Selection("D:")

Anmerkung: Vielfach werden Laufwerke ohne die jeweiligen Bezeichnungen (Labels) aufgelistet. Das oben erwähnte Datensicherungs-Script enthält (auskommentierte) Anweisungen, die FileSystemObject-Funktionen zusammen mit dem List-Objekt verwenden, um eine alternative Laufwerksliste zu erzeugen.

EventLog

Dieses Objekt kann für die Aufzeichnung besonderer Ereignisse (Events) verwendet werden. Es erzeugt wahlweise Einträge in das Windows-Ereignisprotokoll oder in eine Logdatei. (Dem Objekt liegt die entsprechende Funktionalität von Visual Basic zugrunde, daher sind leider nicht alle Möglichkeiten der Windows-Protokollierung verfügbar.) VTOOL ergänzt somit die LogEvent Methode des WshShell-Objekts.

Durch die Eigenschaften File und Mode lässt sich optional steuern, wo die Protokollierung erfolgen soll. File spezifiziert eine Logdatei (Textdatei) für die Ausgabe. Für Mode können folgende Werte angegeben werden:

0 (default) Das Ausgabeziel wird abhängig vom Betriebssystem festgelegt. Normalerweise erfolgt die Ausgabe in das Windows-Ereignisprotokoll, auf nicht-NT-basierten Versionen (Windows 95/98/me) hingegen in eine Logdatei.
1 Die Ausgabe erfolgt in das Windows-Ereignisprotokoll. Dabei werden VBRunTime als Anwendungsquelle und VTOOL (sowie der übergebene Text) als Bestandteil der Beschreibung eingetragen.
2 Die Ausgabe erfolgt in eine Logdatei. Wurde kein Dateiname unter File bestimmt, so lautet die Bezeichnung vtool.log. Ist kein Speicherpfad definiert, so wird die Datei im WINDOWS-Verzeichnis erstellt.

Die Funktion Report(text, typ) protokolliert ein Ereignis, wobei text als abschließender Teil der Beschreibung gespeichert wird. Bei Übergabe eines leeren Strings erzeugt VTOOL einen Fehler.
Der Parameter typ ist optional und kann einen der folgenden Werte annehmen:

vbCritical (16)
vbExclamation (48)
vbInformation (64)

Die Methoden EventLog.Report und WshShell.LogEvent sind in Anwendung und Ergebnis ähnlich:

Set obj = CreateObject("VTool.EventLog")
obj.Report "Log-Entry created by VTOOL", vbInformation
Set obj = CreateObject("WScript.Shell")
obj.LogEvent 1, "Log-Entry created by WShell"

LogEvent erzeugt dabei die einfachere und übersichtlichere Ereignisbeschreibung, als Anwendungsquelle wird WSH (Windows Script Host) eingetragen.

Mit VTOOL kann zusätzlich die Protokollierung in eine Textdatei durchgeführt werden. Diese Logdatei wird erforderlichenfalls erzeugt und um neue Einträge ergänzt. Beachten Sie, dass Datums- und Zeitwerte hierbei nicht automatisch hinzugefügt werden, so dass Sie diese selbst mit dem Protokolltext übergeben müssten. Entsprechendes gilt für die Programm- oder Anwendungsbezeichnung.
Das folgende Beispiel legt eine Logdatei im aktuellen Verzeichnis fest und erzeugt einen Protokolleintrag. Der benutzerdefinierte Textteil wird dabei durch einen Zeilenumbruch abgesetzt.

Set obj = WScript.CreateObject("WScript.Shell")
var = obj.CurrentDirectory
If Right(var, 1) <> "\" Then var = var & "\"
Set obj = CreateObject("VTool.EventLog")
With obj
    .Mode = 2
    .File = var & "vtool-test.log"
    .Report vbNewLine & "TESTSCRIPT " & Now & _
            " Dies ist ein neuer Eintrag für die Logdatei."
End With

List

Mit diesem Objekt steht die allgemeine Form eines Listbox-Fensters, bei dem der Benutzer Listeneinträge auswählen kann, zur Verfügung.
Selection(items, default, title) öffnet ein Listbox-Fenster und gibt die Listenauswahl (String) zurück.
Die Einträge der Liste werden durch einen einzelnen String items definiert, in dem sie durch Zeilenumbruch-Codes getrennt sind. Bei der Auswertung werden leere Teilstrings nicht berücksichtigt.
Eine Vordefinition der Auswahl ist durch das optionale Argument default möglich, welches einen 0-basierenden Index darstellt.
Mit dem gleichfalls optionalen Argument title kann der Fenstertitel festgelegt werden.

abc = "alpha" & vbNewLine & "beta" & vbNewLine & "gamma" ' & vbNewLine
Set obj = CreateObject("VTool.List")
var = obj.Selection(abc, , "Auswahl eines Buchstaben")

Ist die Eigenschaft MultiSel False (0, Voreinstellung), so kann nur ein Eintrag markiert werden. Mit der Einstellung True ist die erweiterte Auswahl mehrerer Einträge möglich. Eine Vordefinition ist in diesem Fall wirkungslos. Erfolgt eine Mehrfachauswahl, so sind die selektierten Listeneinträge wiederum durch Zeilenumbruch-Codes begrenzt.

var = "Love means never having to say you're sorry."
var = Replace(var, " ", vbNewLine)
Set obj = CreateObject("VTool.List")
obj.MultiSel = vbTrue
var = obj.Selection(var, , "Auswahlliste mit so Wörtern")
Set obj = Nothing
MsgBox var

Wurde die Auswahl vom Benutzer abgebrochen, wird ein leerer String zurückgegeben.

Me

Dieses Objekt liefert einige Angaben zum laufenden VTOOL-Prozess zurück. Folgende Eigenschaften können gelesen werden:
About enthält eine kurze Programminfo, hInstance den Wert für das Instanz-Handle, Path das Programmverzeichnis und ThreadID den Wert der Thread-ID.

Set obj = CreateObject("VTool.Me")
WScript.Echo "About = " & obj.About
WScript.Echo "Path = " & obj.Path
WScript.Echo "hInstance = " & obj.hInstance
WScript.Echo "ThreadID = " & obj.ThreadID
Set obj = Nothing
WScript.Quit (0)

Profile

Da es oft einfacher und passender ist, für die Speicherung von Parametern eine simple INI-Datei zu verwenden, stellt VTOOL mit diesem Objekt die entsprechenden Grundfunktionen bereit, so dass damit Werte (Strings) gelesen und geschrieben werden können.

Die Eigenschaft File erhält den Dateinamen, um eine INI-Datei für nachfolgende Zugriffe festzulegen. Die verwendete Datei muss existieren, VTOOL erzeugt ansonsten einen Fehler bei der Zuweisung. (Dies geschieht, weil die zugrunde liegende Windows-API-Funktion Dateifehler nicht gerade verlässlich anzeigt.)

Benutzen Sie GetValue(section, key), um einen Schlüsselwert zu lesen, und GetSection(section), um alle Werte des angegebenen Abschnitts zu erhalten. GetSection liefert einen String zurück, wobei die einzelnen Werte durch Zeilenumbruch-Codes getrennt sind und so leicht ausgewertet werden können.

Set obj = CreateObject("VTool.Profile")
With obj
    .File = "sample.ini"
    var1 = .GetValue("Abschnitt-1", "Eintrag-1")
    var2 = .GetSection("Abschnitt-2")
End With

Mittels SetValue(section, key, entry) kann ein einzelner Eintrag in die vorbestimmte INI-Datei geschrieben werden, wobei erforderlichenfalls auch der Abschnitt angelegt wird.
Die Funktion liefert den boolschen Wert der API-Funktion zurück, bei einem Versagen also den Wert 0 (False), was offenbar nur unter ganz bestimmten Umständen auftritt (z.B. bei schreibgeschützter INI-Datei). Wenn die INI-Datei unbestimmt ist, liefert die API-Funktion keinen Fehler!
Um mit einer neuen INI-Datei zu beginnen, könnten Sie etwa wie folgt vorgehen:

profile = "C:\Apps\xtest.ini"
Set obj = CreateObject("Scripting.FileSystemObject")
Set obj = obj.CreateTextFile(profile, True)
obj.Close
Set obj = CreateObject("VTool.Profile")
obj.File = profile
var = obj.SetValue("kapitel", "alphabet", "abc")

Window

Für fortlaufende Textausgaben enthält VTOOL das Objekt eines schlichten, nicht-modalen Fensters. Die Verwendung solcher Fenster macht natürlich nur Sinn, wenn Anzeigen während länger dauernder Vorgänge erfolgen sollen. Zudem ist zu beachten, dass die Script-Ausführung hierbei eben nicht pausiert. Dies wäre durch MsgBox, WScript.Sleep o.ä. zu veranlassen.

Create(title) erzeugt ein Fenster, das optionale Argument gibt den Fenstertitel an. Dieser lässt sich ferner über die Eigenschaft Title ändern und lesen.
Mit der Funktion WriteLine(text) wird eine neue Textzeile ausgegeben. Dies bleibt ohne Auswirkung, wenn das Fenster nicht erzeugt ist.
Mit den Eigenschaften WriteSize und WriteBold lassen sich die entsprechenden Schriftattribute festlegen (ändern). Die Größe wird in Punkt im Wertebereich von 6 bis 36 angegeben, voreingestellt ist 10. Der Schriftstil (fett) wird über einen booleschen Wert True/False bestimmt, mit letzterem als Vorgabe. Beachten Sie, dass diese Einstellungen auf den ganzen Text wirken.
Cls() löscht alle bisherigen Textausgaben. Remove() entfernt das Fenster.

Set obj = CreateObject("VTool.Window")
obj.Create
obj.Title = "Das ist ein Textfenster"
obj.WriteLine "ABC, easy as: one, two, three"
obj.WriteLine "Or simple as: Do Re Mi"
obj.WriteLine "ABC, one, two, three, baby, you and me!"
MsgBox "Hier halten wir an ...",, "VTOOL-WINDOW"
obj.Remove
Set obj = Nothing

Da die Anzeige des Textes auf den sichtbaren Fensterbereich beschränkt ist, können Teile einer umfangreicheren Textausgabe verborgen sein. Zwar ist es möglich, das Fenster zu vergrößern, wenn das Script pausiert, der Inhalt kann jedoch nicht verschoben (»gescrollt«) werden. Das nachfolgend beschriebene Objekt Window2 bietet einen optionalen Scroll-Balken.

Window2

Dieses Objekt entspricht Window, verwendet zur Textanzeige jedoch eine Textbox (edit control, nur lesbar) mit einer optionalen Bildlaufleiste (scroll bar). Um diese zu aktivieren, setzen Sie die Eigenschaft Scroll auf True bevor Sie das Fenster erzeugen. Hierdurch wird eine vertikale Bildlaufleiste hinzugefügt.
Im Beispiel wird auf diese Weise eine Textdatei angezeigt.

Const TEXTFILE = "C:\Data\sample.txt"
Set file = CreateObject("Scripting.FileSystemObject")
Set file = file.OpenTextFile(TEXTFILE, 1, 0, -2)
Set win = CreateObject("VTool.Window2")
win.Scroll = True
win.Create "Inhalt von " & TEXTFILE
Do While Not file.AtEndOfStream
    win.WriteLine file.ReadLine
Loop
file.Close
MsgBox "Okay!",, win.Title
win.Remove

Anmerkung: Obwohl die Textanzeige nur lesbar ist, also nicht bearbeitet werden kann, weist sie dennoch eine Einfügemarke (»Text-Cursor«) auf, und es lässt sich Text markieren und kopieren.


Verwendung in Scripts etc.

Berücksichtigen Sie bitte, dass VTOOLs Variablen typisiert sind, während dies auf Variablen von Client-Umgebungen nicht zutreffen muss. In VBScript beispielsweise existiert nur der Datentyp Variant. Es kann daher erforderlich sein, einer Variable vor der Übergabe an VTOOL einen spezifischen Typ zuzuweisen:

Set obj = CreateObject("VTool.Window")
obj.Create
obj.WriteLine CStr(VariableX)


Lizenz/Hinweise

VTOOL wird als Freeware und »so wie es ist« zur Verfügung gestellt. Die Überlassung erfolgt also unentgeltlich und für beliebige Verwendungszwecke, aber auch ohne jede Gewährleistung oder Haftung. Verbesserungsvorschläge sind natürlich willkommen.


Download, Installation

Die Datei  vtool.zip enthält VTOOL.EXE zusammen mit dieser Beschreibung (VTOOL.CHM).

Zur Installation genügt es, den Inhalt der Archivdatei in ein prinzipiell beliebiges Verzeichnis zu entpacken.
Als COM-Modul muss VTOOL einmal entsprechend registriert werden, was sich einfach durch Programmaufruf erledigen lässt. (Umgekehrt sollte diese Registrierung vor der Entfernung von VTOOL wieder aufgehoben werden.)
Der Aufruf

vtool /?

zeigt hierzu die möglichen Programmparameter.
Beachten Sie, dass für die Registrierung in aller Regel Administrationsrechte erforderlich sind. Die empfohlene Vorgehensweise besteht darin, ein Konsolenfenster (»Eingabeaufforderung«) als Administrator zu öffnen und darin den Befehl

vtool.exe /regserver

bzw. für die Deregistrierung

vtool.exe /unregserver

einzugeben.

VTOOL erfordert die VB6-Laufzeitdateien, die normalerweise in Windows enthalten sind (zudem auch als Download verfügbar).
 

http://eriedel.info/files/vtool/vtool.html


ERCC (http://eriedel.info)  2013 - 2017   © Erhard Riedel Computer Consulting (ERCC)

 

Link zur ERCC-Hauptseite   Link zur Info-Übersicht