Release Notes Synapta Services Builder
Attachmate Synapta Services Builder for 3270/5250 Version 3.0
Attachmate Synapta Services Builder for UTS/T27 Version 3.0
Attachmate Synapta Services Builder for VT Version 3.0
October 2004


This file contains late-breaking information about the version 3.0 release of Synapta Services Builder for 3270/5250, Synapta Services Builder for UTS/T27, and Synapta Services Builder for VT, known collectively as Synapta Services Builder for Screens.

These release notes include known issues involving all three components that together make up each Services Builder product; Task Builder for Screens, Runtime Service for Screens, and Management & Control Service for Screens.

Task Builder for Screens The design tool that assists you in producing services from host screens for use in service-oriented architectures. Task Builder has a graphical user interface that simplifies the process of capturing host screen fields and provides tools that make designing custom applications easier.
Runtime Service for Screens The component with which you access and execute transactions within the host application.
Management & Control Service for Screens The component with which you centrally configure and monitor session pools, J2EE session EJBs, and your task failover and load balancing capabilities.

For information on issues concerning Management & Control Services (MCS), a Web-based server console that administrators can use to centrally manage and configure compatible Attachmate products, see readme_mcs.htm.

New in this Release

For more information about these features, refer to the What's New in Services Builder topic in the Getting Started Guide.

Installation Notes

For information about upgrading and installing Synapta Services Builders see the Getting Started or product guide.

Installing the Screen Connector Proxy Service

The Smart Connector Proxy Service is a Windows service, which maintains a single instance of the Java Virtual Machine and services DCOM requests for stateless task execution via Attachmate's IConnectorAccess.

When installing the Screen Connector Proxy Service on a system that has either Runtime Service for Screens or Task Builder for Screens installed: Choose No, when prompted as to whether you want to replace the existing ..\Attachmate\EAI\ScreenConnectors\ file. Failure to do so will corrupt the system.

RMI Port Value Removed when Task Builder is Un-installed

The RMI port number is stored in the file, located in the <install_dir>/Attachmate/EAI/ScreenConnectors. When the Task Builder is uninstalled, this entry is removed, and the default port number 6700 will be used. If you require a different port number, you can manually add the rmi port number to the file.

For example:


Runtime Configuration Issue in certain Uninstall Situations

After installing Runtime Service for Screens and Task Builder for Screens, if you uninstall Task Builder, the deployerconfig.bat file will also be removed. This file is used to associate a Runtime Sevice with a MCS server. To replace the file, manually re-create the file and copy it to the <install_dir>\Attachmate\EAI\ScreenConnector directory.

To re-create deployerconfig.bat:

  1. Open the <install_dir>\Attachmate\EAI\ScreenConnector directory and create a new text file, naming it deployerconfig.bat.

  2. To edit the new file, right-click on the file and choose Edit.

  3. Paste the following text into the file:
    set JAVAVM=<Install_Dir>\SysTools\j2sdk1.4.2_02\bin\java
    set EAIROOT==<Install_Dir>\EAI
    set CP=.;%EAIROOT%\Common\Config;%EAIROOT%\ScreenConnectors\lib\clientclasses.jar;%EAIROOT%\ScreenConnectors\lib\nav.jar
    "%JAVAVM%" -classpath "%CP%" com.attachmate.common.util.DeployerConfig %*

  4. Replace the <Install_Dir> string with the full path to the Attachmate directory where the product is installed. For example, C:\Program Files\Attachmate.

  5. Save and close the file.

Task Builder Resizes when Using Multiple Designers

When multiple designers are installed, Task Builder resizes itself to the frame size of the designer with the largest layout. Occasionally panels within the currently selected designer will also resize. A simple refresh by maximizing or minimizing the frame will make the window repaint correctly. If Task Builder's layout size is the largest of the installed designers, you will not see this problem.

Installing MCS and Management Components with Windows XP SP2

During the installation of MCS or an MCS management component, you may see a Windows security alert one or more times. This message is displayed only if you use Windows XP with the Windows XP firewall enabled (as it is by default). The message asks you if you want to keep blocking the program java or javaw. To continue with the installation, when you see this message, click Unblock.

After you click Unblock, these programs are logged in the Windows Firewall Exceptions page. Although not evident on this page, the entire path to the program has been saved. Running either program from the logged location will not display the security alert; however, running them from a different location will display the alert.

