Extra Basic Macro Conversion

Macro Conversion Help

Extra! Basic Macro to BlueZone Basic Script Conversion

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.

SEE Object Compatibility Mode Help for more information.

The BlueZone Script Host & Debugger supports several scripting languages such as BlueZone Basic, Visual Basic Scripting Edition, also known as VBScript, JScript, Perl, Python, Rexx, as well as others.

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 one of the supported scripting languages.

This document is a "rough-guide" to techniques involved in the process of converting Extra! Basic macros to BlueZone Basic scripts. Its purpose is to provide a source reference for those who wish to quickly begin using BlueZone Script Host & Debugger with their existing Extra! Basic macros.

The BlueZone Script Host & Debugger will identify the syntax errors and highlight them as the script is played.

Extra! Basic macros use the Extra! System Object and are coded to run within the Extra! scripting framework. The BlueZone scripting framework 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.

Requirements

Attachmate Extra! Macro Editor, installed and working.
BlueZone for the Desktop (version 3.2 or higher) with BlueZone Script Host & Debugger, installed and working.

Extra! Basic Macro Conversion

Save the Extra! Macro to a Text File

Using the Extra! Macro Editor, open the desired existing Extra! macro, then select File:Save As from the main menu. In the Windows 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! Basic macro has been saved as a text file, copy this file to the BlueZone \Scripts directory and manually rename the file extension to .bbs.

Open the BlueZone Basic Script using BlueZone Script Host & Debugger

To load the newly created script file, launch the 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 BlueZone Basic.

Replace the Extra! System Object with the BlueZone System Object

Here is an example of the Extra! System Object in a Extra! Basic macro:

sub setups (file_name as string, set_to as integer, set_to2 as integer)

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. Stopping macro playback."

STOP

End If

Set Sessions = System.Sessions

If (Sessions is Nothing) Then

Msgbox "Could not create the Sessions collection object. Stopping macro playback."

STOP

End If

Here is an example of the Extra! System Object replaced with the BlueZone Object:

sub setups (file_name as string, set_to as integer, set_to2 as integer)

Dim Sessions As Object

Dim System As Object

Set System = CreateObject( "Bzwhll.Whllobj" ) ' Gets the system object

If (System is Nothing) Then

Msgbox "Could not create the BlueZone System object. Stopping macro playback."

STOP

End If

Set Sessions = System.Sessions

If (Sessions is Nothing) Then

Msgbox "Could not create the Sessions collection object. Stopping macro playback."

STOP

End If

NOTE Some Extra! macros contain the "CreateObject" statement in one or more header files, and call it as an include. If this is the case with your macros, you must convert the Extra! System Object to the BlueZone System Object in each header file.

Include Statements in Header Files

Extra! header files (.ebh) which contain Include Statements, need to be converted to BlueZone header files by changing the file extension to .bbh, and references to these files inside the main script body, must changed to .bbh as shown here:

Sub Main

x = 1

'$Include: “c:\file1.bbh”

'$Include: “c:\file2.bbh”

End Sub

Replace WaitHostQuiet with WaitReady

This change is optional but recommended. 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

Include Main Execution Statement

Include the Main subroutine name at the bottom of your script to begin script execution at run-time. The Extra! Basic macro will end like this:

End Sub

You must add the Main subroutine name (the comment is of course optional) after the End Sub as shown here:

End Sub

Main 'execute sub Main at run-time

Other Object Differences

There are some differences between how BlueZone Script Host implements the Extra! Object that are important to understand.

Session Object - There is only one Session Object in the BlueZone Host Automation Object. When using the BlueZone Host Automation Object to control multiple BlueZone sessions, the script must explicitly “Connect” to the session prior to reading or writing it. Using the BlueZone Host Automation 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! Object, 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.