Chapter 3   The Tuxedo Management Console


This chapter describes how to configure the iPlanet Application Server Enterprise Connector for Tuxedo using the Tuxedo Management Console.

This chapter covers the following topics:

• Overview

• Launching the Tuxedo Management Console

• Configuring the Tuxedo Enterprise Connector

• Tuxedo Management Console Operations

• Read Only Nodes

• Deploying the Repository Content

• Setting Parameters for International Applications

• Jolt Migration

Overview

---

In order to access the Tuxedo service(s) using the Tuxedo Enterprise Connector, the following information must be set in the iPlanet Application Server:

• Tuxedo /T server information including:
  • The workstation listener's network address through which the Tuxedo workstation clients gain access to the Tuxedo server

  • Security level defined on the Tuxedo /T server

  • Application password, if required

  • User name, client name and user password, if required

• Tuxedo workstation client installation directory (Tuxedo /WS)

• Tuxedo services available on the Tuxedo server. Tuxedo can have many services such as ADD_EMPLOYEE, GET_EMPLOYEE, CHANGE_EMPLOYEE, and ASSIGN_PROJECT. Any or all of these service definitions can be defined in the iPlanet Application Server

• Tuxedo Field Manipulation Language (FML) field definition information, if any Tuxedo service uses FML as an input or output parameter

• Tuxedo VIEW information, if any Tuxedo service uses VIEW buffer type as an input or output parameter

The Tuxedo Management Console allows to import and store the above required information into the UIF Repository. The Tuxedo Enterprise Connector runtime uses this information to process Java-based client requests to invoke the Tuxedo services.

The Tuxedo Management Console is also used to configure connection pool parameters to fine tune the runtime performance of the overall web application.

Launching the Tuxedo Management Console

---

This section describes how to launch the Tuxedo Management Console. The management console is stand alone Java-based Graphical User Interface (GUI) tool used to configure the Tuxedo enterprise connector.

On Windows NT

To launch the management console, select Start->Programs->iPlanet Application Server 6.0->TUXEDO Connector 6.0 - Management Console or type the following command tuxConsole.bat at the DOS prompt.

On Unix

To launch the management console, type the following command at the Unix prompt:

<ias directory>/ias/APPS/bin/tuxedoconsole.sh

The Tuxedo Management Console main window is displayed as shown in Figure 3-1.

Figure 3-1    Tuxedo Management Console Main Window

The management console is used to perform the following operations:

• Create a new datasource

• Edit an existing datasource

• Import Tuxedo FML field definitions

• Import Tuxedo VIEW definitions

• Import Tuxedo Service definitions

• Configure Tuxedo server authentication information

• Configure connection pool parameters

Please refer to "Tuxedo Management Console Operations" for detailed descriptions on how to perform a specific operation.

---

Note	The management console is a stand alone Java-based GUI tool which uses the iPlanet Directory Server installed with your iPlanet Application Server. The iPlanet Directory Server must be up and running to use the management console. There is no need to start the iPlanet Application Server.

---

Configuring the Tuxedo Enterprise Connector

---

This section explains basic configuration concepts, configuration parameters, a procedure to import the Tuxedo services with associated input and output parameters, and setting the connection pool parameters to fine tune the web application.

The following topics are covered:

• Tuxedo Datasources

• Tuxedo Services IDL File

• Importing Tuxedo Data Types and Services

• Connection Pooling

• Tuxedo Authentication Contexts and User Mapping

Tuxedo Datasources

A datasource in UIF represents a single EIS instance and defines the business functions (function objects) available for execution on the datasource. In the context of the Tuxedo Enterprise Connector, a datasource is mapped to the Tuxedo Server and business functions are mapped to Tuxedo services.

Multiple datasources can coexist and each datasource can be configured to connect to a separate Tuxedo server (Tuxedo /T). Also, more than one datasource can be configured to connect to the same Tuxedo server with different sets of Tuxedo services. There is no limit on the number of datasources that can be defined. The management console uses the Create New Data Source and Edit Data Source features to create a new datasource or to modify an existing datasource.

A datasource consists of the EIS configuration, data type definitions, service provider definitions, function objects, pool definitions, and user mapping information. Refer to the iPlanet Application Server Unified Integration Framework Developer's Guide for more information.

The Tuxedo Enterprise Connector comes with the following two preconfigured datasources:

• Tuxedo-OnlineBank

• Tuxedo-SimpApp

These datasources are configured to connect to a single Tuxedo server with different services based on information provided during installation.

Figure 3-2    Tuxedo-OnlineBank Datasource

Figure 3-3    Tuxedo-SimpApp Datasource

Datasource Configuration Parameters

The following parameters are associated with each datasource:

• TUXDIR

• WSNADDR

• WSDEVICE

• SECURITY

• APPLICATION PASSWORD

• CLIENTNAME

• MAX_CHANNELS_PER_PROCESS

The system prompts for parameter values while creating a new datasource using the management console. Some parameters can be modified later using the Edit Data Source feature.

TUXDIR
This is the Tuxedo workstation (Tuxedo /WS) installation root directory and must be installed on the same machine as the iPlanet Application Server.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dataSourceName>.config.ENVIRONMENT.TUXDIR

For example, d:\tuxedows (NT) and /export/home/tuxedows (Unix).

WSNADDR
Specifies the workstation listener process network address through which the Tuxedo Enterprise Connector's workstation clients gain access to the Tuxedo server. WSNADDR must be specified in one of the following formats:

//host_name:port_number

//#.#.#.#:port_number

You can specify more than one address by including a comma separated list of pathnames for WSNADDR. You can use this advanced syntax to take advantage of Tuxedo server load balancing and fail over functionality. Please refer BEA Tuxedo documentation for additional information.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dataSourceName>.config.ENVIRONMENT.WSNADDR

For example, //horse:9999 and //192.18.117.141:9999.

WSDEVICE
Specifies the device used to access the network. It should be set to /dev/tcp for TCP/IP or left blank.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dataSourceName>.config.ENVIRONMENT.WSDEVICE

For example, /dev/tcp.

SECURITY
Specifies the security level defined on the Tuxedo server. The BEA Tuxedo server provides several levels of security, as follows:

• NONE

• APP_PW

• USER_AUTH

• ACL

• MANDATORY_ACL

The Tuxedo administrator configures the security level. Consult your Tuxedo administrator for the security level setting. The following table shows the security level mappings.

Tuxedo Security Level	SECURITY Parameter Value
NONE	TPNOAUTH
APP_PW	TPSYSAUTH
USER_AUTH	TPAPPAUTH
ACL	TPAPPAUTH
MANDATORY_ACL	TPAPPAUTH

• NONE

  No additional information is needed to connect a workstation client to the Tuxedo server.

• APP_PW

  This security level requires an application password which is placed in the passwd field of the TPINIT buffer when a workstation client connects to the Tuxedo server.

• USER_AUTH, ACL, and MANDATORY_ACL

  These security levels requires application password and user specific data (user name, client name, and user password) to connect to the Tuxedo server.

  The parameters are placed in the passwd, usrname, cltname, data, and datalen fields of the TPINIT buffer when a workstation client connects to the Tuxedo server.

  Refer to "User Mapping" for details on how to configure user specific data.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dataSourceName>.config.SECURITY

For example, TPNOAUTH, TPSYSAUTH, and TPAPPAUTH.

