Release Notes for iPlanet Application Server Enterprise Connector for Tuxedo

Version 6.0 SP2 (for iAS 6.0 SP2, SP3, and SP4)

Updated August 27, 2002

These release notes contain important information available at the time of the version 6.0 SP2 release of iPlanet Application Server Enterprise Connector for Tuxedo. New features and enhancements, installation notes, known problems, and other late-breaking issues are addressed here. Read this document before you begin using iPlanet Application Server Enterprise Connector for Tuxedo.

An electronic version of these release notes can be found at the iPlanet documentation web site: http://docs.sun.com. Check the web site prior to installing and setting up your software and then periodically thereafter to view the most up-to-date release notes and manuals.

These release notes contain the following sections:

What's New in iPlanet Application Server Enterprise Connector for Tuxedo, Version 6.0 SP2

iAS Enterprise Connector for Tuxedo, Version 6.0 SP2 supports Unified Integration Framework Version 6.0 SP2 and Tuxedo Version 7.1.
The tux.ini has been added to the location where services are loaded. This file indicates which version of Tuxedo (adapter and worker) is being used.
Tuxedo 7.1 supports multi-threading.

Software and Hardware Requirements

The following table lists the hardware and software requirements for installing and running iPlanet Application Server Enterprise Connector for Tuxedo.

Table 1 Software and Hardware Requirements

Component

Requirement

Computer and Operating System

One of the following systems:

Intel Pentium microprocessor running Microsoft Windows NT version 4.0 SP6 or Windows2000 (iAS 6.0 SP3 only).

Sun SPARC running Solaris 2.6 or Solaris 2.8.

Memory

Per CPU: 256 MB minimum; 512 MB recommended.

Available disk space

Total disk space: 200 MB on NT and Windows2000, 400 MB on Solaris.

CD-ROM drive

CD-ROM drive

Network software

TCP/IP

Browser software

One of the following web browsers:

Netscape Communicator 4.6.1 or 4.7

Microsoft Internet Explorer 5.0 (Windows NT or Win2000)

Tuxedo system

Tuxedo 7.1 with Rolling Patch no. CR042398.

Other software

The following additional software must be installed prior to installing the iPlanet Application Server Enterprise Connector for Tuxedo:

Webserver 6.0 SP1 for Win2000. In order to use the samples with Webserver 6.0 SP1 see the workaround to Problem 562501 (Win2K only).

iPlanet Application Server 6.0 (SP2 and SP3 only)

Unified Integration Framework 6.0 SP2

Tuxedo Workstation Client 7.1 with RollingPatch (available from BEA)

Component	Requirement
Computer and Operating System	One of the following systems: Intel Pentium microprocessor running Microsoft Windows NT version 4.0 SP6 or Windows2000 (iAS 6.0 SP3 only). Sun SPARC running Solaris 2.6 or Solaris 2.8.
Memory	Per CPU: 256 MB minimum; 512 MB recommended.
Available disk space	Total disk space: 200 MB on NT and Windows2000, 400 MB on Solaris.
CD-ROM drive	CD-ROM drive
Network software	TCP/IP
Browser software	One of the following web browsers: Netscape Communicator 4.6.1 or 4.7 Microsoft Internet Explorer 5.0 (Windows NT or Win2000)
Tuxedo system	Tuxedo 7.1 with Rolling Patch no. CR042398.
Other software	The following additional software must be installed prior to installing the iPlanet Application Server Enterprise Connector for Tuxedo: Webserver 6.0 SP1 for Win2000. In order to use the samples with Webserver 6.0 SP1 see the workaround to Problem 562501 (Win2K only). iPlanet Application Server 6.0 (SP2 and SP3 only) Unified Integration Framework 6.0 SP2 Tuxedo Workstation Client 7.1 with RollingPatch (available from BEA)

Installation Notes

The iPlanet Application Server 6.0 SP2 or SP3 component, the Unified Integration Framework (UIF) SP2, and Tuxedo Workstation client 7.1 must be installed before installing iPlanet Application Server Enterprise Connector for Tuxedo, version 6.0 SP2.

The iPlanet Application Server Enterprise Connector for Tuxedo, Version 6.0 SP 2 must be installed on the same machine as iPlanet Application Server.

To install the connector:

for Windows, unzip NT/instux.zip from the CD-ROM into a temporary directory; then run setup.exe in the instux directory.
for Solaris, untar Solaris/instux.tar from the CD-ROM into a temporary directory and then run setup in the instux directory.

Post-installation Issues

One of the most significant improvements from Tuxedo version 6.5 to version 7.1 was the addition of multi-threading.

multi-threading is the inclusion of more than one unit of execution in a single process. In a multi-threaded application, multiple simultaneous calls can be made from the same process.

The advantages of multi-threading are:

improved performance.
simultaneous access to multiple applications - BEA Tuxedo clients can be connected to more than one application at a time.
reduced number of required servers - because one server can dispatch multiple service threads, the number of servers to start the application is reduced.

