ERCC (http://eriedel.info)

VTOOL.EXE: description


Overview

VTOOL (VTOOL.EXE) is a COM module by ERCC, written to support Windows scripting (esp. VBS). It provides a few visual components such as a list selection and some functions to use profiles (.ini files). Sample usage can be seen with the script for backup copying (bakcopy.zip), which initially was the cause for writing VTOOL.

As a COM module VTOOL.EXE has to be registered once, which can simply be done by invoking the program file. (Conversely this registration should be undone before removing VTOOL.)
Running

vtool /?

will show possible arguments.
VTOOL was created with classic Visual Basic thus requiring the VB runtime files (MSVBVM60.DLL and others) which are included with all Windows versions since Windows 2000 but also available as download (see below).
The current VTOOL version 1.3 (03.2015) provides the following objects.


Objects

Clipboard

This object allows to copy text to and from the Windows clipboard, simply using its property Text.
The sample demonstrates usage with the involvement of Windows editor Notepad.

Set CLP = CreateObject("vtool.Clipboard")
CLP.Text = "A text is a text is a text." & vbNewLine
MsgBox "You now can insert and modify the clipboard text ...", _
        , "starting NOTEPAD"
Set WSS = WScript.CreateObject("WScript.Shell")
WSS.Run "notepad", , vbTrue
MsgBox CLP.Text, , "clipboard text:"

DriveList

DriveList provides a list of currently available drives (drive letters) where the user can select one. The function (method) Selection(default, title) opens a listbox window and returns the selected drive specification (drive letter with colon).
Use the argument default to preselect a valid drive specification.
The optional argument title can be used to define the window's caption.

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

Note: Most often drives are not listed with their respective labels. The above-mentioned backup script contains statements (commented out) that use FileSystemObject functions together with the List object to create a different drive list.

EventLog

This object can be applied to record events. It creates informational entries either in the Windows application event log or in a log file. (Because this object is based on the corresponding functionality of Visual Basic, it doesn't provide all the capabilities of Windows event logging.) So VTOOL supplements WshShell's LogEvent method.

The properties File and Mode optionally determine the target place for event recording. File specifies a log file (which is a text file) for output. Mode can be given the following values:

0 (default) The output destination depends on Windows. For all NT-based versions this is the system's event log, otherwise it's a log file.
1 Output is written to Windows event log. VBRunTime will indicate the application source and VTOOL —along with the given text— will be part of the event description.
2 Output is written to a log file. If File doesn't define a file name, the name vtool.log will be used. If no path is specified, the file will be created in the WINDOWS folder.

The function Report(text, type) logs an event with text as (trailing) part of the description. An empty string will produce an error.
The optional parameter type can define one of the following event types:

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

The EventLog.Report and WshShell.LogEvent methods are quite similar in use and results:

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"

The event description created by LogEvent is more straightforward and clear. The application source here is WSH (Windows Script Host).

Additionally VTOOL can accomplish logging to a text file. The file will be created if it doesn't exist. New entries are appended to the end. Note that date and time values are not included automatically. So if you want them to be recorded, you have to pass them with the log text. And the same goes for the application name.
The following example uses a log file in the current folder and creates a log entry. The user-defined part of the text is separated by a line break.

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 & _
            " This is a new record for our log file."
End With

List

This is the generalized form of a list box window where the user can select items.
Selection(items, default, title) opens a list box window and returns the selected item(s). If the user cancels the selection, an empty string is returned.

List entries are defined by a single string items with newline characters as delimiters. When dividing the items the function will ignore empty parts.
Use the optional argument default as a zero-based index to initialize a selection.
The optional argument title defines the window's caption.

By default the property MultiSel is False (0) and only a single list entry can be selected. The setting True allows the selection of multiple entries. In this case the selected items are again newline-separated parts of the returned string.

abc = "alpha" & vbNewLine & "beta" & vbNewLine & "gamma" ' & vbNewLine
Set obj = CreateObject("vtool.List")
var = obj.Selection(abc, , "Choose your letter")

Me

This object gives some details about the current VTOOL process. The following properties can be read:
About holds a brief program information, hInstance is the handle of the process instance (module), Path returns the program's directory, and ThreadID is the thread identifier of the current thread.

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

Because it's often easier and more suitable to use a simple .ini file ("INI") for storing parameters, this object provides somewhat basic profile functionality, giving the opportunity to read and write values (strings).

The property File specifies a file to be used as an initialization file. The file name must be defined before any subsequent access. If the file does not exist, VTOOL immediately raises an error. (This is because the underlying Windows API function otherwise doesn't reliably indicate profile errors.)

Use GetValue(section, key) to read a key's value, and GetSection(section) to read all values of the given profile section. GetSection returns a single string where the items are delimited by newline characters and can easily be splitted (see the backup copy script mentioned above).

Set obj = CreateObject("vtool.Profile")
With obj
    .File = "sample.ini"
    var1 = .GetValue("department-1", "entry-1")
    var2 = .GetSection("department-2")
End With

The function SetValue(section, key, entry) writes a single key entry (string) into the specified section of the defined INI file, creating the section if necessary.
The function returns the boolean value of the API function, where a nonzero value indicates success. Some —not all— failures are indicated by the return value zero (0, False), e.g. a write-protected INI file.
The following sample shows how to start with a new INI file:

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("chapter", "alphabet", "abc")

Window

To facilitate continuous text output VTOOL provides a simple modeless window. Of course using such a window is reasonable only during prolonged procedures. Keep in mind that the script execution doesn't stop. For a pause use MsgBox, WScript.Sleep, or the like.

Create(title) creates (shows) an empty austere window. The optional argument defines the window's caption, which also can be accessed with the Title property.
Calling the function WriteLine(text) prints (appends) a new line of text inside the window's client area. This is of no effect if the window isn't created.
The properties WriteSize and WriteBold can be used to set (change) the respective font attributes. The size is specified in points and can take a value between 6 and 36, the default is 10. The bold style is determined by a boolean value, False as default. Note that these settings affect the entire text.
Cls() clears all text output. Remove() removes the window.

Set obj = CreateObject("vtool.Window")
obj.Create
obj.Title = "This is a text output window"
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 "Let's have a break here ...",, "VTOOL-WINDOW"
obj.Remove
Set obj = Nothing

Because the display of text output is restricted to the visible window's area, parts of longer text may be hidden. While it is possible to resize the window if the script pauses, there's no way of scrolling the content. The Window2 object, described subsequently, provides an optional scroll bar.

Window2

This object is similar to Window, except that it uses a (read-only) edit control with an optional scroll bar for displaying text. To enable scrolling, set the property Scroll to True before creating the window. This will add a vertical scroll bar.
The example uses this feature to display a text file.

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 "Content of " & TEXTFILE
Do While Not file.AtEndOfStream
    win.WriteLine file.ReadLine
Loop
file.Close
MsgBox "Okay!",, win.Title
win.Remove

Note: Although text display is read-only, it still features a text cursor (caret), and the user can select text for copying.


Usage in scripts etc.

Please consider that VTOOL's variables are typed, while those in client environments may not. Within VBScript, for example, all data is of type Variant. So it may be necessary to cast a variable to the specific data type before passing it to VTOOL:

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


License, Notes

VTOOL is provided as freeware and "as is" without any warranty or liability. Of course, suggestions for improvements are welcome.


Download

The file   vtool.zip contains VTOOL.EXE along with this description (VTOOL.CHM).

The aforementioned VB runtime files are normally included with Windows. Furthermore Microsoft provides an installation program, that you can download here if needed. For whatever reasons, this program is wrapped into another self-extracting executable. (Just to simplify things, the unpacked program file vbrun60sp6.exe is available here.)
 

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


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


link to info overview