APPLICATION PASSWORD
Specifies the application password and is required when the SECURITY level is set to either TPSYSAUTH or TPAPPAUTH. The setting is ignored with security level TPNOAUTH.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dataSourceName>.config.PASSWORD

For example, iastux.

CLIENTNAME
Specifies the client name. The parameter is set to iastuxadapter by default and cannot be modified. The parameter is used only when the security level is set to TPNOAUTH or TPSYSAUTH. The parameter is passed in the cltname field of the TPINIT buffer when a client joins the Tuxedo system. The Tuxedo administrator can easily identify the list of all enterprise connector clients who have joined the Tuxedo server and is used for administration purposes.

When the security level is set to TPAPPUTH the client name is defined as part of the user mappings (Tuxedo Authentication) instead of the CLIENTNAME parameter. Refer to "Connection Pooling" for details.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dataSourceName>.config.CLIENTNAME

For example, iastuxadapter.

MAX_CHANNELS_PER_PROCESS
The maximum concurrent channels per Tuxedo worker process and must be greater than or equal to 1, and less than or equal to 50. By default its set to 50. Refer to "Connection Pooling" for details.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dataSourceName>.config.MAX_CHANNELS_PER_PROCESS

For example, 50.

Tuxedo Services IDL File

BEA Tuxedo doesn't provide an API for querying services available on a Tuxedo server. Therefore, the management console cannot automatically discover and import them into the UIF Repository. The definition of these Tuxedo services must be specified manually. The enterprise connector defines a DCE IDL-based file format which allows users to define the Tuxedo services and their associated parameters. The management console uses the IDL files and loads them into the UIF Repository.

IDL File Syntax

The IDL file has three main components:

• Interface

• Services

• Parameters

The file name containing the interface definition have a .idl suffix and using the convention makes the file type self documenting.

Interface
The interface is the first component and wraps around the other two. The interface begins with the word interface followed by the interface name, an open brace, service definition, a closed brace, and a semicolon to signify closure. Multiple service definitions can be defined within a single interface.

interface InterfaceName{    <services>       <<parameter>> };

Services
A Service contains the word void, the Tuxedo service name, an open parenthesis, the input and output parameters, a closed parenthesis and a semicolon to signify closure. Multiple parameters can be defined for a single service.

void ServiceName(    <parameters> );

Parameters
Parameters contain the in or out keyword, the Tuxedo buffer type, parameter name, and any buffer type specific information.

The parameter block for Tuxedo buffer types STRING, CARRAY, and X_OCTET is defined as follows:

[in|out] TYPE PARAM_NAME TYPE : STRING | CARRAY | X_OCTET PARAM_NAME : Valid Parameter Name

The parameter block for Tuxedo buffer types FML and FML32 is defined as follows:

[in|out, FML] TYPE PARAM_NAME [in|out, FML32] TYPE PARAM_NAME TYPE : CHAR | STRING | SHORT | LONG | FLOAT | DOUBLE | CARRAY PARAM_NAME : FML_FIELD_NAME | FML_FIELD_NAME[] Note: FML_FIELD_NAME[] format is used to specify the multiple occurence attribute of FML field.

The parameter block for Tuxedo buffer types VIEW, VIEW32, X_COMMON, and X_C_TYPE is defined as follows:

[in, TYPE VIEW_NAME] TYPE inputBlock [out, TYPE VIEW_NAME] TYPE outputBlock TYPE : VIEW16 | VIEW32 | X_COMMON | X_C_TYPE VIEW_NAME : Tuxedo View Name Note: in must follow inputBlock out must follow outputBlock view name - name follows after VIEW clause in Tuxedo view definition file

Sample Services IDL Files

The following is a list of sample services IDL files:

Sample 1
The following listing shows a sample IDL file to demonstrate how-to use STRING, CARRAY, and X_OCTET Tuxedo buffer types as input and output parameters:

interface sample1 {     void STRINGTEST1 ( [in] STRING inParam [out] STRING outParam     );         void STRINGTEST2 ( [out] STRING outParam     );     void STRINGTEST3 ( [in] STRING inParam     );     void CARRAYTEST1 ( [in] CARRAY inParam [out] CARRAY outParam     );     void CARRAYTEST2 ( [out] CARRAY outParam     );     void CARRAYTEST3 ( [in] CARRAY inParam     );     void XOCTETTEST1 ( [in] X_OCTET inParam [out] X_OCTET outParam     );     void XOCTETTEST2 ( [out] X_OCTET outParam     );     void XOCTETTEST3 ( [in] X_OCTET inParam     ); };

Sample 2
The following listing shows a sample IDL file to demonstrate how-to use FML and FML32 Tuxedo buffer types as input and output parameters:

interface sample2 {    void FML16TEST1 ( [in, FML] STRING string16 [out,FML] STRING string16[] ); void FML16TEST2 ( [out,FML] CHAR char16[] ); void FML16TEST3 ( [in, FML] STRING string16 [in, FML] SHORT short16 [in, FML] DOUBLE double16 [in, FML] FLOAT float16 [in, FML] LONG long16 );    void FML32TEST1 ( [in, FML32] STRING string32 [out,FML32] STRING string32[] ); void FML32TEST2 ( [out,FML32] CARRAY carray32[] ); void FML32TEST3 ( [in, FML32] STRING string32 [in, FML32] SHORT short32 [in, FML32] DOUBLE double32 [in, FML32] FLOAT float32 [in, FML32] LONG long32 ); };

The above sample uses the following FML field definitions:

// FML 16 # name number type flags comments *base 1000 char16 1 char - this is a char field string16 2 string - this is a string field short16 3 short - this is a short field long16 4 long - this is a long field float16 5 float - this is a float field double16 6 double - this is a double field carray16 7 carray - this is a carray field // FML32 # name number type flags comments *base 2000 char32 1 char - this is a char field string32 2 string - this is a string field short32 3 short - this is a short field long32 4 long - this is a long field float32 5 float - this is a float field double32 6 double - this is a double field carray32 7 carray - this is a carray field

Sample 3
The following listing shows a sample IDL file to demonstrate how-to use VIEW, VIEW32, X_COMMON, and X_C_TYPE Tuxedo buffer types as input and output parameters:

interface sample3 { void VIEW16TEST1 ( [in, VIEW16 v16test1] VIEW16 inputBlock [out, VIEW16 v16test1] VIEW16 outputBlock ); void VIEW16TEST2 ( [in, VIEW16 v16test1] VIEW16 inputBlock [out, VIEW16 v16test2] VIEW16 outputBlock ); void VIEW16TEST3 ( [in, VIEW16 v16test4] VIEW16 inputBlock ); void VIEW16TEST4 ( [out, VIEW16 v16test4] VIEW16 outputBlock ); void VIEW32TEST1 ( [in, VIEW32 v32test1] VIEW32 inputBlock [out, VIEW32 v32test1] VIEW32 outputBlock ); void VIEW32TEST2 ( [in, VIEW32 v32test1] VIEW32 inputBlock [out, VIEW32 v32test2] VIEW32 outputBlock ); void VIEW32TEST3 ( [in, VIEW32 v32test4] VIEW32 inputBlock ); void VIEW32TEST4 ( [out, VIEW32 v32test4] VIEW32 outputBlock ); void XCOMMONTEST1 ( [in, X_COMMON xcomtest1] X_COMMON inputBlock [out, X_COMMON xcomtest2] X_COMMON outputBlock ); void XCTYPETEST1 ( [in, X_C_TYPE xctest1] X_C_TYPE inputBlock [out, X_C_TYPE xctest2] X_C_TYPE outputBlock ); };

