Using VBScript

Overview of IOM Interfaces in VBScript

The preceding sections provide many examples of using the IOM interfaces in a full Visual Basic environment (or in a VBA environment like Microsoft Word and Excel).

You can also use the IOM interfaces from a VBScript environment. VBScript is a commonly used scripting language that is available in Active Server Pages (ASP), Dynamic HTML (DHTML), Microsoft Outlook 97 and later, and Windows Scripting Host.

Scripto is an ActiveX DLL that has been developed by SAS in order to provide workarounds for the following common VBScript limitations:

Method calls in VBScript are limited to a single return value of type Variant.
Arrays can contain Variants only.
There is no support for reading or writing binary files.

Note: Scripto is provided with SAS Integration Technologies so that developers who choose to use VBScript can effectively use the SAS automation interfaces. However, Scripto is not specific to SAS and can be used with other automation interfaces.

The performance of VBScript is often slower than a Visual Basic application for several reasons. First, VBScript provides only late binding. It uses IDispatch instead of v-table calls. Also, VBScript is interpreted, not compiled. In addition, the way that VBScript invokes methods (InvokeMethod) causes additional overhead because all parameters must be copied twice to get them in the proper format.

The slower performance of VBScript is especially evident in the case of safe arrays in which SAS expects to contain the actual type of element in the array (such as string or an enumeration value). VBScript expects it to contain only VARIANTS, which in turn contain the appropriate type of element. InvokeMethod takes care of this conversion. However, it produces an additional copy of the array.

Scripto does not address these performance issues. We recommend that if performance is an issue, consider something other than a scripting language for your implementation. We also recommend that you only use Scripto when calling methods whose signatures require it.

Two components are implemented by the Scripto DLL: Scripto and StreamHelper.

The Scripto Interface: IScripto

IScripto is the single interface to the Scripto component. It provides two methods:

SetInterface IUnknown

The SetInterface method is used to specify the IOM interface that contains the method that you want to invoke. The interface must be set before using InvokeMethod. The interface specified must support IDispatch, and that IDispatch implementation must support type information. If either of these is not true, SetInterface returns E_INVALIDARG(&H80070057). An instance of the Scripto component can handle only a single interface at a time. Although you can create multiple instances of Scripto that handle with a different interface, you typically need only a single instance of Scripto. Switching between interfaces does not consume a significant amount of system resources. SetInterface performs an AddRef function on the interface that is specified. You can release this reference when you are finished with the interface using the following statement:

SetInterface Nothing

Also, when you release IScripto, it releases any interface that Scripto still references. After you set an interface, you can still make calls on it without using Scripto.

Return-Parameter InvokeMethod( methodName, params)

The InvokeMethod method invokes the desired IOM interface method through the Scripto DLL. This method can be invoked only after the interface has been set using SetInterface. The methodName parameter is a string that contains the name of the method to invoke on the interface that has been set. The params parameter is an array whose elements contain the parameters for the method that is to be invoked. The order of the parameters in the array must be in reverse order of how they are specified in the method signature. For example, the first parameter in the method signature must be the final parameter in the array. The array must have exactly the same number of elements as there are parameters to the method. Otherwise, InvokeMethod returns DISP_E_BADPARAMCOUNT(&H8002000E).

Note: If the method has a parameter that uses the [retval] modifier, then this parameter is returned as the return value to InvokeMethod and you do not need an element in the params array for it.

If the method that you invoke returns a value, then InvokeMethod returns the value in the Return-Parameter.

Note: If the method returns a reference to an object, then be sure to use the Set keyword. For example:

Set obServer = obScripto.InvokeMethod(_ "CreateObjectByServer", ServerDefParms)

The StreamHelper Interface

The StreamHelper interface contains three methods that are related to working with the SAS BinaryStream (available through the SAS FileService). These methods are useful only when working with SAS; these methods make calls on IBinaryStream to read and write binary data.

WriteBinaryFile IBinaryStream, fileName

copies the entire contents of the given IBinaryStream into the specified file. This method can be useful for copying a SAS ResultPackage from the SAS server to the machine where the VBScript is running. It can also be used to copy GIF images. The IBinaryStream parameter that is passed in must have already been opened with permission to read.

ReadBinaryFile fileName, IBinaryStream

reads the entire contents of the file into the SAS BinaryStream. This method does the reverse of what WriteBinaryFile does. The IBinaryStream parameter that is passed in must be open for permission to write. Sending binary data to SAS can be useful if you want to include a binary file in a SAS package.

arrayOfBytes ReadBinaryArray (IBinaryStream, numBytes)

