VBScript/en

Introduction

VBScript-Code in expecco

This plugin allows for Visual Basic Script (VBScript) actions to be created, edited, imported and executed in expecco. VBScript actions are useful to access Windows OLE/COM objects or to create lightweight user interfaces.

Be aware, that VBScript requires a Windows machine; this means that using this may lock you into the Windows world, and your suite may no longer execute correctly under Linux or OSX.

For import and execution, the plugin uses the Windows executable "ScriptClient.exe", which is part of the expecco VBScript plugin package and technically addressed via the .NET-Bridge.

Settings

The settings contains the path of the ScriptClient program. By default, this is:

  plugin\vbScript\ScriptClient\ScriptClient.exe

under the expecco installation folder.

In addition, you can define a so called "scope", which makes importing of scripts easier. If set, only that part of the file system will be shown in the import window.

The checkbox "Delete External Files" tells if imported scripts can be removed from the file system after being imported. This is mostly useful if scripts are coming from a generator or from an export mechanism of another program (e.g. SAP).

Working with VBScript

The following describes typical interactions with the plugin. The plugin's menu is found under "Plugins" → "Bridges" → "VBScript".

Connecting

Before a script can be imported or executed, expecco needs to be connected to a ScriptClient. The "connect"-option is found in the menu.

The ScriptClient can run either on the local or on a remote machine. Because it is a proprietary Windows program, it must run on either a Windows machine, a virtual machine running Windows or in an emulator, such as Wine. The connection is done via a .NET-bridge; therefore, expecco itself can run on any system which supports .NET (this includes Linux or OSX).

In case of a local connection, the ScriptClient will be automatically started by expecco, when the first VBScript action is executed.

For a remote connection, the ScriptClient must be already running and started either manually, or via a script or via "autoexec.bat" on the remote machine. Command-line arguments for startup are:

Argument	Description
-port <int>	The TCP-port to be used for the connection.
-mode <server/client>	Run the .NET-bridge either as TCP-server or TCP-client.
-keepAlive <true/false>	true if the ScriptClient should continue to run after a connection breakdown.

Defining/Editing VBScript Actions

VBScript actions can be created/edited/executed like other bridged actions vie the tree menu or the tree's quick create buttons. Right click in the tree and select "New Action" - "Script" - "Visual Basic Script".

Importing VBScript Actions

Import-Dialog

Open the import-dialog via the plugin's menu (found in the "Extensions" menu). It presents folders and VBS-files (*.vbs) of the Host, on which the ScriptClient is running.

The source code of a selected script is shown in a preview window. The script can be imported or executed via the context menu (right-click on a script file), or via the buttons in the preview window.

Accessing Input Pin Values

When the script is executed, input pin values can be referred to with "%x%" or $(x) sequences⁽¹⁾, where "x" is the pin name.
For example, if there are three input pins, named "param1", "param2" and "param3", of type integer,integer,string, a code sequence using those values would be:

op1 = %param1%
op2 = %param2%
WScript.StdOut.Writeline("Param3 is " & %param3%)
WScript.StdOut.Writeline("Adding " & op1 & " and " & op2 & " gives " & (op1+op2))

if called with input pins frozen to 11 (integer), 22 (integer) and "bla" (string), the script will generate the two lines:

Param3 is bla
Adding 11 and 22 gives 33

If there is an output pin named "stdout", the output will appear there (linewise), otherwise, the output appears on the Transcript, if the corresponding settings flag ("Show Stdout on Transcript") is set (see "Showing stdin/stderr on the Transcript" in the general script documentation).

When importing, the stdout pin is automatically created, otherwise you can create one via the action's context menu in the schema editor ("Special Pins" - "Create Stdout Pin").

Note (1):
for historical reasons, previous expecco versions used "%x%" in VBScript actions but "$(x)" in shell and other script languages. This was a mistake and might lead to confusion. Therefore, VBScript supports both; %-notation to be backwaqrd compatible and $-notation for consistency among script languages.

Writing to Output Pins

This feature is new in the 22.1 version; previous versions did not support output pins with VBScript.

Output pin values are generated by writing special escape-sequenced strings to the stderr stream (as with any script action). For example, assuming there is a pin named "result" (with type integer), the statement:

Wscript.StdErr.WriteLine(":out:result:42")

will generate the integer value 42 at that pin. To write a computed value, construct the string using the "&" operator:

value = 84 / 2
Wscript.StdErr.WriteLine(":out:result:" & value)

There is one difference to other script actions: because stderr is read from the VBScript interpreter only at the very end of the action, all output writes will be performed at the end of the execution. It is therefore not possible to generate values for triggering other actions while the script is executing. All writes will be effective en-bloque at the end (i.e. all outputs are always and implicitly buffered output pins)

Generating Log Entries / Reporting Failures

This feature is new in the 22.1 version.

Write one of the special patterns to the stderr:

Wscript.StdErr.WriteLine(":logInfo:" & "this is an info message")
Wscript.StdErr.WriteLine(":logWarning:" & "this is a warning message")
Wscript.StdErr.WriteLine(":logError:" & "this is an error message")
Wscript.StdErr.WriteLine(":logFail:" & "this is a failure message")

A logError or logFail will make the action be marked as unsuccessful; however, the action continues execution (i.e. the error/fail will be reported at the end of the action's execution)

Changes w.r.t. Previous Versions

Before 22.1, VBScript actions which generated ANY string to stderr where considered to be failing. This was changed in order to support output pin writing and log-entry generation.

In case your existing scripts depend on this, please change the code to use one of the above "logFail/logError" patterns (i.e. prepend ":logError:" in front of your message).

Executing

When executed, a VBScript-block behaves like any other action block in expecco. Of course, a ScriptClient needs to be present (and in case of remote execution already running). Obviously, the ScriptClient must run on a Windows machine (or inside a virtual guest machine, running Windows).

Examples

Simple examples are found in the "testSuites/examples/vbScript" subfolder under the expecco installation folder.

---

Copyright © 2014-2024 eXept Software AG