The above sample uses the following VIEW definitions (only few elements are shown for each view for simplicity):

VIEW v16test1 # type cname fbname count flag size null string str1 - 1 - 100 - END VIEW v16test2 # type cname fbname count flag size null double double1 - 5 - - - END VIEW v16test4 # type cname fbname count flag size null string str1 - 1 - 100 "UIF_TUX_STRING_NULL" END VIEW v32test1 # type cname fbname count flag size null char char1 - 1 - - - long long1 - 1 - - - END VIEW v32test2 # type cname fbname count flag size null int int1 - 5 - - - dec_t dec1 - 5 - 9,2 - END VIEW v32test4 # type cname fbname count flag size null double double1 - 1 - - 987.654 END VIEW xcomtest1 # type cname fbname count flag size null string str1 - 1 - 100 - END VIEW xcomtest2 # type cname fbname count flag size null long long1 - 10 - - - END VIEW xctest1 # type cname fbname count flag size null short short1 - 1 - - - END VIEW xctest2 # type cname fbname count flag size null char char1 - 10 - - - END

Sample 4
Sample .idl file for services defined in the Tuxedo OnlineBank and Simpapp sample applications:

interface sample4 { void TOUPPER( [in] STRING STRING [out] STRING STRING ); void CLOSE_ACCT( [in,FML] LONG ACCOUNT_ID [out,FML] STRING SBALANCE ); void DEPOSIT( [in,FML] STRING SAMOUNT [in,FML] LONG ACCOUNT_ID [out,FML] STRING SBALANCE ); void INQUIRY( [in,FML] LONG ACCOUNT_ID [out,FML] STRING SBALANCE ); void OPEN_ACCT( [in,FML] STRING SAMOUNT [in,FML] STRING LAST_NAME [in,FML] STRING FIRST_NAME [in,FML] CHAR MID_INIT [in,FML] CHAR ACCOUNT_TYPE [in,FML] STRING ADDRESS [in,FML] STRING PHONE [in,FML] STRING SSN [in,FML] LONG BRANCH_ID [out,FML] LONG ACCOUNT_ID [out,FML] STRING SBALANCE ); void TRANSFER( [in,FML] LONG ACCOUNT_ID[] [in,FML] STRING SAMOUNT [out,FML] STRING SBALANCE[] );    void WITHDRAW( [in,FML] LONG ACCOUNT_ID [in,FML] STRING SAMOUNT [out,FML] STRING SBALANCE ); };

The Online Bank Services sample uses the following FML field definitions:

# Fields for database bankdb # name number type flags comments ACCOUNT_ID 110 long - - ACCT_TYPE 112 char - - ADDRESS 109 string - - AMOUNT 117 float - - BALANCE 105 float - - BRANCH_ID 104 long - - FIRST_NAME 114 string - - LAST_ACCT 106 long - - LAST_NAME 113 string - - LAST_TELLER 107 long - - MID_INIT 115 char - - PHONE 108 string - - SSN 111 string - - TELLER_ID 116 long - - # # non database fields SBALANCE 201 string - - SAMOUNT 202 string - - XA_TYPE 203 short - - CURS 204 string - - SVCHG 205 string - - VIEWNAME 206 string - - OPEN_CR 207 char - - TYPE_CR 208 char - - STATLIN 209 string - -

Importing Tuxedo Data Types and Services

This section describes the basic procedure or steps to import the Tuxedo data types and services into UIF Repository. The metadata describing the Tuxedo data types and services must be present in the UIF Repository prior to starting the web application development using the Tuxedo Enterprise Connector.

Perform the following steps to import Tuxedo data types and services:

1. Create a new datasource

   Create a new datasource using the Create New Data Source option provided with the management console. Refer to "Create New Data Source" for detailed information.

   The management console must be restarted in order to use the newly created datasource.

2. Create Services IDL file

   Create a Tuxedo services IDL file (as described in "Tuxedo Services IDL File") which contains the Tuxedo services definitions to be imported into the UIF Repository.

   The enterprise connector supports STRING, CARRAY, X_OCTET, FML, FML32, VIEW, VIEW32, X_COMMON, and X_C_TYPE Tuxedo buffer types. Any Tuxedo service definition which uses these buffer types can be included. There is no limit on the number of services that can be included in an IDL file. Custom buffer types are not supported.

3. Import the FML field table definitions

   This step is mandatory, if any Tuxedo service uses an FML buffer type. Use the FML 16 Import feature in the management console to perform this step (refer to page 95).

   An FML buffer is a self defining Tuxedo data type where each data field carries its own identifier, an occurrence number, and possibly a length indicator.

   The FML field table file must be specified as an input to this step. This is the text file created during the Tuxedo services design and development stage, and contains the FML fields definition. This is the same file given as an input to mkfldhdr to create a header file included in the Tuxedo service routine or client programs. There are no restrictions on the number of fields defined in a single file. Create a single file containing the FML field definitions used in all services. Because it is a text file the file can be used across all platforms.

   This information is stored under the following node:

   bsp.dataSources.<dsName>.config.FML_TABLE

   The node contents must match the header file contents generated using mkfldhdr during the Tuxedo service(s) development stage.

   The following listing shows a sample FML field table file:

   # name number type flags comments *base 3000 EMP_EMPNO 1 long - - EMP_NAME 2 string - - EMP_SSN 3 string - - EMP_PHONE 4 string - - EMP_DEPT 5 long - - EMP_SALARY 6 float - -

4. Import FML32 field table definitions

   This step is mandatory, if any Tuxedo service uses the FML32 buffer type. Use the FML 32 Import feature in the management console to perform this step (refer to page 98).

   The FML32 data type is similar to FML but allows for larger character fields, more fields, and larger buffers.

   The FML32 field table file must be specified as an input to this step. This is the text file created during the Tuxedo services design and development stage, and contains the FML32 fields definition. This is the same file given as an input to mkfldhdr32 to create a header file included in the Tuxedo service routine or client programs. There are no restrictions on the number of fields defined in a single file. Create a single file containing the FML32 field definitions used in all services. Because it is a text file the file can be used across all platforms.

   This information is stored under the following node:

   bsp.dataSources.<dsName>.config.FML32_TABLE

   The node contents must match the header file contents generated using mkfldhdr32 during the Tuxedo service(s) development stage.

   The following listing shows a sample FML32 field table file:

   # name number type flags comments *base 2000 char32 1 char - this is a char field string32 2 string - this is a string field short32 3 short - this is a short field long32 4 long - this is a long field float32 5 float - this is a float field double32 6 double - this is a double field carray32 7 carray - this is a carray field

