SEE Extra!
Object Interface Compatibility for more information.BlueZone Script Host and the BlueZone Host Automation Object have Extra! Compatible functions, methods, and properties to make the conversion from Extra! to BlueZone easier. This document describes the steps and methods used to convert Extra! macros to BlueZone Visual Basic scripts. This document is a "rough-guide" to techniques involved in the process and its purpose is to provide a source reference for users who wish to quickly begin using BlueZone Script Host & Debugger with their existing Extra! macros.
The BlueZone Script Host uses Visual Basic Script (VBScript) or Java Script, so the syntax rules for these scripting languages affect the level of compatibility with Extra! Basic. Some syntax changes are necessary when converting from Extra! Basic to BlueZone Visual Basic Scripting. The BlueZone Scripting Host and debugger will identify the syntax errors and highlight them as the script is played.
Extra! recorded macros use Extra! system objects and are coded to run within the Extra! framework. BlueZone scripting includes Extra!-compatible objects and are coded to run within generic script host environments. Some examples of script hosts are Internet Explorer (IE), Windows Script Host (WSH), Internet Information Services (IIS) and BlueZone Script Host & Debugger (BZSH).
The BlueZone Host Automation Object provides exact replacement methods and properties for most of the Extra! System Object and inherited objects.
SEE Extra!
Object Interface Compatibility for more information.
Attachmate Extra! Macro Editor, installed and working.
BlueZone for the Desktop (version 3.2 or higher) with BlueZone Script Host & Debugger, installed and working.
Using the Extra! Macro Editor, open the desired existing Extra! macro, then select File:Save As from the main menu. In the common file dialog, select "Save as type: Text File (*.txt)" and enter a name for the new file to be saved as.
Once the Extra! macro file has been saved as a text file, copy this file to the BlueZone \Scripts directory and manually rename the file extension to .vbs.
To load the newly created script file, run BlueZone Script Host & Debugger and select File:Open from the MenuBar. If the script file does not appear in the common file dialog list, then select Options from the MenuBar and make sure that the Script Type selected is Visual Basic.
The Extra! header is code that is placed at the beginning of all Extra! macros and must be removed from the BlueZone script. Here is a sample of the header code to exclude, followed by the BlueZone compatible script code to replace it with:
'-------------------------------------------------------------
' This macro was created by the Macro Recorder.
' Session Document: "SESS1.EDP"
' Date: Wednesday, January 29, 2003 10:28:22
' User: userid
'-------------------------------------------------------------
' Global variable declarations
Global g_HostSettleTime%
Global g_szPassword$
Sub Main()
'-------------------------------------------------------------
' Get the main system object
Dim Sessions As Object
Dim System As Object
Set System = CreateObject("EXTRA.System")' Gets the system object
If (System is Nothing) Then
Msgbox "Could not create the EXTRA System object."
STOP
End If
Set Sessions = System.Sessions
If (Sessions is Nothing) Then
Msgbox "Could not create the Sessions collection
object."
STOP
End If
'-------------------------------------------------------------
' Set the default wait timeout value
g_HostSettleTime = 3000' milliseconds
OldSystemTimeout& = System.TimeoutValue
If (g_HostSettleTime > OldSystemTimeout) Then
System.TimeoutValue = g_HostSettleTime
End If
' Get the necessary Session Object
Dim Sess0 As Object
Set Sess0 = System.ActiveSession
If (Sess0 is Nothing) Then
Msgbox "Could not create the Session object."
STOP
End If
If Not Sess0.Visible Then Sess0.Visible = TRUE
Sess0.Screen.WaitHostQuiet(g_HostSettleTime)
Replace the above header code with the following BlueZone compatible script code:
Sub Main
Set System = CreateObject( "BZWhll.WhllObj" )
Set Sess0 = System.ActiveSession
Set Screen = Sess0.Screen
Replace all references to Session.Screen objects to include just the Screen object.
For example, convert statements like this:
Sess0.Screen.Sendkeys("userid<Tab>password<Enter>")
To this:
Screen.Sendkeys("userid<Tab>password<Enter>")
While WaitHostQuiet is supported in the BlueZone Screen object, it is recommended to replace this method with the WaitReady function included in the BlueZone System object. Although the WaitHostQuiet method in Extra! macros does work, it's not a fool-proof method for determining when the host machine is done transmitting, and may slow script execution unnecessarily. WaitReady on the other hand, is used to specify the number of host keyboard restores sent between screens (this number is displayed on BlueZone Display's StatusBar as Ready(x) where x is the number of host keyboard restores) and results in blazingly fast errorless scripts.
For example, convert statements like this:
Sess0.Screen.WaitHostQuiet(g_HostSettleTime)
To this:
System.WaitReady 10, 1
Finally, include the Main subroutine name at the bottom of your script to begin script execution at run-time. These are all of the changes necessary to convert a recorded macro to a BlueZone macro.
Sub Main
' … script code included in sub Main
End Sub
Main 'execute sub Main at run-time
Extra! Basic is similar to the older Microsoft Word Basic in features and syntax. BlueZone Scripting is an extension to the Microsoft Visual Basic Scripting. Therefore, some changes in syntax and structure may be required to convert from Extra! Basic to BlueZone VBScript. Below are some common syntax changes that must be made to convert an Extra! Basic macro to a BlueZone VBScript. Use the BlueZone Scripting Host debugger to help identify syntax errors and step through scripts will testing.
SEE Extra!
Object Interface Compatibility for more information.
“$”, “%”, and “&” are used in variable names in Extra! Basic macros, but are not supported in Visual Basic Scripting.
GoTo’s are not supported in Visual Basic Scripting and, in most cases, must be converted to subroutines. Some exceptions are:
GoTo End - can be replaced with StopScript
OnError Goto - should be commented out or replaced with On Error Resume Next, which ignores the errors and keeps the script running
All other GoTo’s can be converted to sub routines. The script logic should be evaluated and changed as needed to maintain the same functionality.
Extra! Basic Dialogs - BlueZone has a nearly identical dialog structure as Extra!. The main differences are the beginning and end of the dialog statement. Also, BlueZone dialogs do not support a callback feature that allows you to change the dialog list box contents based on user input.
Change Begin Dialog to BeginDialog
Remove and %, $, or & in the dialog definition
Change End Dialog to EndDialog
Include Statements for header files (extra.ebh) are not supported. Header files referenced in Extra! macros should be merged into each macro that references them.
File I/O
Opens a file for read, write, or append.
Filename - the name of the disk file.
Filemode - 0 or "Input" for Input, 1 or "Output" for Output, 2 or "Append" for Append.
FileNum - File number, used in subsequent file operations.
RecordLength - Record length (optional).
Returns - 0 for success, or error code.
Extra! Open statement “Open filename$ for Input as #1” changes to:
Open filename, Input, 1
Extra! Basic provides a means to load Windows DLLs and call them directly that is not possible with VBScript. Changes must be made to provide the same or similar functionality. Possible changes include:
Evaluate what the DLL call does and see if it can be eliminated from the script.
Find a COM object that does the same thing. Many Windows API calls have analogous methods or properties in the WScript or Windows Shell Objects.
Create a COM wrapper for the DLL that loads the DLL and translates the COM methods to DLL calls.
There are some differences between how BlueZone Script Host implements the Attachmate Extra! Objects that are important to understand.
Session Object - There is only one Session Object in the BlueZone Host Automation object. When using the HAO to control multiple BlueZone sessions, the script must explicitly “Connect” to the session prior to reading or writing it. Using the BlueZone Object, simply calling .Connect “A” prior to using session A and .Connect “B” when switching to session B is all that is required. When using the Extra! Objects, each session must be defined at startup as an Item, then the .Item method used to connect to each session prior to using it.
Area Object - There is only one Area Object used to store data from the screen. In Extra!, multiple Area Objects can be populated simultaneously, then, used any time. In BlueZone the Area Object contains only the last data stored. If the Area Object is to be used more that once in a macro or application, it must be filled, then used, prior to filling it with new data.
Extra! Recorded Macro Conversion