Configuring WebLogic Tuxedo Connector

 

The following sections describe how to configure the WebLogic Tuxedo Connector.

• Summary of Environment Changes and Considerations

• Configuring WebLogic Tuxedo Connector for Your Applications

• Configuring WebLogic Tuxedo Connector for Non-ASCII Coding Sets

 

---

Summary of Environment Changes and Considerations

This section provides an overview of the changes you must make to the Tuxedo and WebLogic Server environments before you can start using the WebLogic Tuxedo Connector.

Tuxedo Changes

Note: For more information on Tuxedo domains, see the BEA TUXEDO Domains Guide.

Tuxedo users need to make the following environment changes:

• If an existing Tuxedo application is already using Tuxedo /T DOMAINS, then a new domain must be added to the domains configuration file for each connection to a WebLogic Tuxedo Connector instantiation.

• If the existing Tuxedo application does not use domains, then the domain servers must be added to the TUXCONFIG of the application. A new DMCONFIG must be created with a Tuxedo /T Domain entry corresponding to the WebLogic Tuxedo Connector instantiation.

• WebLogic Tuxedo Connector requires that the Tuxedo domain always have encoding turned on. MTYPE should always be unset or set to NULL in the DMCONFIG file.

WebLogic Server Changes

Note: For more information on creating WebLogic Tuxedo Connector clients or servers, see the WebLogic Tuxedo Connector Programmer's Guide.

WebLogic Server users need to make the following environment changes:

• Create Java clients or servers.

• Create a WebLogic Tuxedo Connector XML configuration file.

• Deploy WebLogic Tuxedo Connector on the WebLogic Server.

WebLogic Server Threads

Note: For more information on WebLogic Server performance and tuning, see BEA WebLogic Server Performance and Tuning, Release 6.1.

The number of client threads available when dispatching services from the gateway may limit the number of concurrent services running. For this release of WebLogic Tuxedo Connector, there is no WebLogic Tuxedo Connector XML configuration file parameter to increase the number of available threads. Use a reasonable thread model when invoking service EJBs. You may need to increase the number of WebLogic Server threads available to a larger value.

 

---

Configuring WebLogic Tuxedo Connector for Your Applications

Note: This release of the WebLogic Tuxedo Connector provides only static configuration. If you need to change any parameters in the WebLogic Tuxedo Connector XML configuration file, the WebLogic Server must be restarted for the changes to take effect. For example, you can not add or remove domain network links, change network addresses, or import or export new services.

This section provides information on how to configure the WebLogic Tuxedo Connector to allow WebLogic Server applications and Tuxedo applications to interoperate. Use the following main steps to configure the connector:

• Create a WebLogic Tuxedo Connector XML Configuration File

• Set the WebLogic Server Environment

• Create a StartUp Class for the WebLogic Tuxedo Connector

• Create a Shutdown Class for the WebLogic Tuxedo Connector

• Restart the Application Server

• Verify Installation

Create a WebLogic Tuxedo Connector XML Configuration File

The WebLogic Tuxedo Connector uses an XML configuration file to describe the Tuxedo /T DOMAINS connections used to link WebLogic Server to Tuxedo.

Note: A WebLogic Tuxedo Connector XML configuration file must be installed on all WebLogic Servers with JATMI instances.

• Create an XML configuration file by using a text editor, such as vi or WordPad.

• The most efficient method to create a new configuration file is to modify one of the example configuration files located in the WebLogic Tuxedo Connector distribution examples directory, such as: \examples\simpapp\DBMCONFIG.xml

• Save the configuration file with your WebLogic Server application.

Note: For more information on configuration file hierarchy and element definitions, see The WebLogic Tuxedo Connector XML Configuration File.

Configuration File Components

A WebLogic Tuxedo Connector configuration file consists of the following sections:

• Version

• DOCTYPE

• WTC_CONFIG

• BDMCONFIG

• tBridge

Version

Required. Specifies the version of XML used.

Example: <?xml version="1.0"?>

DOCTYPE

Required. The DOCTYPE declaration provides the location of the wtc_config.dtd. When the WebLogic Server is started, the WebLogic Tuxedo Connector XML configuration file is checked against the document type definition (DTD) for errors. BEA maintains the WebLogic Tuxedo Connector DTD at the following location: http://www.bea.com/servers/wls610/dtd/wtc_config.dtd

Example:

<!DOCTYPE WTC_CONFIG SYSTEM 
"http://www.bea.com/servers/wls610/dtd/wtc_config.dtd">

WTC_CONFIG

Required. WTC_CONFIG element is the root of the configuration file. WTC_CONFIG has two child elements:

• BDMCONFIG

• tBridge

BDMCONFIG

Note: For more information on how to configure BDMCONFIG, see Configuring BDMCONFIG.