5. Import VIEW data types

   This step is mandatory, if any Tuxedo services uses the VIEW buffer type. A view object file or view compiled file must be specified as an input to this step. Compiled view files are platform specific and must be generated on the same system the enterprise connector is on. Use the VIEW 16 Import feature in the management console to perform this step (refer to page 100).

   VIEW is a built in Tuxedo buffer type provided to use C structures and COBOL records with the Tuxedo server. VIEW type buffers must have sub types, which designate individual data structures.

   To use VIEW buffers, the C structure or COBOL record is first defined in a view file created with a text editor. The each structure or records description is called a view and more than one view can be defined in a single view file. Each view is given a name. The view file is converted into an object format by the view compiler (viewc) which takes the view file as an input file. The view compiler generates a compiled view file, and a header file to include in the service routine and client applications. The Tuxedo runtime server uses this compiled view file. Compiled view files will have a VV extension on Windows NT and V on Unix systems.

   This information is stored under the following node:

   bsp.dataSources.<dsName>.dataTypes.VIEW_TABLE

   The following listing shows a sample VIEW file (test_view.txt):

   VIEW v16test1 # type cname fbname count flag size null char char1 - 1 - - - string str1 - 1 - 100 - carray cary1 - 1 - 100 - long long1 - 1 - - - short short1 - 1 - - - int int1 - 1 - - - float float1 - 1 - - - double double1 - 1 - - - dec_t dec1 - 1 - 9,2 - END

   Run the viewc -n test_view.txt command to generate a view object file test_view.VV (Windows NT) or test_view.V (Unix) file is the input to this step.

6. Import VIEW32 data types

   This step is mandatory, if any Tuxedo services uses the VIEW32 buffer type. A view32 compiled file or view32 object file must be specified as an input to this step. Compiled view files are platform specific and must be generated on the same system the enterprise connector is on. Use the VIEW 32 Import feature in the management console to perform this step (refer to page 102).

   The VIEW32 buffer type is similar to VIEW but allows for character fields, more fields, and larger overall buffer sizes.

   Compiled files are generated by calling the view32 compiler (viewc32) on a view32 definition file.

   This information is stored under the following node:

   bsp.dataSources.<dsName>.dataTypes.VIEW32_TABLE

7. Import X_COMMON data types

   This step is mandatory, if any Tuxedo services uses the X_COMMON buffer type. The view object file or view compiled file must be specified as an input to this step. Use the X_COMMON Import feature in the management console to perform this step (refer to page 104). Compiled view files are system specific and must be generated on the same system the enterprise connector is on.

   The X_COMMON buffer type is similar to VIEW but with field types limited to short, long, and string.

   Compiled files are generated by calling the view compiler (viewc) on a X_COMMON definition file.

   This information is stored under the following node:

   bsp.dataSources.<dsName>.dataTypes.X_COMMON_TABLE

8. Import X_C_TYPE data types

   This step is mandatory, if any Tuxedo services uses the X_C_TYPE buffer type. The view object file or view compiled file must be specified as an input to this step. Use the X_C_TYPE Import feature in the management console to perform this step (refer to page 106). Compiled view files are platform specific and must be generated on the same system the enterprise connector is on.

   The X_C_TYPE buffer type is equivalent to VIEW.

   Compiled files are generated by calling the view compiler (viewc) on a X_C_TYPE definition file.

   This information is stored under the following node:

   bsp.dataSources.<dsName>.dataTypes.X_C_TYPE_TABLE

9. Import Tuxedo Services

   You must use the IDL file created in Step 2 as the input. This step populates the Tuxedo services definitions in IDL file into the UIF Repository. Use the Services Import feature in the management console to perform this step (refer to page 108).

   Make sure that all dependent data types are imported before performing this step.

   Each service is mapped to a Function Object under the following node:

   bsp.dataSources.<dsName>.functionObjectTemplates

10. Verify the UIF Repository Content

    Verify the UIF Repository content using the UIF repository browser. Give special attention to the input and output data blocks defined for each function object and configuration parameters, there should be no unresolved nodes. The unresolved nodes are marked with X in RED. Generally, unresolved nodes occur when imported services IDL file without importing the dependent data types, for example, FML and VIEW information.

    
    

    ---

    Note

    The management console uses <iAS InstallDir>/ias/APPS directory to write the temporary files generated during the import process. These files are automatically deleted at the end of import process. In order to perform successfully the console operations, the user must have read-write permissions to the above directory. The metadata is stored in iPlanet Directory Server used with your instance of iPlanet Application Server. You must re-start the iPlanet Application Server to use this data by any Java application.

    ---

    
    

Connection Pooling

This section describes the pooling concepts and parameters used to configure the enterprise connector. Pooling allows resource sharing with the enterprise connector. Pools are used to share the workstation client connections to the Tuxedo server. The characteristics associated with a pool determines, the number of Tuxedo client worker processes needed and the load on each Tuxedo client worker process. Pools are defined on a per datasource basis. In other words, each datasource defines its own connection pool(s) which can be individually configured using management console.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dataSourceName>.pools.<poolName>

The enterprise connector can support more than one connection pool per datasource. A pool named default is automatically created with a new datasource, for example bsp.dataSources.<dataSourceName>.pools.default.

The number of connection pools defined for a datasource is dependent on the security level setting. For security level, TPNOAUTH (NONE) and TPSYSAUTH (APP_PW) only one pool can be defined. For security level TPAPPAUTH (USER_AUTH, ACL, and MANDATORY_ACL) more than one pool can be specified depending on the user mapping settings. Refer to "Tuxedo Authentication Contexts and User Mapping" for details.

Pool Parameters

The following characteristics are associated with each pool and are configurable:

MaxPoolSize
Maximum number of concurrent requests to be processed.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dsName>.pools.<poolName>.config.MaxPoolSize

Default value: 50

SteadyPoolSize
This should always be the same as MaxPoolSize. The kjs engine fails to load the Tuxedo Enterprise Connector, if this value differs from MaxPoolSize. Any changes to MaxPoolSize must be reflected immediately to SteadyPoolSize.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dsName>.pools.<poolName>.config.SteadyPoolSize

Default value: 50

MaxWait
The maximum time, in seconds, a request waits in the queue for a connection to Tuxedo server before it times out.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dsName>.pools.<poolName>.config.MaxWait

Default value: 600

UnusedMaxLife
The maximum time, in seconds, that a connection remains unused in the pool. Currently the Tuxedo Enterprise Connector requires a higher value to be set for this parameter. On creation of pool, this value is set to 300000. Please ensure that UnuxedMaxLife is always set to either 300000 or above.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dsName>.pools.<poolName>.config.UnusedMaxLife

Default value: 300000

MonitorInterval
The time in seconds, that the monitor thread is executed to monitor the current status of the pool. Default is 30 seconds. Typically, setting this number too low degrades performance.

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dsName>.pools.<poolName>.config.MonitorInterval

Default value: 30

DebugLevel
Determines the message logging type, as follows:

0 - Logging turned off

1 - Logs only callback messages

2 - Logs all messages

This information is stored in the UIF Repository under the following node:

bsp.dataSources.<dsName>.pools.<poolName>.config.DebugLevel

Default value: 0

Figure 3-4    Pool Parameters in the UIF Repository

The value of MaxPoolSize in conjunction with, the value of MAX_CHANNELS_PER_PROCESS defined with the datasource determine the number of Tuxedo client worker processes needed for each pool and loads on each Tuxedo client process. The enterprise connector automatically spawns the necessary number of Tuxedo client processes (MaxPoolSize and MAX_CHANNELS_PER_PROCESS) and load balances the requests across the Tuxedo client worker processes. As shown in the next three examples:

1. A default configuration:

   MaxPoolSize: 50

   SteadyPoolSize: 50

   MAX_CHANNELS_PER_PROCESS: 50

   The enterprise connector spawns one (50/50) Tuxedo client worker process to support 50 non-transactional requests.

