GWKB2035 : Using ExecuteGlobal to Include VBScript Code

Product: Window-Eyes
Author: Aaron Smith
Date Added: 08/16/2013
Last Modified: 08/16/2013

Many programming languages include the ability to include external code to make common code tasks available without having to re-type the code every time you want to use it. Although VBScript lacks an explicit method of including external code files, or code snippets, the ExecuteGlobal statement can be used to provide this missing functionality.

ExecuteGlobal executes a string of VBScript code in a script's global namespace, meaning that the executed code will be available anywhere in the script. Variables, sub routines and functions can be included in the executed string, and their respective declarations will be available any time you need them throughout the rest of your code.

Let's take a look at some examples.

Example 1 - Including a Simple Code Snippet

A code snippet, in the context of ExecuteGlobal, refers to a string of code (simple or complex) rather than an entire, external VBScript file.

Dim result : result = 0
Dim a : a = 5
Dim b : b = 10
ExecuteGlobal "result = a + b"
Speak result

In this example, the code snippet is the string following the ExecuteGlobal statement. After reading through the previous lines of code, what value do you think the variable result will contain? Let's examine each line, and see what happens.

Dim result : result = 0

This line declares a variable named result, and sets its initial value to 0.

Dim a : a = 5

This line declares a variable named a, and sets its initial value to 5.

Dim b : b = 10

This line declares a variable named b, and sets its initial value to 10.

ExecuteGlobal "result = a + b"

This is the line that does the work by executing the string of code. The string says, "let result equal the value of a plus b." Since a is equal to 5, and b is equal to 10, result would contain the addition of the two values: 15. ExecuteGlobal is nothing more than a VBScript statement saying, "Do the stuff inside this string," which would in fact set the result variable equal to the sum of a plus b (again, 15).

Speak result

The final line of this example causes Window-Eyes to speak the value contained in the result variable, which as we know now to be 15.

While it may make more sense to simply use result = a + b (or even more concise, Speak a + b), this example does demonstrate how ExecuteGlobal executes the code inside of a string.

Example 2 - Including a Complex Code Snippet

The usefulness of ExecuteGlobal is apparent when including more complex structures, such as a sub routine.

Dim subStr : subStr = "Sub HelloWorld() : MsgBox ""Hello World!"" : End Sub"
ExecuteGlobal subStr

If you were to run a script including these two lines, what would you expect to happen? If you said nothing, you would be correct. Well, nothing obvious, that is. Although you receive no verbal indication that the code executed successfully, ExecuteGlobal did what it was told to do; it executed the code inside of the string provided. In this example, ExecuteGlobal executed a sub routine called HelloWorld, and now a HelloWorld sub exists for use throughout the rest of the script. At any time, we could say:

HelloWorld

to display a message box containing the text "Hello World!" If you attempted to call HelloWorld without first using ExecuteGlobal to execute the string containing the sub routine, you would get an error, because the sub routine HelloWorld does not exist until ExecuteGlobal causes the string to get executed.

Example 3 - Including an External File

While including code snippets is certainly useful (the GW Toolkit script provides a complex string for setting up script error reporting for use with ExecuteGlobal), the true power of being able to execute external code comes in the way of including external VBScript files.

Lets say you have a script called myfunctions.vbs which includes several functions you find useful when developing scripts. Rather than re-typing, or copying and pasting those functions every time you want to use them, you can use ExecuteGlobal to execute the functions in the global namespace of your current script.

Dim fsObj : Set fsObj = CreateObject("Scripting.FileSystemObject")
Dim vbsFile : Set vbsFile = fsObj.OpenTextFile("myfunctions.vbs", 1, False)
Dim myFunctionsStr : myFunctionsStr = vbsFile.ReadAll
vbsFile.Close
Set vbsFile = Nothing
Set fsObj = Nothing
ExecuteGlobal myFunctionsStr

Let's examine each of these lines to see how the external VBScript file was included.

Dim fsObj : Set fsObj = CreateObject("Scripting.FileSystemObject")

This line declares the fsObj variable, and sets its value to a FileSystemObject object (an object provided by the operating system used to manipulate directories and files) created with the CreateObject method.

Dim vbsFile : Set vbsFile = fsObj.OpenTextFile("myfunctions.vbs", ForReading)

This line declares the vbsFile object, and sets its value to an object (a TextStream object, to be precise) returned by the OpenTextFile method of the FileSystemObject object (which was previously stored in the fsObj variable). The parameter ForReading indicates that we're interested in obtaining the contents of the file (instead of writing contents to the file).

Dim myFunctionsStr : myFunctionsStr = vbsFile.ReadAll

This line declares the myFunctionsStr variable, and sets its value to the contents of the file stored in the vbsFile object using the TextStream object's ReadAll method.

vbsFile.Close

This line closes the file that we opened. It is very important to remember to close files that are opened so that they don't become locked, and inaccessible in the future.

Set vbsFile = Nothing

This line releases the memory that the vbsFile variable was using. We don't need this object anymore as we've already stored the contents of the file in another variable.

Set fsObj = Nothing

This line releases the memory that the fsObj variable was using. We don't need this object anymore as we're done reading from our external file.

ExecuteGlobal myFunctionsStr

Once again, ExecuteGlobal does the work by executing the contents of the myFunctionsStr string, which at this point contains the entire contents of our external myfunctions.vbs file. Now the variables and functions that reside in the myfunctions.vbs file are included in memory, accessible from any point in the script. For example, perhaps you have a function called OSVersionNumber, which contained the major and minor build numbers of the operating system, along with the installed service pack version number. Prior to using ExecuteGlobal, you would have had to re-type, or copy and paste the entire OSVersionNumber function in your current script. Having executed the contents of your external file containing the function, however, you can now access the function as if it existed in your script explicitly, by doing something like:

If OSVersionNumber < 12.34.5 Then
   MsgBox "Operating System Not Supported"
End If