Known Issues

You may encounter the following issues common to all Service Builder components:

Default Security Option in Windows XP SP2 Restricts JavaScript in Help

The Synapta Services Builder for Screens help uses JavaScript. Windows XP SP2 includes the security option Local Machine Zone Lockdown, which by default restricts JavaScript from running in Internet Explorer. If you use Internet Explorer, by default, when you attempt to display the help, a message is displayed in the Information bar stating that Internet Explorer has restricted the help from showing active content.

To display the help, click the Information bar, and then click Yes to allow active content.

Note You must do this each time you view the help.

Alternatively, you can lower your security settings to avoid seeing this message. However, this change will apply to all files that include active content, and Microsoft does not recommend this approach. For more information about Local Machine Zone Lockdown, see the Microsoft Web site.

Installing MCS Service Agent for Runtime Replication

Before replicating an installed runtime it is recommended that you first install the MCS Service Agent. Although not required, the agent allows the runtime to communicate logging information to an MCS Server. There needs to be a preexisting JVM on the system for the agent to be able to run.

To install the MCS Service Agent:

  1. Copy client_installer.tar.gz, located in /opt/Attachmate/EAI/ScreenConnectors/ClientInstall/Solaris to the target server and uncompress the file:

    gunzip < client_installer.tar.gz | tar xf -

  2. Change to the client_installer directory and run the script:
    cd client_installer

  3. Follow the prompts to install the agent.

  4. The agent should be started before any Runtimes are started on the server. To start the agent: EAI/Common/mcs/ start
It is recommended that MCS Service Agent be installed as a priviledged user on the system if it will be shared among multiple runtimes owned by different users. This way no individual runtime owner can stop MCS Service Agent, which will prevent event logging for other potential runtimes on the system.

Independent NavMap Recorder utility

The NavMap Recorder, which provides the ability to remove duplicate screens, has been removed from Task Builder and is now a stand-alone utility.

From <INSTALL_DIR>\Attachmate\EAI\ScreenConnectors\Tools\NavMapRecorder:

To do this..
Then do this
Access the NavMap Recorder Run navmaprecorder.exe
Read the documentation Open the documentation folder and click navmaprecorder.htm

Task Builder mnemonics visibility

When running Windows 2000, with the addition of the new look and feel, which has been added to the designer in this release, mnemonics are not visible unless you press the ALT key. To change this option:

  1. Click on the desktop, right-click and select Properties.
  2. On the Effects tab, clear the Hide Keyboard Navigation Indicators option.

Using .NET Remotable Objects in Custom Applications

When using custom host applications, it is important to remember that the XML task file must reside in the same directory as the server application.

Task Builder

Executing an Imported or Exported Global Screen Handler

During run-time execution, using an imported or exported global screen handler, you may encounter an unrecognized screen error. To remedy this, manually edit the project NavMap.

  1. Open the NavMap for the project containing the global screen handler.

  2. Under the Resources section, locate the InitialState value of the NavProcedureUpdate.

  3. Modify the [state list] parameter, but do not modify the true InitialState property on the state itself. For example,
    	<OBJECT NAME = "NavProcedureUpdate">
            <OBJECT NAME = "States">
                    <OBJECT NAME = "<state name>">
                        <PARAM NAME = "InitialState"  VALUE = "true" />
            <PARAM NAME = "InitialState"  VALUE = "[state list]" />

    The state list must contain all of the names of all the global screen handlers prefixed with "GLOBAL_". If you have three global screen handers defined as, MyGlobalScreen, ErrorScreen, and Another_Screen, then the InitialStatae parameter will be: 'GLOBAL_MyGlobalScreen GLOBAL_ErrorScreen GLOBAL_Another_Screen'. Names are delimited by a space character and the order they appear in the list is the order they are evaluated during runtime.

Custom Steps Used as Task Endpoints when Looping

If you want to navigate through multiple screens using a custom step that uses itself as its own step destination, then the step should not be used as a task endpoint. To avoid this situation move the endpoint to the next settled step.

Naming Conventions when Generating WebSphere Web Services

WebSphere Studio has certain issues relating to Java naming conventions. When generating WebSphere Web services, these issues can be minimized by following these guidelines:

WebSphere prefers short names when creating client and router WAR files.

Incorrect File Location Displayed when Generating Apache Axis Web Services