2. An advanced configuration:

   MaxPoolSize: 100

   SteadyPoolSize: 100

   MAX_CHANNELS_PER_PROCESS: 50

   The enterprise connector spawns two (100/50) Tuxedo client worker processes to support 100 non-transactional requests. All incoming requests are automatically load balanced across the worker processes.

The above configurations gives better performance when all client requests are non-transactional. In other words, none of the requests received by the enterprise connector invokes either BEGIN or COMMIT/ROLLBACK transactional operations provided by the TransactionFO function object. In this mode, the enterprise connector, utilizes the Tuxedo server feature "maximum up to 50 pending responses for non-transactional asynchronous requests allowed per tpinit" and gives better throughput.

Only one concurrent transactional request is allowed per Tuxedo client worker process (tpinit) by the Tuxedo server. If the client requests are transactional, or a combination of transactional and non-transactional, a lower value for MAX_CHANNELS_PER_PROCESS is recommended for better throughput. The lower value for MAX_CHANNELS_PER_PROCESS for the same MaxPoolSize, forces a higher number of Tuxedo client worker process and better transactional requests throughput.

3. A more advanced configuration:

   MaxPoolSize: 100

   SteadyPoolSize: 100

   MAX_CHANNELS_PER_PROCESS: 10

   The enterprise connector spawns ten (100/10) Tuxedo client worker processes to support a mixture of transactional and non-transactional requests. All incoming requests are automatically load balanced across the worker processes.

Tuxedo Authentication Contexts and User Mapping

The enterprise connector supports multiple Tuxedo authentication contexts. Security level, user mapping, and connection pooling are used to define the Tuxedo workstation client connection behavior. This section is applicable only if the Tuxedo server is configured with security level TPAPPAUTH (USER_AUTH, ACL, or MANDATORY_ACL).

These security levels provide an authentication service that checks for the combination of user name, client name, and user password before the client is allowed to attach to the Tuxedo server. The authentication context information is passed through the TPINIT buffer when a Tuxedo workstation client joining the Tuxedo system. Multiple authentication contexts (users) can exist for a given Tuxedo server but only one authentication context is allowed per tpinit process.

A Tuxedo authentication context is defined as using a user name, client name and user password. The definition of these parameters are as follows:

User Name

A user name assigned by the Tuxedo administrator and is mapped to usrname member in the TPINIT buffer. This name may be the same used by the operating system.

Client Name

Client name whose semantics are application defined and is mapped to cltname member in the TPINIT buffer. Additionally, it can be used for administration purpose or left blank.

User Password

Password for the user/client name combination and is mapped to data and datalen members in the TPINIT buffer.

Normally, the Tuxedo server administrator uses tpaddusr, tpmodusr, and tpdelusr commands to configure the Tuxedo authentication contexts on a Tuxedo server. Refer to BEA Tuxedo documentation for further details.

The Tuxedo authentication context (user) is mapped to an Entity, as shown in Figure 3-5, in the enterprise connector and uses the following UIF Repository nodes to store the information:

bsp.dataSources.<dsName>.ENTITY_MAPPINGS.default.ENTITIES.<entityName>.usrName

bsp.dataSources.<dsName>.ENTITY_MAPPINGS.default.ENTITIES.<entityName>.cltName

bsp.dataSources.<dsName>.ENTITY_MAPPINGS.default.ENTITIES.<entityName>.data

Figure 3-5    Entity Mapping in the UIF Repository

The Tuxedo User Mapping feature (refer to page 110) in the management console is used to define each entity per datasource. The enterprise connector supports an unlimited number of entities per datasource.

A separate pool is created with each Entity because only one authentication context is allowed per tpinit process. This feature allows an enterprise connector to spawn separate client worker processes to process the client requests for this authentication context.

The pool definitions are found under the following node and is configurable:

bsp.dataSources.<dataSourceName>.pools

The web user must pass the authentication context either directly or indirectly with each request. Passing the information directly with each web request is a tedious process and error prone. Any changes to the authentication context must be sent to all web users on the system.

To simplify the process, UIF supports WebUser Entity Mapping, which allows the enterprise connector administrator to define each web user and assigns an entity (authentication context) per web user. The web user ID is passed with each request instead of the authentication context. Therefore, any change to the authentication context can be carried transparently without effecting the web users.

The application programmer assigns a WebUserId to the enterprise connector and is used to determine the authentication context to be used to process each request. A user pool exists with each context. The enterprise connector uses the pool associated with the context to process the request.

The management console provides a GUI-based interface to support creation of Entities, Web Users and associating an entity with each web user.

Tuxedo Management Console Operations

---

The operations that can be performed using the management console are divided into the following two groups:

• Tasks used to create and update the datasource, import Tuxedo data types, and services.

• User management tasks that establishes the relationship between the web and Tuxedo users.

The main management console window contains two task tabs named, Tasks and Tuxedo User Management. The Tasks tab contains icons for accessing screens to create a datasource, edit a datasource, import Tuxedo data types and services. The Tuxedo User Management tab allows you to access screens to define Tuxedo authentication contexts and configure pool parameters.

The remainder of this section describes step-by-step procedures to perform a specific task.

Create New Data Source

1. Choose the Create New Data Source feature from the Tuxedo Management Console main window and Figure 3-6 shows the displayed window:

Figure 3-6    Create Data Source Window

2. Enter the following information:
   

   
   
   

   Data Source Name	This is the name you assign to the new datasource.
   WSNADDR	Specify the network address of the workstation listener process through which workstation clients gain access to Tuxedo server. This parameter must be specified in one of the following format: //host_name:port_number //#.#.#.#:port_number
   WSDEVICE	Specify the device used to access the network. It should be set to /dev/tcp for TCP/IP. Optionally can be left blank.
   TUXDIR	The Tuxedo workstation (Tuxedo /WS) installation root directory.
   APP PASSWORD	Application password. This is required when the SECURITY level is set to either APP_PW, or USER_AUTH/ACL/MANDATORY_ACL. This parameter value is ignored with security level NONE.
   SECURITY	Specify the security level defined at Tuxedo server. Valid values: NONE APP_PW USER_AUTH/ACL/MANDATORY_AUTH The default value is NONE. Note that user specific data (user name, client name, and user password) must be defined if the security level is set to USER_AUTH/ACL/MANDATORY_AUTH. Refer to "User Mapping" for details.

3. Press the Ok button.

4. You must restart the management console to use the newly created datasource.

The new Tuxedo datasource is created under the following repository node:

bsp.dataSources

with the following top level child nodes, as shown in Figure 3-7.

• adapterType

• config

• dataTypes

• functionObjectTemplates

• functionObjectTemplates.TransactionFO

• pools

• pools.default

• serviceProviderTemplates

• serviceProviderTemplates.tuxConnectionTx

• serviceProviderTemplates.tuxConnection

• ENTITY_MAPPINGS

The MAX_CHANNELS_PER_PROCESS is set to 50 with a new datasource. The default function object, TransactionFO supports client side transactions in conjunction with tuxConnectionTx service provider. Refer to the iPlanet Application Server Enterprise Connector for Tuxedo Developer's Guide for details on how to use the TransactionFO function object.

Figure 3-7    Tuxedo Datasource in the UIF Repository

Edit Data Source

1. Choose the Edit Data Source option from the Tuxedo Management Console main window and Figure 3-8 shows the displayed Choose Data Source window:

Figure 3-8    Choose Data Source Window 

