RRAFS V200704.18 Engine Setup
for Robot Versions 2000 and later

Author: Carl Nagle
UPDATED: Apr 18, 2007

Copyright (C) SAS Institute
General Public License: http://www.opensource.org/licenses/gpl-license.php
Remember: "RobotJ", "XDE Tester", and "Functional Tester" are names for the same IBM Rational test tool as habitually (re)named by IBM Rational.  We collectively refer to all of these as "RobotJ", or simply "RJ" in much of our documentation and class names.  (After all, we can't continuously rework all our documentation and class implementations just because IBM Rational has an identity problem.)

Backup selected customized files before installation:
If you have never installed RRAFS or SAFS before, then this doesn't apply to you.
If you have previously installed but never modified any of the files then this doesn't apply to you.  Still, you may want to review the mentioned files "just in case".

Affected customizable files from previous releases:

If you have taken advantage of any of the customization capabilities of this framework, then you must take some simple precautions prior to installing this new release.  Installing a new version of the framework will install new, default versions of these files.  Failure to perform any of these prescribed backups may erase your previous customizations. Hopefully, you have backed them up somewhere already as part of your normal ongoing activities...You have done this, right?!

Uninstall Pre-2003.08 RRAFS Release:

Installations of RRAFS Release 2003.01.27 (Jan 2003) and earlier installed via the Windows Installer .MSI need to be uninstalled before installing this new release.  You must do this to avoid unexpected backward versioning that can occur if the Windows Installer update or repair feature is ever invoked.

RRAFS Release 2003.08.27 (Aug 2003) and later do not have this uninstall requirement as we implemented the ability to patch and install on top of releases using different technologies.

To uninstall these older releases, uninstall "SAFS Engine for Rational Robot" from the Windows Control Panel "Add/Remove Programs" application if present.

Future releases of the framework will not have this problem as we will have the ability to patch and install on top of releases using Scripting technology. If you manually installed the engine previously, you should not need to delete your existing installation. Manual installation and the new Installer will simply overwrite existing files. Instructions for manually installing the engine are at the end of this document.

Basic Install Steps if Accepting all Defaults:

  1. (Optional) Check Java and WSH prerequisites
  2. Download the latest RRAFS Release
  3. UnZip the Release into your "C:\Program Files\Rational\Rational Test\sqabas32" directory.
  4. Double-Click "SetupRRAFS.wsf" in that directory.
  5. Check Robot configuration settings

Now, on to "why you should read the rest of this first..."

Install Java Runtime Necessary for SAFS Framework.

The additional SAFS installation requires that a Java Runtime Rnvironment (JRE) is already installed on the target machine. For best results and ease of installation, a JRE version of 1.4.2 or higher is recommended.
Note: The automated install of old STAF versions (before 2.6.10) will fail with Java V1.5.  However, Java V1.5 should work fine once the STAF install with a lesser version of Java is successful.  This has not been evaluated.  We now distribute STAF version 2.6.10 so new installations with this version of STAF should have no problems using and installing with Java 1.5.

The JRE must be in the normal search path for the system.  The install scripts now check this automatically. You can check this manually using the following command typed at any command prompt:

         java -version

The command should list the version of JRE installed.  You can download and install a JRE if necessary from the Java Sun Site

You may also be able to use the JRE that is installed as part of the IBM Rational TeamTest, IBM Rational XDE Tester or Functional Tester if the version is high enough.

Install Windows Scripting Host 5.6

Windows Scripting Host 5.6 must be installed and available via the normal system search path for the install script to run. STAF and the SAFS pieces can be installed manually without the script, but the script can automatically error-correct important values and set environment variables that the separate Java installs cannot.

The install scripts now check this automatically.  You can check this manually using the following command typed at any command prompt:


The command should list the version of Windows Scripting Host installed.  You can download and install WSH 5.6 if necessary from Microsoft Windows Script Downloads

Download, UnZip/Extract, and Run the Installation Script

The RRAFS engine installation uses simple Scripting technology. It includes everything you need to use the engine with the latest version of Robot. Even compiled versions of all the core libraries are included.   You can download the installation from our SAFSDEV Project FileList Page.

  1. Download the latest RRAFS release ZIP file 
  2. UnZIP/Extract "All Files" into your Rational install directory "C:\Program Files\Rational\Rational Test\sqabas32"
    (This is a.k.a. the DDE_RUNTIME location.)
  3. With Windows Explorer, locate the newly extracted "SetupRRAFS.wsf" script in that directory and double-click to launch it.
  4. Once complete, you will be prompted to proceed with the installation of STAF and the shared SAFS Framework.
    It is recommended you select "YES"--even if you initially think you won't be using these features.
    You can select "NO" if you wish to perform this install at a later time.

Consult SetupSAFS.README to proceed with additional steps necessary to take advantage of the many new features provided by the shared SAFS Framework.

If necessary, you can instead perform a manual install.  A manual install requires extra install steps that are prone to human error.  Manual installs are not recommended, but not terribly difficult.

Further Setup is necessary for:

Rational Robot Configuration
In order to use the Rational Robot implementation of the engine there are a few settings that should be made in Robot.  In addition, the routines currently expect a specific directory structure to exist in each of the projects that intend to make use of the engine.

*Required* Robot Playback Option Settings:

Recommended Playback Options:

The RRAFS engine has thus far proven very robust. Low settings for command and keystroke delays have not adversely affected playback accuracy in the limited number of applications that have been tested with it. Thus, you may be able to set Robot's playback delays extremely low (less than 10 milliseconds) or even to 0. These delay settings can be found in Robot's Playback Options dialog.

Recommendations would be to start with no delays ( 0 milliseconds ).  If your tests experience no inexplicable playback problems then you can keep these settings.  However, if playback experiences problems with object clicking or other activities that might be attributable to Robot running too fast, increase the delay settings to see if that resolves the problem.  But remember, there can be other causes to playback errors.  If larger delays do not fix these problems, don't forget to go back and set your delays to their original low settings.  This will help improve the performance of your RRAFS tests.

Disable Unnecessary Extensions:

To significantly improve performance, you should disable all unnecessary extensions in Robot. You do this via Robot's Tools->Extension Manager dialog. Disable all extensions you do not need. You may need to restart Robot for the changes to take affect.

Required Robot Project Subdirectories:


RRAFS.INI Configuration and Customization

The RRAFS.INI configuration file actually lets the user configure the framework to use alternate locations for the Bench, Dif, Logs, and Test directories--among other things. The Datapool\Runtime directory is OPTIONAL only as long as you do not intend to place a version of the RRAFS.INI file in that location. If you do intend to deploy a project-specific version of RRAFS.INI, then it must be placed in the <Project>\Datapool\Runtime location and that directory cannot be "moved" to any alternate location.

By default, a "global" copy of the RRAFS.INI exists in the DDE_RUNTIME directory (Program Files\Rational\Rational Test\sqabas32) where all the source was installed.  This copy affects all projects accessed by the local machine. Settings placed in a project-specific Datapool\Runtime RRAFS.INI will override the "global" settings in DDE_RUNTIME.

Set Windows Environment Variables:

The RRAFS.INI file and other changes have removed most requirements for Environment Variable settings for RRAFS. However, the shared SAFS Framework and STAF each have one Environment setting noting their root install directories.

These root install directories are:

The instructions below provide information for backward compatibility, and some older installations.
The setup for these items must be satisfied before they can be successfully used for older installations and installations not deploying a RRAFS.INI configuration file.  Environment Variable settings can be done via the Control Panel "System" application.

Set these as System Variables, rather than User Variables if possible. Robot will need rebooting in order to use any new or modified setting.

Setup Development Environment

If/How/Where to Setup and Build a RRAFS development environment:

The RRAFS release ZIP includes everything you need to use the engine with Robot. Even compiled versions of all the core libraries are included.   If you don't intend to add new functionality, then you may not need to setup a development environment and you should not have to compile the code.

Of course, if Robot complains about the compiled code format when you attempt to execute a test then you might need to compile the source SBLs with your version of Robot.

If you are using an incompatible version of Robot, you may have to create a development project and compile all the libraries to work with your version. You will also need to create a development project if you are planning to develop new functionality or customizations for the engine.

To do this, Create a separate Rational project. This one will be your *DEVELOPMENT* project--the one you will use to build the engine (and/or enhance it so that you can pass that on to SAFSDEV and the rest of the world :)

This project should not be used for anything other than building, enhancing, and testing the engine. It is not recommended for production testing of another application.

Next, UnZIP/Extract the RRAFS release ZIP file into the project's .\TMS_Scripts\SQABas32 directory. Only the *.SBL and *.SBH files need to be extracted into this directory.

You must *NOT* run the "SetupRRAFS.wsf" script from this project directory!

You will then need to do a batch compile in Robot (File->Batch Compile) of all SQABasic library source. If you make changes that you want available to all projects, then those changes and the associated compiled *.SBX files should be moved or copied to the DDE_RUNTIME location where the Rational product is installed. Changes are only local to that project until they are copied or moved to the DDE_RUNTIME location.

Once changes are copied or moved to your DDE_RUNTIME location, ALL projects accessed by this machine will find the modified files in this location. The modified files must also be copied (dragon drop?) to each Robot machine that is to run with the modifications. You only have to modify/build once on one machine. Then just copy to all other machines that need it. The other machines must have completed the initial RRAFS install and the other setup described at the top of this document.

This provides a neat development advantage. All projects can use and run a PRODUCTION version of the engine from the DDE_RUNTIME directory. Your special DEVELOPMENT project can be used to play with, modify, and enhance the version in DEVELOPMENT without impacting the PRODUCTION version. And you don't have to do anything special to take advantage of this. Robot always looks for files in the active Project's sqabas32 directory before it goes looking in your DDE_RUNTIME directory. So it will find modified development files before it will find the production DDE_RUNTIME versions.

Note: Users who have disabled the Repository or Project SQABas32 directory by specifying a path to a "common" directory will either have to temporarily disable this setting or use that common directory to build the engine. They will then also have to make their own determination as to whether they want to install the engine files to each machine's DDE_RUNTIME directory, or leave it in the "common" directory. I have not used this type of setup but imagine you loose the advantages of separate DEVELOPMENT and RUNTIME environments as discussed above.

Manual Installation Instructions:

These instructions are for those folks who need to manually install a release.   This is generally only necessary if you do not have access to and/or are not allowed to use Microsoft's Scripting technologies.  Manual installs are not recommended, but not terribly difficult.   Use the Scripting technology whenever possible. 

1.  Download the latest RRAFS release ZIP file.

2.  UnZIP/Extract  "All Files" into your Rational install directory  C:\Program Files\Rational\Rational Test\sqabas32  (This is a.k.a. the DDE RUNTIME location.)

3.  Move the following files from your DDE_RUNTIME directory into your System Folder. This is often [Windows Dir]\System32.

4.  Register the DDVariableStore.DLL extracted into your DDE_RUNTIME directory. This is done from a command line with regsvr32:

regsvr32 "[path to DLL]\DDVariableStore.DLL" [Enter]

There is also a DDVariableStoreREGISTER.VBS script you can double-click to do this.

5.  The following items need to be installed to take advantage of the ever-growing XML features of the engine. However, they do not need to be reinstalled for every release. Check with Microsoft or your system administrator because you may have these installed already depending on the version of your operating system.

 6.  Consult SetupSAFS.README  to proceed with additional steps necessary to take advantage of the many new features provided by the shared SAFS Framework.

7.   Enjoy!

SAFSDEV Web and SAFSDEV Project on SourceForge.net