When you generate Apache Axis Web services a message box displays containing the post-generation file locations. These file locations are inaccurate. All generated files are placed in the following location:


Incompatibility between JDK 1.4.1_02 and some video drivers

If you do not have JDK 1.4.1_02 or a later version already installed, JDK 1.4.1_02 is installed by Services Builder for Screens. If you experience either of the following two problems, please update your video driver.

Updating your video driver should eliminate these problems.

Problem Executing an Axis Web Service in C# Applications

The C# development environment, in some situations, uses default port 80. After creating an Axis Web service, some of the port numbers may no longer be in synch and must be modified manually.

In order to successfully execute an Axis Web service in C#:

  1. Create and deploy an Axis Web service to your C# development environment.
  2. Open the imported web reference "Reference.cs" file in the IDE and locate the constructor.
  3. Add the port number to the URL for the member variable in the constructor. For example, "http://myServer:8080/axis/services/PVSimpleTaskOneA".

Management & Control Services for Screens

After fail-over, new primary MCS server does not display server list

In a fail-over situation, when the secondary MCS server in a cluster takes over the primary server role, the server node tree structure is not visible in the left pane of the management console. This is easily remedied by refreshing the server list.

To refresh the server list under Services Builder for Screens in the left pane of the management console, click each server listed in the right pane, click Edit. When the Edit dialog box displays, click OK. Continue with each server in turn. This process re-populates the Servers node with the pre-configured server names.

Changing port and server values in TaskConfigurations.xml

The TaskConfigurations.xml file is used, in some instances, to configure remote or client machines and to modify default configuration settimgs.

The default taskconfigurations.xml file has changed. Previously, a default configuration looked like:

	<Configuration Name = "oldTaskName" >
		<Property Name = "serverAddress" Value = "localhost" />
		<Property Name = "serverClass" Value = "com.attachmate.common.eai.ProxyTaskServer" />

While the new configuration has two additional nodes and looks like:

	<Configuration Name = "newTaskName" >
		<Property Name = "serverAddress" Value = "localhost" />
		<Property Name = "serverClass" Value = "com.attachmate.common.eai.ProxyTaskServer" />
		<Property Name = "port" Value = "6700" />
		<Property Name = "server" Value = "localhost" />

The two added "port" and "server" nodes are currently unused. To modify the port and server settings follow the previous format. For example,

	<Property Name = "serverAddress" Value = "rmi://localhost:6700/?contextName=poolName" />	

Where contextName = the name of the pool and 6700 is the number of the RMI port.

See Modifying the Task Configuration File in the product guide for detailed information on this file.

Task name length limitation when deploying EJBs to WebSphere or Sun ONE application servers

Tasks with very long names may cause deployment errors when deploying session EJBs to WebSphere or Sun ONE application servers. Use project names of ten characters or less.

The Attachmate J2EE connector architecture supports BEA WebLogic 8.1 and 7.04

When deploying J2EE session EJBs to a BEA WebLogic 8.1 application server, verify that the registered application server and the configuration information you used when packaging the EJB are consistent with that version of WebLogic. You cannot package an EJB using a WebLogic 7.04 configuration and deploy it to a WebLogic 8.1 application server.

When you register a WebLogic 8.1+ server over an existing WebLogic 7.04 server installation, you will not be prompted for the path to the new version of the WebLogic.jar file. To specify the correct path:

  1. Delete the ..\Generator\lib\weblogic%2ejar.binary file.
  2. Add or edit the WebLogic 8.1+ server registration.
  3. Click OK and specify the path to the new version of the WebLogic JAR file.

Errors in the Tomcat Log

You may see several bad read errors in your Tomcat log file. This is a known bug in Tomcat v. 4.0.4, which is documented on the Apache Web site at The errors are harmless and can be safely ignored.

Using Tomcat on UNIX Systems

If you are using Tomcat on a UNIX system that will receive a high volume of traffic for MCS, you should increase your system's default setting for the number of "files" that can be concurrently opened by a particular process to 1024. This is advisable because UNIX considers a network connection to be a kind of file. Many systems have a default value of 64 or 256 for this setting, which may limit the concurrent connections available to your MCS Server.

To increase the number of files allowed by the Java process in which MCS is running
  1. After the UNIX installation is complete, edit, located in the Attachmate/HTTPEngine/bin directory, by adding the following line near the top of the file:

    ulimit -n 1024

  2. Restart the HTTPEngine.