2. Select the datasource you wish to edit and press the Ok button. Figure 3-9 shows the displayed window:

Figure 3-9    Edit DataSource Window 

3. You can modify the following information:
   

   
   
   

   WSNADDR	Specify the network address of the workstation listener process through which workstation clients gain access to Tuxedo server. This parameter must be specified in one of the following format: //host_name:port_number //#.#.#.#:port_number
   WSDEVICE	Specify the device used to access the network. It should be set to /dev/tcp for TCP/IP. Optionally can be left blank.
   TUXDIR	The Tuxedo workstation (Tuxedo /WS) installation root directory.
   MAX CHANNELS	Specifies the maximum concurrent channels per Tuxedo worker process. Must be greater than or equal 1 and less than or equal to 50. Please refer to "Connection Pooling" for detail description.
   SECURITY	Specify the security level defined at Tuxedo server. Valid values: NONE APP_PW USER_AUTH/ACL/MANDATORY_AUTH
   APP PASSWORD	Application password. This is required when the SECURITY level is set to either APP_PW, or USER_AUTH/ACL/MANDATORY_ACL. This parameter value is ignored with security level NONE.

4. Select Ok button to save the information.

---

Note	The datasource name is read only and cannot be modified. To assign a new name to an existing datasource, you must first delete the existing datasource using the UIF repository browser and create a new datasource.

---

FML 16 Import

1. Choose the FML 16 Import feature from the Tuxedo Management Console main window. The Choose Data Source window is displayed as shown in Figure 3-8.

2. Select a datasource from the datasources listed and click on Ok. The Choose FML Field Table File window is displayed as shown in Figure 3-10.

3. Click on the Add Function... button and the File Selection window appears. The current directory (directory from which console started) is shown as the default directory for file selection.

4. Select FML field table definition file(s) and click the Ok button.

FML fields defined in the FML Field Table file(s) are imported under the following repository node:

bsp.dataSources.<dsName>.config.FML_TABLE

Figure 3-10    Choose FML Field Table File Window 

The following lists the sample data:

• Content of FML Field Table input file (fml16flds).

  # name number type flags comments *base 3000 EMP_EMPNO 1 long - - EMP_NAME 2 string - - EMP_SSN 3 string - - EMP_PHONE 4 string - - EMP_DEPT 5 long - - EMP_SALARY 6 float - -

• Content of header file generated by calling mkfldhdr fml16flds command. Not required for import operation. Optionally, can be used to verify the repository information after importing FML fields.

  #define EMP_EMPNO ((FLDID)11193) #define EMP_NAME ((FLDID)43962) #define EMP_SSN ((FLDID)43963) #define EMP_PHONE ((FLDID)43964) #define EMP_DEPT ((FLDID)11197) #define EMP_SALARY ((FLDID)27582)

• Figure 3-11 shows the UIF Repository information after importing fml16flds using FML 16 Import feature.

Figure 3-11    FML Data in the UIF Repository 

FML 32 Import

1. Choose the FML 32 Import feature from the Tuxedo Management Console main window. The Choose Data Source window is displayed as shown in Figure 3-8.

2. Select a datasource from the datasources listed, and click on Ok button. The Choose FML32 Field Table File window is displayed as shown in Figure 3-12.

3. Click on the Add Function... button and the File Selection window appears. The current directory (directory from which console started) is shown as the default directory for file selection.

4. Select FML32 field table definition file(s) and click the Ok button.

FML32 fields defined in the FML32 Field Table file(s) are imported under the following repository node:

bsp.dataSources.<dsName>.config.FML32_TABLE

Figure 3-12    Choose FML32 Field Table File Window 

The following lists the sample data:

• Content of FML32 Field Table file (fml32flds).

  # name number type flags comments *base 5000 CUST_NO 1 long - - CUST_NAME 2 string - - CUST_ADDRESS 3 string - -

• Content of header file generated by calling mkfldhdr32 fml32flds command. Not required for import operation. Optionally, can be used to verify the repository information after importing FML32 fields.

  #define CUST_NO ((FLDID32)33559433) #define CUST_NAME ((FLDID32)167777162) #define CUST_ADDRESS ((FLDID32)167777163)

• Figure 3-13 shows the UIF Repository information after importing fml32flds using FML 32 Import feature.

Figure 3-13    FML32 Data in the UIF Repository 

VIEW 16 Import

1. Choose the VIEW 16 Import feature from the Tuxedo Management Console main window. The Choose Data Source window is displayed as shown in Figure 3-8.

2. Select a datasource from the datasources listed, and click on Ok. The Choose VIEW Object File window is displayed as shown in Figure 3-14.

3. Click on the Add Function... button and the File Selection window appears. The current directory (directory from which console started) is shown as the default directory for file selection.

4. Select VIEW object file(s) and click the Ok button.

This information is imported under the following repository node:

bsp.dataSources.<dsName>.dataTypes.VIEW_TABLE

Figure 3-14    Choose VIEW Object File Window 

The following lists the sample data:

• Content of VIEW file (view16.txt).

  VIEW v16test1 # type cname fbname count flag size null char char1 - 1 - - - string str1 - 1 - 100 - carray cary1 - 1 - 100 - long long1 - 1 - - - short short1 - 1 - - - int int1 - 1 - - - float float1 - 1 - - - double double1 - 1 - - - dec_t dec1 - 1 - 9,2 - END

• Generate VIEW Object file (view16.VV on NT or view16.V on Unix) by running viewc -n view16.txt command.

• Figure 3-15 shows the UIF Repository information after importing view16.VV using VIEW 16 Import feature.

Figure 3-15    VIEW Data in the UIF Repository 

VIEW 32 Import

1. Choose the VIEW 32 Import feature from the Tuxedo Management Console main window. The Choose Data Source window is displayed as shown in Figure 3-8.

2. Select a datasource from the datasources listed, and click on Ok. The Choose VIEW32 Object File window is displayed as shown in Figure 3-16.

3. Click on the Add Function... button and the File Selection window appears. The current directory (directory from which console started) is shown as the default directory for file selection.

4. Select VIEW32 object file(s) and click the Ok button.

This information is imported under the following repository node:

bsp.dataSources.<dsName>.dataTypes.VIEW32_TABLE

Figure 3-16    Choose VIEW32 Object File Window 

The following lists the sample data:

• Content of VIEW32 file (view32.txt).

  VIEW v32test1 # type cname fbname count flag size null char char1 - 1 - - - string str1 - 1 - 100 - carray cary1 - 1 - 100 - long long1 - 1 - - - short short1 - 1 - - - int int1 - 1 - - - float float1 - 1 - - - double double1 - 1 - - - dec_t dec1 - 1 - 9,2 - END

• Generate VIEW32 Object file (view32.VV on NT or view32.V on Unix) by running viewc32 -n view32.txt command.

• Figure 3-17 shows the UIF Repository information after importing view32.VV using VIEW 32 Import feature.

Figure 3-17    VIEW32 Data in the UIF Repository 

X_COMMON Import

1. Choose the X_COMMON Import feature from the Tuxedo Management Console main window. The Choose Data Source window is displayed as shown in Figure 3-8.

2. Select a datasource from the datasources listed, and click on Ok. The Choose X_COMMON Object File window is displayed as shown in Figure 3-18.

3. Click on the Add Function... button and the File Selection window appears. The current directory (directory from which console started) is shown as the default directory for file selection.

4. Select X_COMMON object file(s) and click the Ok button.