Required. BDMCONFIG describes connectivity information and security protocols used by the WebLogic Tuxedo Connector to process service requests between WebLogic Server and Tuxedo. These configuration parameters are analogous to the interoperability attributes required for communication between Tuxedo domains. The following child elements make up the BDMCONFIG:

• T_DM_LOCAL_DOMAIN: provides a view of local domains as they appears to other (remote) domains.

• T_DM_REMOTE_TDOMAIN: provides a view of remote domains as they appear to the local domains.

• T_DM_EXPORT: provides information on services exported by a local domain.

• T_DM_IMPORT: provides information on services available on remote domains imported to local domains.

• T_DM_PASSWORD: provides configuration information for inter-domain authentication through access points of type TDOMAIN.

• T_DM_RESOURCES: provides information to specify global field table classes and application passwords for domains.

tBridge

Note: For more information on how to configure the tBridge, see Configuring tBridge.

Optional. The tBridge is a bi-directional JMS interface to imported Tuxedo services. Configuring this section causes the tBridge to start as part of the WebLogic Server application environment.

Using a Local Copy of the wtc_config.dtd

WebLogic Tuxedo Connector uses an external internet connection lookup the wtc_config.dtd file from the BEA DTD repository. You may need to use a local copy of the wtc_config.dtd file to meet the security requirements of your installation. If you need to create a local copy of the wtc_config.dtd, do the following:

• Save a copy of the wtc_config.dtd in your local directory. Make sure it is saved as a text file.

• Update the DOCTYPE declaration of the wtc_config.dtd in your local directory to reflect the new fully qualified path and file name. Remember to change http to file.

Example:

<!DOCTYPE BDMCONFIG SYSTEM 
"file:my_bea_directory\weblogic\wtc\gwt\wtc_config.dtd">

Validate the XML file

Validate your configuration file using WTCValidateCF. This utility allows you to validate the XML configuration file before booting WebLogic Server.

To validate the XML configuration file, enter the following command:

 > java weblogic.wtc.gwt.WTCValidateCF your_XML_configuration_file

where your_XML_configuration_file is the name of your XML configuration file.

Set the WebLogic Server Environment

You need to set the environment of your WebLogic Server application by running the setEnv script.

- NT/2000 users: run setEnv.cmd

- UNIX users: run setEnv.sh

If you are setting the environment for the first time, you will need to review the settings in the script. If necessary, use the following steps to modify the settings for your application environment:

1. From the command line, change directories to the location of the WebLogic Server application.

2. Edit the setEnv script with a text editor, such as vi.

   - NT/2000 users: edit setEnv.cmd

   - UNIX users: edit setEnv.sh

3. Save the file.

Note: The setExamplesEnv file is used to set the environment for the WebLogic Server examples provided with your distribution.

Create a StartUp Class for the WebLogic Tuxedo Connector

In order to use the WebLogic Tuxedo Connector, you must create a WebLogic Server Startup class and assign the location of the configuration file as a property of the startup class. Use the following steps to create a Startup Class for a domain:

1. Run the startWebLogic script.

   - NT/2000 users: run startWebLogic.cmd

   - UNIX users: run startWebLogic.sh

   WebLogic Server starts.

2. Start the WebLogic Server Console.

3. If necessary, right-click on the domain root and select Create or edit other domains. Left-click to select a domain from the repository.

4. Left-click and expand the Deployments branch.

5. Right-click on the Startup & Shutdown branch.

6. Select Create a new Startup Class . . .

   The Configuration tab is active.

7. Enter the Name.

   Example: MyWTCStartup Class

8. Enter weblogic.wtc.gwt.WTCStartup for the Classname.

9. Enter the Arguments. If more than one argument is used, separate them using a comma. Valid arguments include:

   BDMCONFIG: This required argument specifies the location of the WebLogic Tuxedo Connector XML configuration file.

   Example: BDMCONFIG=.\config\mydomain\wtc_config.xml

   • TraceLevel: This optional argument specifies the level of error tracing used.

     Example: BDMCONFIG=.\config\mydomain\wtc_config.xml,TraceLevel=100000

   • PasswordKey: This optional argument specifies the password key used for encrypting passwords when configuring local and remote domains.

     BDMCONFIG=.\config\mydomain\wtc_config.xml,PasswordKey=mykey

10. Check Abort startup on failure.

11. Click Create.

12. Select the Target tab.

13. From the Available servers list, click on the server you wish to select.

    The server is highlighted.

14. Click on the right-arrow.

    The selected server appears in the Chosen servers list.

15. Click Apply.

Create a Shutdown Class for the WebLogic Tuxedo Connector

Use the following steps to create a shutdown class for a domain:

1. Right-click on the Startup & Shutdown branch.

2. Select Create a new Shutdown Class . . .

3. Enter the Name.

   Example: MyWTCShutdown Class

4. Enter weblogic.wtc.gwt.WTCShutdown for the Classname.

5. Click Create.

Restart the Application Server