UnsupportedEncodingException Cp1386

When a browser accesses the WebSphere v. 4.0 application server and it throws an "UnsupportedEncodingException Cp1386" exception, you will need to change the line in <was_root>\properties\ as follows:

From this
GB2312=Cp1386 GB2312=Gb2312

When you restart the application server, the problem should go away. (There is a note about this in this the WebSphere Readme file.)

Failover and Load Balancing Errors When Using the J2EE Connector with WebSphere and Oracle

Failover and load balancing errors may occur when using the J2EE connector with WebSphere and Oracle. To successfully implement failover and load balancing in an application server environment, use either WebLogic or Sun ONE as your application server. In all non-application server environments, such as Task beans and task files (XML), failover and load balancing is not affected.

Running Tasks using Sun ONE

To use Sun ONE with the MCS service agent for failover and load balancing, you must make two modifications to the server.policy file in the application server:

For information on the TaskConfigurations.xml file, see Modifying the Task Configuration File in the product guide.

Thread Clean-up Problems when Exiting Client Applications

When writing an application using task interface objects (service beans, XML task file, Java beans), the VM may not terminate as expected. When the final thread terminates the VM fails to cleanup all daemon threads which will result in the VM not exiting. Exiting the application via a call to System.exit() or any other explicit means, such as closing the client window, will result in normal VM termination.

Pools are Unavailable After Installing Different Host Types

If you install one host type over another host type installation where pools have been created, then the pool type for the latter installation will not be available.

For example, if you install Unisys on top of an IBM installation where IBM pools have been created, then the Unisys pool type will not be available and you will be unable to create Unisys pools. The same issue occurs if you install IBM over an Unisys installation.

To correct this situation:

  1. Stop the Runtime Service.

  2. Run the appropriate <host-type>Configure.exe file:
    If this platform
    Then this file
    Windows Attachmate\EAI\cfg\IBMConfigure.exe
    UNIX Attachmate/EAI/cfg/

  3. Start the Runtime Service.

Runtime Service for Screens

Enhanced performance option when using the IConnectorAccess interface

You can now cache the task file's XML metadata so that it does not have to be reloaded and parsed each time a task is opened. Caching the task file can significantly improve performance. However, by default caching is turned off, which provides for backward compatibility and makes debugging easier.

To enable caching:

To update the cache:

If you copy an updated metadata file to a running system with caching enabled, you need to update the cache. There are several ways to trigger an update:

  1. Update the metadata file and simply restart each Java VM that is hosting a connector. All connector instances will automatically start using the updated version when the VM is restarted.

  2. Without restarting the Java VM, you can call open on any connector instance with cache=false. All connector instances will automatically start using the updated version. Repeat for each Java VM that you want to update.

    The open parameters syntax is: <path to metadata XML>[?cache=<true | false>]...[&=<value n>]

To disable caching:

Re-initializing the Runtime Service Database

Before re-initializing the Runtime Service Database, first verify that the Runtime Service is not running. MCS will display a Server not Available error if the Runtime Service is not running.

If, after starting the Runtime Service, the server is not available in Management & Control Service for Screens, you may need to create the file ConfigTree.db. If this file is missing ininstalldir/EAI/cfg directory, where installdir is the directory to which you installed the Services Builder for Screens Runtime Service, use the following procedure to create the file and initialize the Runtime Service database.

  1. Stop the Runtime Service.

  2. In the installdir/EAI/cfg directory, run BaseConfigure.exe, and then run IBMConfigure.exe, UnisysConfigure.exe,and VTConfigure.exe depending on your host type.

    These utilities create new versions of the ConfigTree.db and .data files.
    If this platform
    Then this file
    Windows Attachmate\EAI\cfg\IBMConfigure.exe
    UNIX Attachmate/EAI/cfg/

  3. Start the Runtime Service.

It is important to remember that when you re-create ConfigTree.db any existing configuration for the affected Runtime Service will be lost.

Services Builder for 3270/5250

You may encounter these issues specific to Services Builder for 3270/5250:

Using Characters Outside ASCII Range when Generating WebLogic Web Services

If your task outputs contain characters outside the ASCII range and you are generating WebLogic Web services, you must set the following system property in your WebLogic start-up file: weblogic.webservice.i18n.charset="UTF-8" The start-up file is either startWebLogic.cmd or depending on whether you are running on a Windows or Unix system.