This information is imported under the following repository node:

bsp.dataSources.<dsName>.dataTypes.X_COMMON_TABLE

Figure 3-18    Choose X_COMMON Object File Window 

The following lists the sample data:

• Content of X_COMMON definition file (xcomm.txt).

  VIEW xcomtest1 # type cname fbname count flag size null char char1 - 1 - - - string str1 - 1 - 100 - long long1 - 1 - - - short short1 - 1 - - - END

• Generate VIEW Object file (xcomm.VV on NT or xcomm.V on Unix) by running viewc -n xcomm.txt command.

• Figure 3-19 shows the UIF Repository information after importing xcomm.VV using X_COMMON Import feature.

Figure 3-19    X_COMMON Data in the UIF Repository 

X_C_TYPE Import

1. Choose the X_C_TYPE Import feature from the Tuxedo Management Console main window. The Choose Data Source window is displayed as shown in Figure 3-8.

2. Select a datasource from the datasources listed, and click on Ok. The Choose X_C_TYPE Object File window is displayed as shown in Figure 3-20.

3. Click on the Add Function... button and the File Selection window appears. The current directory (directory from which console started) is shown as the default directory for file selection.

4. Select X_C_TYPE object file(s) and click the Ok button.

This information is imported under the following repository node:

bsp.dataSources.<dsName>.dataTypes.X_C_TYPE_TABLE

Figure 3-20    Choose X_C_TYPE Object File Window 

The following lists the sample data:

• Content of X_C_TYPE definition file (xctype.txt).

  VIEW xctest1 # type cname fbname count flag size null char char1 - 1 - - - string str1 - 1 - 100 - long long1 - 1 - - - short short1 - 1 - - - END

• Generate VIEW Object file (xctype.VV on NT orxctype.V on Unix) by running viewc -n xctype.txt command.

• Figure 3-21 shows the UIF Repository information after importing xctype.VV using X_C_TYPE Import feature.

Figure 3-21    X_C_TYPE Data in the UIF Repository 

Import Tuxedo Services

1. Choose the Services Import feature from the Tuxedo Management Console main window. The Choose Data Source window is displayed as shown in Figure 3-8.

2. Select a datasource from the datasources listed, and click on Ok. The Choose Services IDL File window is displayed as shown in Figure 3-22.

3. Click on the Add Function... button and the File Selection window appears. The current directory (directory from which console started) is shown as the default directory for file selection.

4. Select the IDL file which contains the definition of Tuxedo services and click the Ok button.

This information is imported under the following repository node:

bsp.dataSources.<dsName>.functionObjectTemplates

There must be an entry for each service.

Figure 3-22    Choose Services IDL File Window 

The following lists the sample data:

• Content of Services IDL file (simple.idl).

  interface simple { void TOUPPER( [in] STRING STRING [out] STRING STRING ); };

• Figure 3-23 shows the UIF Repository information after importing simple.idl using the Services Import feature.

Figure 3-23    Services in the UIF Repository 

User Mapping

1. Choose the Tuxedo User Mapping tab from the Tuxedo Management Console main window.

2. Select Tuxedo User Mapping option from Tuxedo User Management tree. The Choose Data Source window is displayed as shown in Figure 3-8, if datasource is not selected. Select a datasource from the datasources listed, and click on Ok. The Tuxedo User Management main screen appears, as shown in Figure 3-24.

   Using the Tuxedo User Management main screen, you can add, edit, and delete Entity and Web User information for the selected datasource.

Figure 3-24    Tuxedo User Management Main Window 

Entity Information

You can add a new entity, change an existing entity, and delete an entity by clicking on the corresponding button.

To add a new entity, click on the New Entity... button. The Entity Information window appears, as shown in Figure 3-25.

Figure 3-25    Entity Information Window 

Type in appropriate data and click the Ok button. The new entity information appears in the Entity Information area of User Management main window.

To change entity information, select the entity to be modified in Entity Information area, then click on the Change Entity... button. Edit the desired field(s) and click on the Ok button. The updated information appears in the Entity Information area of User Management main window.

To delete an entity, select the desired entity and click on the Delete button. The entity information is removed from Entity Information area of User Management main window.

When you have completed all actions in this window, click on the Save button. All additions and changes is saved into the UIF Repository.

---

Note	An entity cannot be deleted if the web users are associated. You must first delete all associated web users before deleting an Entity.

---

Web User Information

The Web User Information is used to map a web user's identity to an EIS user's identity (Tuxedo authentication context). The administrator assigns an entity for the web user and the Web User Id is used by the application programmer to specify the authentication context to be used while processing the request.

You can add, change, and delete web user by clicking the corresponding button.

To add a web user, click on the New User... button. The Web User Information window appears, as shown in Figure 3-26.

Figure 3-26    Web User Information Window 

Type in the Web ID and select an Entity from the available entities. Click on Ok. The information is added to Web User Information area of User Management main window.

To change a user, select the desired user from list, click on the Change User... button. Edit the desired field(s) and click on Ok. The updated information appears in the Web User Information area of User Management main window.

To delete a web user, select the desired web user and click on the Delete button. The selected web user is deleted from User Management main window.

When you have completed all actions in this window, click on the Save button. All additions and changes are saved into the UIF Repository.

Changing Datasource

To perform user mapping operations on another datasource:

1. Select Tuxedo User Mapping option from Tuxedo User Management tree and click the right mouse button. The Change Data Source popup menu appears.

2. Select the Change Data Source popup menu. The Choose Data Source window is displayed as shown in Figure 3-8.

3. Select a datasource from the datasources listed, and click on Ok. The selected datasource is used for further user mapping operations.

Update Connection Pool Parameters

1. Choose the Tuxedo User Mapping tab from the main management console window.

2. Select Tuxedo Connection Pools option from Tuxedo User Management tree. The Choose Data Source window is displayed as shown in Figure 3-8, if datasource is not selected before. Select a datasource from the datasources listed, and click on Ok. The Connection Pools Information main screen appears, as shown in Figure 3-27.

Figure 3-27    Connection Pools Information Window 

3. Select the desired pool and click on Change Pool... button. The Connection Pool Information window appears, as shown in Figure 3-28.

Figure 3-28    Edit Connection Pool Window 

4. You can modify the following information:
   

   
   
   

   Debug Level	Connection Pool message logging level. Valid values: 0 - Logging turned off 1 - Logs only callback messages 2 - Logs all messages
   Max Pool Size	Maximum number of concurrent requests to be processed. Refer to "Connection Pooling" for detail information.
   Max Wait	The maximum time, in seconds, a request waits in the queue for a connection to Tuxedo server before it times out.
   Monitor Interval	The time in seconds, the monitor thread prints logging message about pool status.
   Steady Pool Size	Should be same as Max Pool Size. The field value is automatically updated for any changes to Max Pool Size field. The GUI will ensure that both the Max Pool Size and Steady Pool Size are set to same value. This is the requirement for Tuxedo Enterprise Connector.
   Unused Max Life	The maximum time, in seconds, that a connection remains unused in the pool.

   Edit the desired field(s) and click on the Ok button. The updated information appears in the Connection Pools Information area.

5. Click the Save button to store the changes into the UIF Repository.

Changing Datasource

To update a pool defined for another datasource:

1. Select Tuxedo Connection Pools option from Tuxedo User Management tree and click the right mouse button. The Change Data Source popup menu appears.