reads the specified number of bytes from the IBinaryStream parameter and returns them in the arrayOfBytes array. If the value of the numBytes parameter is 0, then the entire contents of the BinaryStream is returned in the array. The array is a variant containing a safe array of bytes. This array can be passed directly to the Response.BinaryWrite method of Microsoft ASP.

Programming Examples

This programming example illustrates using the Scripto component to reverse the order of parameters when invoking a method. This example assumes that the method has been defined with the following Interface Definition Language (IDL) code:
```
HRESULT MethodToInvoke([in]param1, [out]param2, [out]param3)
```
To call this method with Scripto, use the following code:
```
Dim f(2) 'An array of 3 VARIANTS
obScripto.SetInterface myInterface
f(2) = param1
obScripto.InvokeMethod "MethodToInvoke", f
param3 = f(0) ' Note that the order of parameters is reversed
param2 = f(1)
```
The next example uses the IOM LanguageService to submit SAS language statements to the IOM server. It then uses Scripto to invoke the FlushLogLines method of the LanguageService. Using Scripto provides two important advantages over invoking the method directly from VBScript:
- It converts the three arrays that are returned from the method from arrays of long integers to arrays of variants. (Note that VBScript can use arrays that contain elements of data type variant only.)
- It allows the VBScript application to receive more than one return parameter from the method that is invoked. (Note that when you invoke a method directly from VBScript, you are limited to a single return value.)
```
set obSAS = CreateObject("SAS.Workspace.1.0")
Set obScripto = CreateObject("SASScripto.Scripto")
obSAS.LanguageService.Submit "proc options;run;"
obScripto.SetInterface obSAS.LanguageService
' This example uses Scripto to invoke the FlushLogLines method
' instead of invoking the method directly from VBScript
' as shown in the following statement:
' obSAS.LanguageService.FlushLogLines 1000, carriageControls,_
' linetypes, logLines
Dim flushLogLinesParams(3)
' Note that the FlushLogLines method takes 4 parameters:
' 1) numLinesRequested (in) Specifies an upper limit on the
' number of lines to be returned.
' 2) carriageControls (out) An array that indicates carriage
' control for each line returned.
' 3) lineTypes (out) An array that indicates the line type
' for each line returned.
' 4) logLines (out) Contains the SAS log output lines
' retrieved by this call.
flushLogLinesParams(3) = 1000
obScripto.InvokeMethod "FlushLogLines",_
flushLogLinesParams
' flushLogLinesParams(0) now has logLines
' flushLogLinesParams(1) now has lineTypes
' flushLogLinesParams(2) now has carriageControls
' Print the first line
wscript.echo flushLogLinesParams(0)(0)
```
The CreateObject() call in this example creates a server object by providing a COM ProgID. The ProgID is a string form of the COM class identifier (CLSID). In this case, the ProgID describes a SAS session that provides the Workspace interface. By explicitly specifying the major and minor version 1.0 as a suffix to the ProgID SAS.Workspace, you can ensure compatibility with all versions of the SAS Integration Technologies IOM server. If you are using a SAS®9 SAS Integration Technologies client and you do not specify a version suffix to the ProgID, then you cannot connect to a SAS 8 COM server.

Note: Two-level version suffixes were not available in previous versions of the SAS Integration Technologies Windows client.
The next example illustrates using ReadBinaryArray with Microsoft Active Server Pages. Assume that a SAS program has already run that uses SAS/GRAPH to write a GIF image to a fileref called img. This example then uses the FileService to read that file back to the browser, with no intermediate files on the Web server.
```
set obFref = obSAS.FileService.UseFileref("img")
set obBinaryStream = obFref.OpenBinaryStream(1)
' SAS.StreamOpenModeForReading=1
set obStreamHelper = CreateObject("SASScripto.StreamHelper")
response.contenttype = "image/gif"
response.binarywrite obStreamHelper.ReadBinaryArray(_
obBinaryStream, 0)
```
The next example shows how to use WriteBinaryFile to copy a SAS ResultPackage. Demo.sas is a stored procedure that creates a ResultPackage in an archive.
```
obSAS.LanguageService.StoredProcessService.Execute
"demo.sas",_
parameters
```
The following lines move the package that was just created from the SAS server to the local machine:
```
Set obRemotePackageFileRef = obSAS.FileService.AssignFileref(_
"", "", "./demo.spk", "", "")
```
To open a binary stream on the SAS server for the package file, use the following:
```
Set obRemotePackageBinaryStream = _
obRemotePackageFileRef.OpenBinaryStream(1)
'StreamOpenModeForReading
```
Because VBScript cannot handle binary files, use the Scripto object to write the binary file on the local machine:
```
Set obStreamHelper = Server.CreateObject("SASScripto.StreamHelper")
obStreamHelper.WriteBinaryFile obRemotePackageBinaryStream,_
"c:\myfile.spk"
```