The disadvantages of multi-threading are:

difficulty of debugging - It is much harder to replicate an error in a multi-threaded application than it is to do so in a single-threaded application.
difficulty of testing - Testing a multi-threaded application is more difficult than testing a single-threaded application because defects are often timing-related and more difficult to reproduce.

From the Server Side

The server must be specifically configured and compiled to use multi-threading.

To configure a multi-threaded application, edit your UBBCONFIG file by adding the parameters shown in the Table 2.

Table 2 Configuring a multi-threading Application

Parameter

Description

MINDISPATCHTHREADS

Optional parameter.

MAXDISPATCHTHREADS

Required parameter in multi-threaded servers. When making an existing server multi-threaded, an experienced programmer must verify that the source code for the server has been written in a thread-safe manner. In other words, it is not possible to convert a single-threaded server, written with static variables, to a multi-threaded server simply by increasing the value of MAXDISPATCHTHREADS in the configuration file. This server must also be built for multi-threading.

THREADSTACKSIZE

Optional parameter; you may need to set it if your server dispatch threads require an especially large stack. The default, 0, should be sufficient for most applications. (Keep in mind that when 0 is passed to the operating system, the operating system invokes its own default.)

Parameter	Description
MINDISPATCHTHREADS	Optional parameter.
MAXDISPATCHTHREADS	Required parameter in multi-threaded servers. When making an existing server multi-threaded, an experienced programmer must verify that the source code for the server has been written in a thread-safe manner. In other words, it is not possible to convert a single-threaded server, written with static variables, to a multi-threaded server simply by increasing the value of MAXDISPATCHTHREADS in the configuration file. This server must also be built for multi-threading.
THREADSTACKSIZE	Optional parameter; you may need to set it if your server dispatch threads require an especially large stack. The default, 0, should be sufficient for most applications. (Keep in mind that when 0 is passed to the operating system, the operating system invokes its own default.)

If you are creating a multi-threaded server, you must run the buildserver(1) command with the -t option. This option is mandatory for multi-threaded servers. If you do not specify the -t option at build time, and try to boot the new server with a configuration file where the value of MAXDISPATCHTHREADS is greater than 1, a warning message is recorded in the userlog. The server then reverts to single-threaded operation.

For more information on multi-threading, see the documentation on the Tuxedo 7.1 CD -ROM. Refer to the section concerning: How multi-threading and Multicontexting Work in a Server, docs/tuxedo/v7_1/html/pgthr7.htm.

From the Client Side (Connector)

When you use multi-threading you need to customize the connection Pool parameter: MaxPoolSize. It should be the multiple of the number of users that can run concurrently times 50.

The number of users is specified in Lic.txt file that resides in <TuxedoInstallation>/udataobj.

To change the MaxPoolSize parameter refer to iPlanet Application Server Enterprise Connector for Tuxedo Administrator's Guide, Version 6.0, Chapter 3, section: Update Connection Pool Parameters.

Upgrading from iAS Enterprise Connector for Tuxedo 6.0 SP1 to SP2

In order to upgrade the iAS Enterprise Connector for Tuxedo you must also upgrade the iPlanet Application Server 6.0 SP1 and the Unified Integrated Framework from SP1 to SP2.

You must have iPlanet Application Server 6.0 SP2, SP3, or SP4 installed before upgrading the UIF and Connector.

Refer to the Unified Integrated Framework 6.0 SP2 release notes for instruction on upgrading from SP1.

To Upgrade the iAS Enterprise Connector for Tuxedo 6.0 SP1 to SP2.

Export the repository. See Unified Integrated Framework 6.0 SP2 release notes.
Uninstall iAS Enterprise Connector for Tuxedo 6.0 SP1.
Install iAS Enterprise Connector for Tuxedo 6.0 SP2.
If you had your own function object, import the XML file that you exported in Step 1.

Resolved Issues

The following issues have been resolved in the iPlanet Application Server Enterprise Connector for Tuxedo 6.0 Service Pack 2 release:

Problem (#540737)

iPlanet Application Server Enterprise Connector for Tuxedo consumes an exorbitant amount of CPU time.

Workaround

Two new variables have been added to the worker so that the Tuxedo client avoids repetitive GETREPLY requests without receiving a reply: SLEEPTIME and MAXSLEEPTIME.

SLEEPTIME is the time in milliseconds that the worker sleeps (is idle) in between two GETREPLY requests.
MAXSLEEPTIME is the maximum time in milliseconds that the worker is allowed to remain in SLEEPTIME. This value must be greater than SLEEPTIME.

For Windows:

Select Start > Settings > Control Panel > System.
Select the Environment Tab.
Add the following two system variables: SLEEPTIME and MAXSLEEPTIME.
Set your own values.

For Solaris:

Go the iPlanet/iAS6/ias/bin directory.
Edit the kjs script and add the following two variables: SLEEPTIME and MAXSLEEPTIME.
Set your own values.

Problem (#4539445)

Configuring the Installation: Unix section for iAS SP2 and later.

The following is not valid for versions iAS SP2 or later:

Add <tuxedo /ws rootdir>/lib to LD_LIBRARY_PATH environment variable.

* The LD_LIBRARY_PATH of the shell environment may be modified, or the script <ias root>/ias/bin/kjs may be adjusted to include this path

Resolved

With iAS SP2 and later, the "kjs" is changed and LD_LIBRARY_PATH can no longer be changed in this script. This script now internally calls <ias root>/ias/env/iasenv.ksh which in turn adds $TUXDIR/lib to LD_LIBRARY_PATH (TUXDIR= <tuxedo /ws rootdir>). Setting TUXDIR environment variable is sufficient.

Problem (#390188)

The Tuxedo Connector did NOT pass an empty FML32/FML16 string.

Resolved

The iAS Connector for Tuxedo now passes an empty FML32/FML16 string.

Known Problems and Limitations

The following lists known problems and limitations:

Problem 4540987

Uninstaller removes common files in multi-connector installation.

Workaround

When uninstalling one of several connectors, such as R/3, PeopleSoft, Tuxedo or CICS, the common directories <iASInstallDir>/ias/APPS/console, <iASInstallDir>/ias/APPS/ecu and files from the bin directory may be deleted. It is necessary to copy these directories back to APPS directory, while maintaining the same sub-directories structure, from <iASInstallDir>/ias/APPS/UIFbackup for the connectors to function correctly. All files that are present in the UIFBackup directory need to be copied to the <iASInstallDir>/ias/APPS.

Problem

The installer does not copy samples in webless installation mode.

In a webless installation, the web server and iPlanet Application Server reside on separate machines. In this configuration mode the Tuxedo Enterprise connector installation does not automatically copy the HTML and image files pertaining to connector samples to the web server document root directory.

Workaround

To run the samples shipped with the Tuxedo Enterprise connector, copy the HTML and image files manually from the iPlanet Application Server instance to the web server instance. This process is described in section "Copying Files in Webless Installation" in the Administrator's Guide.

Problem

The uninstaller doesn't delete repository content related to Tuxedo connector.

Workaround

Use the UIF Repository Browser to delete the unwanted datasource(s).

Problem

The uninstaller doesn't automatically unregister the Tuxedo extension in iPlanet Registry database.

Workaround

To unregister the Tuxedo extension:

Open the iPlanet Registry editor by typing kregedit on the command line.
Open the following key: SOFTWARE\iPlanet\Application Server\6.0\CCS0\Extensions\ TuxedoAdapterExt\ENABLED
Set the value to 0 and click OK.

Problem

The uninstaller removes common files in a multi-connector installation.

When uninstalling one of several connectors, such as R/3, PeopleSoft, or CICS, the common directories /ias/APPS/console and /ias/APPC/ecu may be deleted.

Workaround

Copy these directories back to APPC directory from /ias/UIFbackup.

Problem

FML fields can not be deleted using the Repository Browser.

Workaround

Use the Netscape Console to delete the unwanted FML/FML32 field(s). Optionally, the configuration node can be exported into an XML file, delete unwanted FML field entries in XML file and re-import using the Repository Browser.

Problem 562501 (Win2K only)

The samples do not work when using Webserver 6.0 SP1.

Workaround

In order to use the samples with Webserver 6.0 SP1:

Install the connector as explained in the Administrator's Guide.
Copy the directory tuxSamples

from:\<iASInstallDir>\iPlanet\ias6\ias\APPS\adapters\tux\htmldocs

to: \<iASInstallDir>\iPlanet\Servers\docs

How to Report Problems

If you have problems with iPlanet Product_Name, contact iPlanet customer support using one of the following mechanisms:

iPlanet online support web site at http://www.sun.com/service/sunone/software/index.html

From this location, the CaseTracker and CaseView tools are available for logging problems.
The telephone dispatch number associated with your maintenance contract .

So that we can best assist you in resolving problems, please have the following information available when you contact support:

Description of the problem, including the situation where the problem occurs and its impact on your operation
Machine type, operating system version, and product version, including any patches and other software that might be affecting the problem
Detailed steps on the methods you have used to reproduce the problem
Any error logs or core dumps

For More Information

Useful iPlanet information can be found at the following Internet locations:

iPlanet release notes and other documentation — http://docs.sun.com
iPlanet product status — http://www.sun.com/service/sunone/software/index.html
iPlanet Professional Services information — http://www.iplanet.com/services/professional_services_3_3.html
iPlanet developer information — http://developer.iplanet.com/
iPlanet learning solutions — http://www.iplanet.com/learning/index.html
iPlanet product data sheets — http://www.iplanet.com/products/product_map/product_name_2_0a.html

Use of iPlanet Application Server Enterprise Connector for Tuxedo is subject to the terms described in the license agreement accompanying it.

Last Updated August 28, 2002