Adding VBScript to Your VB Applications

Overview

By now, it should be clear that VBScript is useful in many contexts within Windows. Not surprisingly, along with a variety of different technologies, Microsoft provides yet another component capable of supporting VBScript-the Script Control. This ActiveX control provides a simple way for your application written in Visual Basic (or any other language that supports ActiveX controls) to host its own scripting environment, allowing you, or your users, to customize the application.

In the past, programmers had to struggle to provide customizability to their projects, or pay license fees for other products such as Microsoft's portable VB variant, Visual Basic for Applications (VBA). In 1997, Microsoft released Windows Script Interfaces (WSI) as an interface to scripting engines, and eventually followed up with Script Control. Although WSI provides greater control over how your application interfaces with a scripting engine, WSI was intended for C++ programmers. The Script Control, on the other hand, is tailor made for Visual Basic (VB).

Why Add Scripting to Your Application?

Allowing customization of your application through scripting can open many opportunities-not only to you, the programmer (allowing you to change or customize your application's behavior without having to recompile and redistribute), but also to your end users, who will be able to do more with your application. The possibilities of scripting are almost endless, but, as usual, adding this capability to your application will require additional time and effort for design, coding, testing.

Adding scripting support to your application is most appropriate when you want to allow customization of the application from within-as opposed to from without. Adding customization from without is often what you really want. For example, consider Microsoft Excel, which offers customization through scripting both from within and from without. Customization of Excel from without comes from the fact that Excel exposes a public, COM-based programming interface that programmers in any other COM-enabled language (like Visual Basic or VBScript) can code against, all without even starting the Excel graphical interface. From within, however, you can add macros and VBA code that add customizations to the behavior of Excel from within Excel itself.

In your Visual Basic application, you can accomplish customization from without simply by creating ActiveX DLLs or EXEs that expose published interfaces. This technique does not necessarily require any additional coding or testing time, though you do need to design your program and segregate your code in a particular way in order to do it right. For many applications, this level of customization is all that is needed.

However, you can also, like Excel, offer customization from within by using the Script Control. There are different approaches to this, and you have to design the internals of your program (at least the parts you want to expose to scripting) a little differently than you are used to. In this chapter we will discuss these techniques and introduce a freely downloadable sample Visual Basic projects that implements the Script Control.

Macro and Scripting Concepts

Before we dig into the details of the Script Control, it is helpful to conceptualize how the Script Control can be used inside an application. There are two approaches: first, using externally stored 'scriptlets' that are executed at certain times for very targeted purposes; and second, exposing whole sections of an application to customization and automation through scripting. In both approaches, you have the option of sharing some or all your application's internal object model with your application's hosted scripts.

Both approaches are similar in that your application gives up control over some portion of its logic or functionality to scripts that are loaded at runtime as opposed to being compiled into your application. They are different primarily in terms of scope. Let's look at two examples.

As an example of the smaller scope approach, imagine an application that has a complex algorithm coded as a series of steps spread across several procedures and/or classes. Let's say this complex algorithm computes the amounts of a series of invoices over time, calculated based on a series of subformulas that have different inputs and outputs depending on the portion of the total invoice amount being computed. Lets say there are 10 subformulas required to compute the amount of one month's invoice. Imagine that nine of these formulas are static, meaning that they are the same in all cases and can therefore be hard coded.

However, one of the formulas is different based on the type of invoice. Sometimes the formula must work one way, sometimes another. Also, the company paying for this application adds new types of invoices all the time, each with unique requirements for this tenth formula. The company wants to be able to add new invoice types without having to add unique, hard-coded versions of this formula for each invoice type. They don't want to have to redeploy the application each time a new invoice type is added.

The application designers decide to use the Script Control to solve this quandary . They add a column called ForumlaScript to the InvoiceTypes table in the database. In this column they store 'scriptlets,' written in VBScript, that compute the result for this tenth subformula in a unique way for each invoice type. Each scriptlet is different based on the requirements for each invoice type. When the invoice amount calculation algorithm reaches the step for the tenth subformula it loads the appropriate scriptlet from the InvoiceType table and uses the Script Control to dynamically execute the scriptlet.

As you can see, in this first example, the application uses scripting capability for a very targeted purpose, adding just the necessary amount of customizability . In a larger scope example, a whole section of the application might be opened up for scripting and automation. The scripts used by the application might be more complex, like the Windows Script Host (WSH) and ASP scripts we've been looking at in this book. The scripts could have access to the entire object model of the hosting application, much in the way that the WSH and ASP engines expose objects like WScript and Server to the scripts they host.

This larger scope approach might be used to allow users to write their own macros to control the user interface of the application. Or the application might expose an object model that allows users to write and plug in their own scripts to generate reports .

Large scope or small scope, the possibilities are endless, and an application you are tasked with designing may or may not have a use for the Script Control at all. If you are trying to add customizability for your end users, then the Script Control may indeed be the best thing because you probably want to allow your users to create and edit scripts from within your application, and you have no control over how or which users to choose to add scripting to the application. Or maybe your application is deployed at the customer's site, and your deployment consultants (who may not be expert programmers) need the flexibility to customize the application on the spot, right when they are in the customer's office installing the application.

However, if you are trying to achieve a design that simply allows for 'plug in' components to ease deployment of bug fixes and new features into your production environment, upon further consideration of your design options, and perhaps a little research, you may decide that an object-oriented polymorphic design that utilizes interfaces and the class factory design pattern might be a better, more stable, and more predictable alternative.

That's a mouthful. Unfortunately, there is no room here to explain what we exactly mean by 'an object-oriented polymorphic design that utilizes interfaces and the class factory design pattern.' The point is that the Script Control is not the solution to every design problem. Consider carefully why you are thinking of using the Script Control. What requirements exactly are you trying to implement? You may find that another solution that achieves the same thing without some of the downsides of the Script Control, namely the fact that script code will almost always run slower than you application's native compiled code and that you do not have any control over syntax errors and poor programming practices that people might insert into the scripts.

Adding the Script Control to a VB Application

If you have not alreadydownload the Script Control you can download it from this address on the Microsoft Web site: http://msdn.microsoft.com/downloads/list/webdev.asp . The installation program automatically adds the control to your machine and registers it.

When you are ready (you might want to read ahead some first, and perhaps take some time to go through this chapter's downloadable sample project), the Script Control can be easily added to a VB project as an ActiveX control (attached to a form) or as a normal COM object that you declare and instantiate in code. In the former case, you would add the control to a form as normal from the Component Toolbox in the VB IDE. In the latter case, you would instead add a reference to the Script Control using the Project > References menu.

When you attach the control to a form, it is an invisible control. That means it does not add any visual properties to your form, much like the native Timer control you may have used before. Unlike the Timer control, which can only be used as a control attached to a form, the Script Control is not limited in this way. In fact, using the Script Control as an object rather than as a control attached to a form offers more flexibility, as demonstrated by the sample project discussed later in the chapter.

Script Control Reference

This middle part of the chapter is a complete reference for the Script Control, including the objects, collections, properties, methods , method syntax, and examples. After the reference, the chapter continues with some additional explanation, followed by an example Visual Basic application that makes use of the Script Control.

Object Model

The Script Control object model is illustrated in Figure 18-1. The details of these objects and their properties and methods are documented in the upcoming sections.

Figure 18-1

Objects and Collections

The Script Control component has several objects and collections (which are a special kind of multivalued object) that work together to provide a wide range of capabilities for adding scripts to a Visual Basic application. For each object and collection, we will describe the object in general; document its properties, methods, and events; and, where appropriate, provide example code.

ScriptControl Object

ScriptControl is the main element that enables scripting in an application. It provides a simple interface for hosting scripting engines such as VBScript or JScript. All of the other available objects depend on an instance of ScriptControl . ScriptControl can be instantiated in three different ways:

• Early bound, on a form (add it through the Components dialog)
• Early bound, through code (add it through the References dialog)
• Late bound (at any time)

Declaration Syntax

This is the syntax to declare an early bound variable for the ScriptControl object (this is preferred over the late bound syntax.).

DimPrivatePublic [WithEvents] objSC As [MSScriptControl.]ScriptControl

This is the syntax to declare a late bound variable for the ScriptControl object. A late bound variable will not be able to handle events. If using a late bound variable, the Script Control does not need to be referenced in the project.

DimPrivatePublic objSC [As ObjectVariant]

Properties

The properties of the ScriptControl object are described in the following table.

Methods

The methods of the ScriptControl object are described in the following table.

Events

The events of the ScriptControl object are described in the following table.

Examples

This line of code shows how to instantiate a new early bound Script Control object.

Set objSC = New [MSScriptControl.]ScriptControl

This line of code shows how to instantiate a new late bound Script Control object.

Set objSC = CreateObject("[MSScriptControl.]ScriptControl")

This script fragment shows how variables and procedures that are outside the scope of a procedure or function can be added in separate steps using the AddCode method. Entire procedures and functions should be added in one call.

strCode = "Option Explicit" & vbNewLine & vbNewLine objSC.AddCode strCode strCode = "Dim x, y" & vbNewLine & vbNewLine objSC.AddCode strCode strCode = "x = 15" & vbNewLine & "y = 2" objSC.AddCode strCode strCode = "Function MultiplyXY(): MultiplyXY = x * y : End Function" objSC.AddCode strCode

The Eval function allows you to execute code fragments at runtime. Eval is simple but effective, capable of achieving tasks nearly impossible in VB.

MsgBox objSC.Eval(InputBox$( _ "Enter Numeric Expression", _ "Eval Example", "5 * 3 - 1"))

Depending upon the type of a procedure, you may call the Run method in several different ways, depending on return values and parameters.

strCode = "Sub TwoArg(a,b): MsgBox CInt(a + b)" & " : End Sub" objSC.AddCode strCode objSC.Run "TwoArg", 1, 2 strCode = "Function ManyArg(a,b,c,d): ManyArg = a * b + c - d" strCode = strCode & ": End Function" objSC.AddCode strCode lngResult = objSC.Run("ManyArg", 1, 2, 3, 4)

The following script fragment illustrates the use of the Error event.

Private WithEvents objSC As ScriptControl Private Sub Main() Set objSC = New ScriptControl ... objSC.Run "MyProc" End Sub Private Sub objSC_Error MsgBox "Script error occurred:" & vbNewLine & _ "Number: " & objSC.Error.Number & vbNewLine & _ "Description: " & objSC.Error.Description & vbNewLine & _ "Line: " & objSC.Error.Line & vbNewLine & _ "Column: " & objSC.Error.Column & vbNewLine & _ "Script Text: " & objSC.Error.Text End Sub

The script following fragment illustrates the use of the Timeout event.

Private WithEvents objSC As ScriptControl Private Sub Main() Set objSC = New ScriptControl ... objSC.Timeout = 10000 objSC.Run "MyProc" End Sub Private Sub objSC_TimeOut MsgBox "The script has timed out." End Sub

Module Object

The Module object, a member of the Modules collection (see below), contains procedure, type, and data declarations used in a script. The Script Control has a default Global module, which is automatically used unless specific member calls are made to other modules that have been added. You can add code to a Module object using the AddCode method. Individual Module objects, on the other hand, are added by using the Add method of the Modules collection. Since the code in each module is private in scope to its module, you can repeat variable and procedure names across modules. This is useful when you have several similar scripts that are only partially different from each other.

Declaration Syntax

This is the syntax to declare a variable for a Module object.

DimPrivatePublic objModule [As [MSScriptControl.]ModuleObject]

Properties

The properties of the Module object are described in the following table.

Methods

The methods of the Module object are described in the following table.

Examples

The script following fragment illustrates the use of the Module.Run method to call a procedure contained in a module.

Set objModule = objSC.Modules.Add("NewModule") objModule.AddCode "Sub Test(): " & _ vbNewLine & vbTab & "MsgBox ""Hello, world.""" & _ vbNewLine & "End Sub" objModule.Run "Test"

The following script fragment illustrates the use of the Module.CodeObject to call code within the module. You may find that calling procedures this way is more natural, and perhaps more readable than using the ScriptControl.Run method since procedures are exposed as methods of the CodeObject object.

Set objModule = objSC.Modules.Add("TestMod") objModule.AddCode "Sub TestProc(): " & _ vbNewLine & vbTab & "MsgBox ""Hello, world.""" & _ vbNewLine & "End Sub" objModule.AddCode "Function TestFunction(a) : & _ vbNewLine & vbTab & "TestFunction = a * a " & _ vbNewLine & "End Function" Set objCodeObject = objModule.CodeObject objCodeObject.TestProc lngVal = objCodeObject.TestFunction(2)

This script fragment shows how variables and procedures that are outside the scope of a procedure or function can be added in separate steps. Entire procedures and functions should be added in one call.

strCode = "Option Explicit" & vbNewLine & vbNewLine objModule.AddCode strCode strCode = "Dim x, y" & vbNewLine & vbNewLine objModule.AddCode strCode strCode = "x = 15" & vbNewLine & "y = 2" objModule.AddCode strCode strCode = "Function MultiplyXY(): MultiplyXY = x * y : End Function" objModule.AddCode strCode

The Eval function allows you to execute code fragments at runtime. Eval is simple but effective, capable of achieving tasks nearly impossible in VB.

MsgBox objSC.Eval(InputBox$( _ "Enter Numeric Expression", _ "Eval Example", "5 * 3 - 1"))

Depending upon the type of a procedure, you may call the Run method in several different ways, depending on return values and parameters.

strCode = "Sub TwoArg(a,b): MsgBox CInt(a + b)" & " : End Sub" objSC.AddCode strCode objSC.Run "TwoArg", 1, 2 strCode = "Function ManyArg(a,b,c,d): ManyArg = a * b + c - d" strCode = strCode & ": End Function" objSC.AddCode strCode lngResult = objSC.Run("ManyArg", 1, 2, 3, 4)

Modules Collection

The Modules collection contains all the Module objects for a ScriptControl object, including the default Global module. Calls to the members of the Global module can be made directly through the ScriptControl object without iterating through the Modules collection. It also has an index matching the value of the constant GlobalModule .

Module objects can be added to the Modules collection using the Add method. Specific Module objects can be accessed through the default Modules.Item method. The Count property provides the number of Module objects in the collection. The entire collection can be iterated in various ways, most commonly using the For Each...Next loop. Since there is no way of deleting individual modules, you will have to use the Reset method of the ScriptControl object to delete unwanted modules, which clears the entire collection.

Properties

The single property of the Modules collection object is described in the following table.

Methods

The methods of the Modules collection object are described in the following table.

Examples

The following line of code shows how to access the Global module directly. The same syntax, using different module names, can be used with other named modules.

Set objModule = sc.Modules("Global")

The following script fragment illustrates how to iterate through the Modules collection.

For Each objModule In objSC.Modules strModuleList = strModuleList & vbNewLine & objModule.Name Next

Modules allow the use of separate scripts and provide separate namespaces. The following script fragment shows how two different modules can contain scripts with the same name.

' Add code to separate modules, using same sub names. Set objModule = objSC.Modules.Add("Maine") objModule.AddCode "Sub ShowState" & _ vbNewLine & vbTab & "MsgBox ""In Maine""" & _ vbNewLine & "End Sub" Set objModule = Nothing Set objModule = objSC.Modules.Add("Ohio") objModule.AddCode "Sub ShowState" & _ vbNewLine & vbTab & "MsgBox ""In Ohio""" & _ vbNewLine & "End Sub"

Procedure Object

The Procedure object defines a logical unit of code, which in case of VBScript can be either a Sub or a Function . The Procedure object contains a number of useful properties that allow us to inspect a procedure's name, the number of arguments, and whether or not the procedure returns any values. Entry to the script code is also provided via the Procedure object.

Declaration Syntax

This is the syntax to declare a variable for a Procedure object.

DimPrivatePublic objProc [As [MSScriptControl.]ProcedureObject]

Properties

The properties of the Procedure object are described in the following table.

Methods

The methods of the Procedure object are described in the following table.

Note that the Procedures collection does not have an Add method. New procedures are added to a module using the AddCode method; Procedure objects are created and added to the collection behind the scenes.

Procedures Collection

The Procedures collection holds all of the procedures in a given Module object. It provides a convenient way to iterate through all of the procedures in a module and access the code therein. Individual procedures are added through the Module object's AddCode method, not through the Procedures collection directly. Also, you can't remove an individual procedure once it has been added, as there is no Remove method on the Procedures collection.

Properties

The single property of the Procedures collection object is described in the following table.

Methods

The Procedures collection object does not have any methods.

Examples

The following script fragment iterates through the Procedures collection using the For Each loop syntax.

For Each objProcedure In objModule.Procedures strList = strList & "Name: " & objProcedure.Name strList = strList & vbNewLine & vbTab strList = strList & "Argument Count: " & objProcedure.NumArgs strList = strList & vbNewLine & vbTab strList = strList & "Has Return: " & objProcedure.HasReturnValue strList = strList & vbNewLine & vbNewLine Next

Error Object

The Error object provides information about syntax and runtime errors associated with the Script Control. Although information provided by the Error object is similar to that of the Err object in VB and VBScript, there are additional properties ( Column , Text , Line ) that are invaluable when diagnosing problems associated with the script. Although it is possible to declare and initialize the Error object in VB, it is common to access members of the Error object directly through the ScriptControl object.

Unlike the Err object, the Error object is not global in scope and only handles errors associated with a single instance of a ScriptControl object. The Error object is reset each time you change the ScriptControl.Language property, or when you call the Reset , AddCode , Eval , ExecuteStatement , or Clear methods of the ScriptControl object. Use the Clear method to explicitly reset the Error object properties. Runtime errors handled internally by the script will not be raised to the application level.

The section called Error Handling with the Script Control provides additional information about error handling strategies. Chapter 6, 'Error Handling and Debugging,' is also a good reference if you need a primer on VBScript error handling.

Properties

The properties of the Erro r object are described in the following table.

Methods

The single method of the Error object is described in the following table.

Constants

The following named constants and enumerated constants are available to projects with a reference to the Script Control. These constants are globally available within any Visual Basic application that has a reference to the Script Control. For each of the constants, we explain the type, value(s), and where the constant is used.

GlobalModule Named Constant

Type: String

Value: 'Global'

When using the Script Control with scripting engines (like VBScript or Jscript) that support more than one module, use the GlobalModule constant to access the default 'global' module in the ScriptControl.Modules collection.

NoTimeout Named Constant

Type: Long

Value: -1

This constant can be used to set the Timeout property of the ScriptControl object, and prevent the execution from timing out. Please refer to the ScriptControl.Timeout property reference (previous) for more specifics.

ScriptControlState Enumerated Constant

This enumerated constant is intended for use with the ScriptControl.State property. The purpose of the State property is to control how events raised by objects is added to the ScriptControl through the AddObject method. The default value, Initialized ( ), means that the ScriptControl will not respond to events raised by these objects. The other possible value, Connected ( 1 ) means that the ScriptControl will respond to raised events.

Error Handling with the Script Control

Error handling can never be underestimated, especially when dealing with several sources of code. This is especially true for dynamically generated scripts, and user -entered expressions. In order to handle the errors, you may have to work with both VBs Err object and the Script Control's Error object. If you are working with several instances of the Script Control, each will have a separate Error object. When an error occurs, if you have a proper strategy to handle the error, you may always clear the error and continue execution of the program. You should use all possible script error-handling techniques in your scripts (especially the scripts you load from files), and handle them internally as much as possible.

Common Errors

The Script Control may raise several types of errors when setting global properties.

These errors can most probably be avoided by careful programming, and should not be a big factor of your error handling strategy. The two cases when errors will be a major nuisance are when adding the scripting code to the Script Control (syntax errors in the script), and when executing it (runtime errors in the script). When an error occurs, you may inspect both the Err and Error objects; however, the Script Control's Error object provides additional information about the nature of the error. The following example shows hypothetical error handling through VB.

Dim strCode As String Dim strValue As String sc.Reset On Error GoTo SyntaxErrorHandler strCode = InputBox("Enter Function (name it Test(a))", _ "Syntax Error Testing", _ "Sub Test(a): MsgBox ""Result: "" & CStr(a*a): End Sub") sc.AddCode strCode On Error GoTo RuntimeErrorHandler strValue = InputBox("Enter a Value for Test function", _ "Runtime Error Testing", _ "test") sc.Run "Test", strValue Exit Sub SyntaxErrorHandler: MsgBox "Error # " & Err.Number & ": " & _ Err.Description, vbCritical, "Syntax Error in Script" Exit Sub RuntimeErrorHandler: MsgBox "Error # " & Err.Number & ": " & _ Err.Description, vbCritical, "Runtime Error in Script"

There are several different ways in which VB can handle errors: through use of On Error GoTo [Label] , and, as in VBScript, through On Error Resume Next and immediate testing of Err.Number . The following example illustrates the use of On Error Resume Next , combined with an inspection of the Err object as well as Script Control's Error object, which provides us with more information.

On Error Resume Next sc.AddCode strCode If Err Then With sc.Error MsgBox "Error # " & .Number & ": " _ & .Description & vbCrLf _ & "At Line: " & .Line & " Column: " & .Column _ & " : " & .Text, vbCritical, "Syntax Error" End With Else MsgBox "No Error, result: " & CStr(sc.Run("Test", _ strValue)) If Err Then With sc.Error MsgBox "Error # " & .Number & ": " _ & .Description & vbCrLf _ & "At Line: " & .Line _ {}, vbCritical, "Runtime Error" End With End If End If

Finally, you may also use two of the events exposed by the ScriptControl object/control, Event and Timeout , to handle some of the errors; however, in some circumstances it may be a nuisance, and the use of the On Error... statement may be preferred because:

• The Timeout event will only occur for the initial ScriptControl object if more than one is in use
• The Script Control either has to be attached to a form, or has to be initialized using the WithEvents keyword, which may not always be desirable
• You may lose the granularity required when executing certain scripts that are likely to cause errors

You should use the Error event when you do not plan on adding any other error-handling script code to your application, as the following example code shows.

Private Sub sc_Error() Dim strMsg As String With sc.Error strMsg = "Script error has occurred:" & vbCrLf & vbCrLf strMsg = strMsg & .Description & vbCrLf strMsg = strMsg & "Line # " & .Line ' Syntax errors have additional properties If InStr(.Source, "compilation") > 0 Then strMsg = strMsg & ", Column# " & .Column strMsg = strMsg & ", Text: " & .Text End If strMsg = strMsg & vbCrLf End With MsgBox strMsg, vbCritical, "Script Error" sc.Error.Clear End Sub

Note that when using the ScriptControl Error event, the event handler is invoked before any On Error... code. Hence, use of both error-handling techniques may produce double error messages and disable any effective error handling.

Debugging

A quick note on debugging scripts hosted by your application using the Script Control: you can debug your native Visual Basic code in the VB IDE. However, in order to debug the code inside of a script, you have to use the freely downloadable Microsoft Script Debugger. When the debugger is installed, any unhandled errors or Stop statements inside of a script will invoke the debugger, just as with any other script. Please read Chapter 6, 'Error Handling and Debugging,' for more information on the Script Debugger and script debugging techniques.

Also, keep in mind that if the debugger is invoked during script execution, the script execution time as it relates to the Timeout property continues to accumulate. In other words, if your Timeout is set to 10,000 milliseconds (10 seconds) and the debugger comes up and the script pauses for more than 10 seconds, the Script Control will bring up the timeout dialog box.

For this reason, while you are debugging, you might want to set the Timeout property to NoTimeout ( -1 ) and then set it to another value when you release to production. A good way to do this is to use a named constant for setting the Timeout value, but control the value of this constant using a conditional compilation flag and the #IFDEF statement, such as the following.

#IFDEF blnDebugging Const TIMEOUT_VAL = -1 #ELSE Const TIMEOUT_VAL = 15000 #ENDIF ...objSC.Timeout = TIMEOUT_VAL ...

Using Encoded Scripts

The Script Control does support encoded scripts (see Chapter 14). There are two things to keep in mind.

First, when setting the Language property for an encoded script, set the property to 'VBScript.Encode' instead of the normal 'VBScript.'

Second, if you are loading an encoded script from a file or database, you may have to use alternative techniques to account for the fact that an encoded script will have a lot of special characters . For loading from a file, you might want to use the scripting runtime TextStream object with the FileSystemObject.OpenTextFile method (see Chapter 7) rather than using native Visual Basic functions to open the file. For storing in and loading from a database, your best bet is to store the script as binary data rather than in a normal Char or VarChar column.

Sample Project

The sample project, ComplexSC , demonstrates the basics of the Script Control, including how an application can share its objects with the script and pass static events-because of this requirement, the project is an ActiveX EXE type.

When building database applications that depend on an outside database, we always encounter the problem of feeding the application with the connection string associated with the appropriate database and the appropriate server. Often, this information is retrieved from the system registry, identifying the software author and the application, and then by a custom key:

Sample Registry Path : SOFTWARECompany NameApp Name

Sample Key Name : MyAppConnection

The sample project provides a way to create, store, and edit registry settings for application settings such as connection strings. The Visual Basic form and code in the ComplexSC project are designed to be generic and customized through a script. This means that you can distribute a new script without having to recompile or redistribute the VB application.

Figure 18-2 shows the main form of the ComplexSC project.

The possibilities here are almost endless: by exposing the objects in the application, and passing some of the events to the script, the script can act as a macro and adapt to your needs. There are some idiosyncrasies, especially when it comes to passing events between the form and the script. To make this possible, all of the controls are placed on the form at design time, some of them in control arrays. The script can easily control all of the properties and methods of all controls, but when the control arrays (optional connection string tags and their values) are used, dynamic modification of the form members is simplified. Here, depending on the choice of connection (OLE DB, ODBC, and DSN) we can display different labels and editable values associated with the connection type.

Sharing of the form members is easily achieved through the CShared class, which allows us to share the main form and all of its members with a script (shown below). Although we could expose individual elements as opposed to the entire form, and prevent the script from manipulating any of the elements we want protected, in the case of this application it is simply not necessary.

Figure 18-2

Option Explicit Private m_Form As Form Public Property Get Form() As Object Set Form = m_Form End Property Friend Property Set Form(ByVal newValue As Object) Set m_Form = newValue End Property

What we are doing here is wrapping the form in the CShared class. With the CShared class in place, we need to use the AddObject method of the Script Control to share the form with the script. This is done via the InitScriptControl procedure, which is executed when the form is loaded (called from the Form_Load event handler). We are passing the reference to the VB form, exposed through the CShared .Form property.

Private Sub Form_Load() Set objScript = InitScriptControl(Me) objScript.Run "init" End Sub

The InitScriptControl instantiates the ScriptControl object, loads the script, instantiates the CShared object, and exposes it to the Script Control. Because we set the third parameter of the AddObject method to true, all of the members of the form are shared too.

Function InitScriptControl(frmForm As Form) As ScriptControl Dim objSC As ScriptControl Dim fileName As String, intFnum As Integer Dim objShare As New CShared ' create a new instance of the control Set objSC = New ScriptControl objSC.Language = "VBScript" objSC.AllowUI = True Set objShare.Form = frmForm objSC.AddObject "share", objShare, True ' load the code into the script control fileName = App.Path & " regeditor.scp" intFnum = FreeFile Open fileName For Input As #intFnum objSC.AddCode Input$(LOF(intFnum), intFnum) Close #intFnum ' return to the caller Set InitScriptControl = objSC End Function

After the Script Control is initialized , the Form_Load code calls the Init procedure in the script, which sets up all of the necessary controls on the form. In actuality, some of the controls are pre-set with certain properties (such as background color , enabled, and so on.), while others are initialized by the script by accessing the members of the form exposed by CShared.Form .

Sub Init() Dim i, strTmp Form.Caption = "Connection Registration Manager" strTmp = "This application saves the database connection" strTmp = strTMP & string in the registry. " & vbCrLf Form.lblExplanation = strTmp Form.lblRegistry.Caption = "" ' this information should be reflected in your application ' the standard is to store the registry keys in subhives ' for different companies and projects Form.txtSubpath.Text = "SOFTWARE Company Name App Name " ' finally the name of the key ' you could similarly extend this application so it would ' work like a wizard, and register several keys Form.txtKey.Text = "MyAppConnection" Form.lblRegistry.Caption = "" Form.cmdRegister.Enabled = False Form.cmdProcess.Enabled = True For i = 0 To 5 Form.lblLabel(i).Visible = False Form.txtText(i).Visible = False Next Form.cboCombo.Clear Form.cboCombo.AddItem "OLE DB" Form.cboCombo.AddiTem "ODBC" Form.cboCombo.AddItem "DSN" End Sub

Next, we need to respond to events generated by the application. In this simple case, we simply pass the events as intercepted by the application directly to the script. Hence, our application may have the following events passed to the script.

Private Sub cboCombo_Click() objScript.Run "cboCombo_Click" End Sub Private Sub txtText_KeyPress(Index As Integer, KeyAscii As Integer) KeyAscii = objScript.Run("txtText_KeyPress",Index, KeyAscii) End Sub

As the example shows, we pass the events directly to the script, optionally passing along the parameters generated by the event. Because in certain cases we might want to modify one of the parameters, we should treat the event-handling procedure as a function, which would return the modified value. This is probably the simplest mechanism for modifying such parameters. Although this functionality is not required by our application, the following function inside the script would capitalize each character entered into one of the text boxes.

Function txtText_KeyPress(Index , KeyAscii) txtText_KeyPress = Asc(Ucase(Chr(KeyAscii))) End Function

This approach is a little different from what you'd expect in VB code, because even if we pass the value of KeyAscii by reference (normal VB code would be KeyAscii = Asc(Ucase(Chr(KeyAscii))) ), the script will not update this value back in VB. Hence, we employ a simple work around by turning the event handler from procedure into a function.

It is also possible to override the default event handling, or to provide optional event handling in the script. When the script does not have the member procedure, an error is generated, which provides us with a possibility of either ignoring events or providing default events, in case the script does not have an appropriately named procedure. The following example shows the simplest error trapping, which allows us to create a default event handler. Moreover, when the error handler is disabled (with On Error Resume Next ), the script must contain an appropriately named procedure with the correct number of parameters.

Private Sub cboCombo_Click() On Error Resume Next objScript.Run "cboCombo_Click" If Err = 0 Then Exit Sub ' default event handler goes here ...End Sub

Details of the application lie in the script itself, so rather than copying the entire code listing, the following example only shows partial implementation of the cboCombo_Click procedure within the script. After the key controls are reset, we set up values of the labels and the associated text that would correspond to an OLE DB type connection string.

Sub cboCombo_Click() Dim strComboSelection, strTmp ' Clean Up in case this was pressed already Form.cmdRegister.Enabled = False Form.cmdProcess.Enabled = True Form.lblRegistry.Caption = "" For i = 0 To 5 Form.lblLabel(i).Visible = False Form.txtText(i).Visible = False Next strComboSelection = _ Trim(Form.cboCombo.List(Form.cboCombo.ListIndex)) Select Case strComboSelection Case "OLE DB" For i = 0 To 4 Form.lblLabel(i).Visible = True Form.txtText(i).Visible = True Next Form.lblLabel(0).Caption = "Provider=" Form.lblLabel(1).Caption = "Data Source=" Form.lblLabel(2).Caption = "Initial Catalog=" Form.lblLabel(3).Caption = "User ID=" Form.lblLabel(4).Caption = "Password=" Form.txtText(0).Text = "SQLOLEDB" Form.txtText(1).Text = "DATABOX" Form.txtText(2).Text = "MyAppDB" Form.txtText(3).Text = "Student" Form.txtText(4).Text = "teacher" [...] End Select strTmp = "Please Fill In Remaining Values in the available" strTmp = strTmp & " text boxes. " & vbCrLf strTmp = strTmp & "You may press ""Proceed"" button, or" strTmp = strTmp & " change the connection method again. " strTmp = strTmp & "Leaving User ID empty will leave out" strTmp = strTmp & " user infromation from registry" Form.lblExplanation = strTmp End Sub

The remainder of the application responds to the end-user events, and builds the connection string as required by the core application, enabling and disabling controls, and modifying values on the form, depending on the 'stage.' The last action is actually carried out directly by the application itself; a value is written to the registry based on the string that is stored in one of the labels on the form.

This little application can be further extended to take advantage of several scripts, and provide wizard- like functionality that can easily be scripted.

Summary

The Script Control is a free control provided by Microsoft that enables your application to host a scripting engine. Uses of the Script Control can range from simple dynamic evaluation of expressions, to a full-fledged macro language add-on capable of automating your applications.

This chapter covered the following topics:

• What the Script Control is
• How the Script Control can be a useful addition to your Visual Basic application
• Why you would want to consider using the Script Control (or why not)
• The Script Control object model, including its properties, methods , and events
• Error handling and debugging
• A sample project demonstrating the use of the Script Control