To make the console changes active, you must shut down and restart the application server.

Verify Installation

Check the WebLogic Server config.xml file. The WebLogic Tuxedo Connector configuration is added to the WebLogic Server StartUp and Shutdown Classes.

.

.

.

<StartupClass
          Arguments="BDMCONFIG=d:\bea\wlserver6.1\config\examples\bdmconfig.xml,Trac
eLevel=100000"
          ClassName="weblogic.wtc.gwt.WTCStartup" FailureIsFatal="true"
          Name="MyWTCStartup Class" Targets="examplesServer"/>
<ShutdownClass ClassName="weblogic.wtc.gwt.WTCShutdown" Name="MyWTCShutdown 
Class"/>

.

.

.

If you have configured TraceLevel, you can view the Weblogic Server log file for WebLogic Tuxedo Connector entries. You should see messages similar to those shown below when TraceLevel=100000:

.

.

.

####<Jul 25, 2001 6:27:38 PM EDT> <Debug> <WTC> <randyr-nt> <examplesServer> 
<Thread-3> <system> <> <180056> <]/WTCStartup/crossCheck/50/true> 

####<Jul 25, 2001 6:27:38 PM EDT> <Debug> <WTC> <randyr-nt> <examplesServer> 
<Thread-3> <system> <> <180056> <]/WTCStartup/extractInfo/80/true; DONE> 

####<Jul 25, 2001 6:27:38 PM EDT> <Debug> <WTC> <randyr-nt> <examplesServer> 
<Thread-3> <system> <> <180056> <]/WTCStartup/loadFile/90/void; LOADED> 

####<Jul 25, 2001 6:27:38 PM EDT> <Info> <WTC> <randyr-nt> <examplesServer> 
<Thread-3> <system> <> <180001> <Done Loading the XML config file.> 

####<Jul 25, 2001 6:27:38 PM EDT> <Debug> <WTC> <randyr-nt> <examplesServer> 
<Thread-3> <system> <> <180056> <Done loading the XML Config File.> 

####<Jul 25, 2001 6:27:38 PM EDT> <Debug> <WTC> <randyr-nt> <examplesServer> 
<Thread-3> <system> <> <180056> <Setting up federation points> 

####<Jul 25, 2001 6:27:38 PM EDT> <Debug> <WTC> <randyr-nt> <examplesServer> 
<Thread-3> <system> <> <180056> <Federating [TDOM1] to [tgiop://TDOM1]> 

####<Jul 25, 2001 6:27:38 PM EDT> <Debug> <WTC> <randyr-nt> <examplesServer> 
<Thread-5> <> <> <180056> <[/WTCStartup/OatmialListener/run/> 

####<Jul 25, 2001 6:27:38 PM EDT> <Debug> <WTC> <randyr-nt> <examplesServer> 
<Thread-3> <system> <> <180056> </WTCStartup/recover returned null> 

####<Jul 25, 2001 6:27:38 PM EDT> <Debug> <WTC> <randyr-nt> <examplesServer> 
<Thread-3> <system> <> <180056> <]/WTCStartup/startup/100/WTC started...> 

####<Jul 25, 2001 6:27:38 PM EDT> <Info> <WebLogicServer> <randyr-nt> 
<examplesServer> <Thread-3> <system> <> <000288> <weblogic.wtc.gwt.WTCStartup 
reports: WTC started...> 

.

.

.

If your installation is not successful, see Troubleshooting The WebLogic Tuxedo Connector.

 

---

Configuring WebLogic Tuxedo Connector for Non-ASCII Coding Sets

Note: For more information about setting WebLogic Server properties, see Starting and Stopping WebLogic Servers.

To transfer non-ascii (multibyte) strings between WebLogic Server and Tuxedo applications, you must configure WebLogic Tuxedo Connector to provide character set translation. WebLogic Tuxedo Connector uses a WebLogic Server property to match the encoding used by all the Tuxedo remote domains specified in a WebLogic Tuxedo Connector service. If you require more than one coding set running simultaneously, you will require WebLogic Tuxedo Connector services running in separate WebLogic Server instances.

To enable character set translation, update the JAVA_OPTIONS variable in your server start script. Example:

JAVA_OPTIONS=-Dweblogic.wtc.encoding=codesetname

where codesetname is the name of a supported codeset used by a remote Tuxedo domain. See Supported Encodings for list of supported base and extended coding sets.

You may not be able to select the exact encoding name to match the encoding used by the remote domain. In this situation, you should select an encoding name that is equivalent to the remote domain.

Example:

• The Supported Encoding list includes EUC_JP

• The remote domain is supported by a Solaris operating system using eucJP

Although the names don't match exactly, EUC_JP and eucJP are equivalent encoding sets and provide the correct string translation between WebLogic Server and your remote domain. You should set the encoding property to EUC_JP:

JAVA_OPTIONS=-Dweblogic.wtc.encoding=EUC_JP