Problems with NavMaps containing Host Disconnects

If you are using NavMaps that:

  1. were created using a previous version of Task Builder for Screens
  2. contain a host disconnect

You may encounter the following problems:

Compile Errors Explained in Log File

If a compilation error occurs (which should only happen if a user has altered the location of the installed jars), a text file is created (attachmate\eai\temp\compile.txt) to explain the errors.

Pool Creation Problems involving Incompatible NavMaps

If you have a run-time installation that includes both Services Builders, IBM and Unisys, you could encounter pool creation problems involving potentially incompatible NavMaps.

Depending on the type of host, the problem will manifest itself differently.

Services Builder for UTS/T27

You may encounter these issues specific to Services Builder for UTS/T27:

Screen Recognition Wait Time Increased while Connecting to UTS Host

While a UTS host connection is being made, the configured Screen Recognition Wait time is increased substantially. Since connecting typically takes longer than other operations, increasing the wait time to three times its configured value during connection lets you use smaller wait times for the majority of operations. The UTS Screen Recognition Wait Time is configured on the General page of the UTS Connection Settings dialog box.

Using the Auxiliary Session with T27 and UTS

T27 configurations used for run-time sessions or auxiliary sessions must obtain their IDs from ID Manager since only one instance of a Station ID, as defined in your configuration, can be connected from a particular IP address to the host at any given time. See Configuring a Host Connection for T27 in the Task Builder documentation for instructions on using ID Manager.

For most UTS users, only one instance of a terminal ID can be connected to a host at a given time, in which case UTS configurations used for runtime or auxiliary sessions must obtain their terminal IDs from ID Manager. See Configuring a Host Connection with UTS in the Task Builder documentation for instructions on using ID Manager. UTS sites which have PID pooling configured are not subject to this restriction.

Unsupported T27 Control Mode Keystrokes

For T27 sessions, the following control mode keystrokes are not supported: Ctrl >, Ctrl :, Ctrl ?, Ctrl < C R, Ctrl @ xx yy, Ctrl n, Ctrl Space m, Ctrl ], Ctrl ;, Ctrl Space d, Ctrl h :, Ctrl h 8, Ctrl h 9, Ctrl h 7.

Unsupported T27 Video Attributes

The T27 status line does not support any T27 video attributes such as blink, bright, underline, secure, reverse, or any combination of these. In addition, the session window does not support negative video page (Ctrl u).

Guidelines for configuring ID Manager pools

When you configure ID Manager pools for use with Services Builder for Screens, it is important that the following options are set to ensure successful pool creation:

Unisys Pools do not support Optimized Mode

An Optimized Mode setting is available from the General Pool Configuration Page. This setting does not apply to Unisys pools and, if selected, will have no effect.

Pool Creation Problems involving Incompatible NavMaps

If you have a run-time installation that includes both Services Builders, IBM and Unisys, you could encounter pool creation problems involving potentially incompatible NavMaps.

Depending on the type of host, the problem will manifest itself differently.

Services Builder for VT

You may encounter these issues specific to Services Builder for VT:

Configuring SSL Security Connection via MCS

To configure SSL security connections, you must:

Using Single Quotes with Recorded Task Inputs

To use single quotes with task inputs you can create either custom steps by using the server-side API feature or use the Script Editor to customize a portion of a task step. See the product guide topics, Using Custom Steps or Using Scripts to Replace Portions of Steps, for more information.

Possible Navigation Issues involving Global Screens

You may experience navigation issues when using tasks recorded with global screens. If problems occur, verify the step destinations for each task step in your task as occasionally an invalid step destination is recorded. Remove the invalid destination and your task should execute properly.

Table Navigation Limitation

When working with detail tables, currently only AID Key navigation is supported. You must use an AID key to return to a previous table.

View User Field Option using Formatted Mode

When you create a task using formatted mode, and you define a table on a screen, then when you click on the table screen all user and auto fields become visible. It appears as if the View User Fields option has been enabled. Toggle twice through the option to make the field outlines disappear.

Using Optimized Mode with Services Builder for VT

An Optimized Mode setting is available from the General Pool Configuration Page of the management component (MCS for Screens). This option is not available for the Services Builder for VT, and, if selected, will have no effect.