2. Select the Change Data Source popup menu. The Choose Data Source window is displayed as shown in Figure 3-8.

3. Select a datasource from the datasources listed, and click on Ok. The Connection Pools Information area is updated with pools defined for the selected datasource.

Read Only Nodes

---

The following repository nodes are read only. Do not modify the definition of these nodes.

• bsp.adapterTypes.Tuxedo

• bsp.dataSources.<dsName>.adapterType.Tuxedo

• bsp.dataSources.<dsName>.config.NLS.charoptimized

• bsp.dataSources.<dsName>.config.NLS.charset

• bsp.dataSources.<dsName>.functionObjectTemplates.TransactionFO

• bsp.dataSources.<dsName>.serviceProviderTemplates

Always use the management console to make any adjustments to the Tuxedo datasource(s). Avoid importing, manually created or updated datasource XML files, into repository using the UIF repository browser.

Deploying the Repository Content

---

In addition to deploying your application, you must explicitly deploy the repository content by exporting its contents to XML and importing the XML file on the deployment machine. This is performed using the Repository Browser tool.

Using repository browser, export the datasource content into an XML file. The XML file can be restored later either on the same machine (as part of backup and recovery) or on a different machine (as part of deploying the application) using the Import feature provided with the repository browser.

During the import process, the repository.dtd for the enterprise connector must exist in the same directory as the XML file. The repository.dtd file for the Tuxedo Enterprise Connector is located in the ias/APPS/adapters/tux/metadata subdirectory of the iPlanet Application Server installation root directory. You must use only this repository.dtd file while importing XML file(s) related to the Tuxedo Enterprise Connector.

Always backup the datasource(s) into XML file before and after any changes to Tuxedo datasources.

Refer to Using the Repository Browser in the iPlanet Unified Integration Framework Developer's Guide for additional information on exporting and importing XML data.

---

Note	VIEW information is platform specific. Therefore, if the repository content contains VIEW data, the content can only be exchanged across the same platform types. For example, NT to NT, and Solaris to Solaris.

---

Setting Parameters for International Applications

---

The following parameters are used with each datasource to store information about the charset to be used while sending configuration data like user name, client name, and password from connector to Tuxedo server.

• bsp.dataSources.<dsName>.config.NLS.charoptimized

  Initialized with value 0. This is read-only parameter.

• bsp.dataSources.<dsName>.config.NLS.charset

  The charset parameter is initialized with UTF-8. The user authentication data (user name, client name, and data in TPINIT structure) is always passed in UTF-8 format to Tuxedo server, if the iPlanet Application Server is running in international mode. Currently only ASCII characters are supported in TPINIT structure of BEA Tuxedo system. Hence this is read-only parameter.

Even tough the management console allows you to enter data in popular legacy character sets such as ASCII, SJIS or ECU_JP (Japanese), GN2312 (Chinese), KCS5601 (Korean), and so on, the datasource and entity (user mapping) names must be defined using ASCII characters only. To handle multi-byte/double byte data correctly in management console and repository browser, the iPlanet Application Server must operate in INTERNATIONAL mode.

Please contact BEA System for details on support of multi-byte/double byte characters in BEA Tuxedo software.

Jolt Migration

---

The Tuxedo Enterprise Connector provides a command line tool to import the Tuxedo services into the UIF Repository, if the Tuxedo services definition are already present in the Jolt Bulk Loader format. The command line tool accepts the Jolt bulk loader services file and converts them into XML format and imports it into the UIF Repository. Refer to the BEA Jolt documentation for detailed information on Bulk Loading Tuxedo Services.

The remainder of this section describes step-by-step procedures to use the command line tool.

1. Create a datasource for your application using the management console.

2. Import FML and VIEW data types, if any, used in the Tuxedo services using the management console.

3. Run the following command by passing the Jolt bulk loader services file:

   On Windows NT

   joltmigrator -f <jolt_bulk_load_file> -s <datasourcename>

   On Unix

   <iAS installdir>/ias/APPS/bin/joltmigrator.sh -f <jolt_bulk_load_file> -s <datasourcename>

   Where, jolt_bulk_load_file is the Tuxedo services definition file in the Jolt Bulk Load format and the datasource name is the datasource under which the services are to be imported.

The following listing shows a sample Jolt Bulk Loader services file for Tuxedo services used in section "Tuxedo Services IDL File".

service=STRINGTEST1

inbuf=STRING

outbuf=STRING

param=inParam

type=string

access=in

param=outParam

type=string

access=out

service=STRINGTEST2

outbuf=STRING

param=outParam

type=string

access=out

service=STRINGTEST3

inbuf=STRING

param=inParam

type=string

access=in

service=CARRAYTEST1

inbuf=CARRAY

outbuf=CARRAY

param=inParam

type=carray

access=in

param=outParam

type=carray

access=out

service=CARRAYTEST2

outbuf=CARRAY

param=outParam

type=carray

access=out

service=CARRAYTEST3

inbuf=CARRAY

param=inParam

type=carray

access=in

service=XOCTETTEST1

inbuf=X_OCTET

outbuf=X_OCTET

param=inParam

type=carray

access=in

param=outParam

type=carray

access=out

service=XOCTETTEST2

outbuf=X_OCTET

param=outParam

type=carray

access=out

service=XOCTETTEST3

inbuf=X_OCTET

param=inParam

type=carray

access=in

service=FML16TEST1

inbuf=FML

outbuf=FML

param=string16

type=string

access=in

param=string16

type=string

access=out

count=10

service=FML16TEST2

outbuf=FML

param=char16

type=char

access=out

count=10

service=FML16TEST3

inbuf=FML

param=string16

type=string

access=in

param=short16

type=short

access=in

param=double16

type=double

access=in

param=float16

type=float

access=in

param=long16

type=long

access=in

service=FML32TEST1

inbuf=FML32

outbuf=FML32

param=string32

type=string

access=in

param=string32

type=string

access=out

count=10

service=FML32TEST2

outbuf=FML32

param=carray32

type=carray

access=out

count=10

service=FML32TEST3

inbuf=FML32

param=string32

type=string

access=in

param=short32

type=short

access=in

param=double32

type=double

access=in

param=float32

type=float

access=in

param=long32

type=long

access=in

service=VIEW16TEST1

inbuf=VIEW

outbuf=VIEW

inview=v16test1

outview=v16test1

service=VIEW16TEST2

inbuf=VIEW

outbuf=VIEW

inview=v16test1

outview=v16test2

service=VIEW16TEST3

inbuf=VIEW

inview=v16test4

service=VIEW16TEST4

outbuf=VIEW

outview=v16test4

service=VIEW32TEST1

inbuf=VIEW32

outbuf=VIEW32

inview=v32test1

outview=v32test1

service=VIEW32TEST2

inbuf=VIEW32

outbuf=VIEW32

inview=v32test1

outview=v32test2

service=VIEW32TEST3

inbuf=VIEW32

inview=v32test4

service=VIEW32TEST4

outbuf=VIEW32

outview=v32test4

service=XCOMMONTEST1

inbuf=X_COMMON

outbuf=X_COMMON

inview=xcomtest1

outview=xcomtest2

service=XCTYPETEST1

inbuf=X_C_TYPE

outbuf=X_C_TYPE

inview=xctest1

outview=xctest2

---

Note	noaccess value for access param is not supported. Use count param value other than 1 to indicate FML field is multiple occurrence.

---