Setting Up a BEA Tuxedo Application

Setting Up Workstation Clients

This topic includes the following sections:

Defining Workstation Clients

Before a Workstation client can join a BEA Tuxedo application, the application environment must be prepared to accommodate it. The BEA Tuxedo system provides the variables described in the following table for setting up your environment. Two (TUXDIR and WSNADDR) are required; the rest are optional. Defaults are available for all parameters except WSENVFILE.

Specifying the Maximum Number of Workstation Clients

To enable Workstation clients to join an application, you must specify the MAXWSCLIENTS parameter in the MACHINES section of the UBBCONFIG file.

MAXWSCLIENTS is the only parameter that has special significance for the Workstation feature. MAXWSCLIENTS tells the BEA Tuxedo system at boot time how many accesser slots to reserve exclusively for Workstation clients. For native clients, each accesser slot requires one semaphore. However, the Workstation handler process (executing on the native platform on behalf of Workstation clients) multiplexes Workstation client accesses through a single accesser slot and, therefore, requires only one semaphore. This capability is an additional benefit of the Workstation component. By putting more clients on workstations instead of on the native platform, an application reduces its IPC resource requirements.

MAXWSCLIENTS takes its specified number of accesser slots from the total set in MAXACCESSERS. This is important to remember when specifying MAXWSCLIENTS; enough slots must be left to accommodate native clients as well as servers. If you specify a value for MAXWSCLIENTS greater than that of MAXACCESSERS, native clients and servers fail at tpinit() time. The following table describes the MAXWSCLIENTS parameter.

Defining a Workstation Listener (WSL) as a Server

Workstation clients access your application through a WSL process and one or more WSH processes. The WSL can support multiple Workstation clients. It acts as the single point of contact for all the Workstation clients connected to your application at the network address specified on the WSL command line. The listener schedules work for one or more Workstation handler processes.

A WSH process acts as a surrogate within the administrative domain of your application for clients on remote workstations. The WSH uses a multiplexing scheme to support multiple Workstation clients concurrently.

To join Workstation clients to an application, you must specify the Workstation listener (WSL) processes in the SERVERS section of the UBBCONFIG file. Use the same syntax you use to specify a server.

Passing Information to a WSL Process

To pass information to a WSL process, you can use the command-line option string, CLOPT. The format of the CLOPT parameter is as follows:

CLOPT="[ -A ] [servopts_options] -- -n netaddr [-d device]
       [-w WSHname][-t timeout_factor][-T Client_timeout]
	[-m minh][-M maxh][-x mpx_factor ]
       [-p minwshport][-P maxwshport]
       [-I init_timeout][-c compression_threshold]
       [-k compression_threshold]
       [-z bits][-Z bits][-H external_netaddr]
       [-N network_timeout][-K{client|handler|both|none}]"

The -A option requests that the WSL offer all its services when it is booted. This option is included by default, but it is shown here to emphasize the distinction between system-supplied servers and application servers. When application servers are booted, they sometimes offer only a subset of their available services.

The double-dash (--) marks the beginning of a list of parameters that is passed to the WSL after it has been booted.

Using Command-line Options Set with CLOPT

You can specify any of the following command-line options in the CLOPT string after the double-dash string (--).

See Also

Detecting Network Failures

The Workstation component provides two administrative options to WSL that enable you to avoid hanging indefinitely when a network connection is lost. Specifically, these options allow you to:

Using the Keep-alive Option

Keep-alive is a networking operation that periodically checks the viability of a network connection between the Workstation handler and a Workstation client if no traffic has occurred over that connection within a specified period of time.

You can request the keep-alive option by adding the -K option to the WSL CLOPT entry in the SERVERS section of the UBBCONFIG file. The -K option accepts the following arguments: client, handler, both, or none.

Your entry in the UBBCONFIG file should look like the following:

WSL SRVGRP="WSLGRP" SRVID=1000 RESTART=Y GRACE=0
CLOPT="-A -- -n //ws.beasys.com:5120 -d /dev/tcp -K both"

In the example, -K turns on keep-alive checking on both the Workstation client and the server.

For details about the format of a WSL entry in UBBCONFIG, see WSL(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

Limitations When Using the Keep-alive Option

The keep-alive option is supported only on platforms for which the BEA Tuxedo system uses sockets:

You cannot use this option on any other platform. The BEA Tuxedo system lets you specify the -K option for any server machine, but it will not execute it properly on any platform other than those previously listed. If you try to perform a keep-alive operation on any other platform, your attempt fails and a message is written to the userlog (once per process for the WSH). Processing continues normally.

Using the Network Timeout Option

Network timeout is an option that lets you decide how long you are willing to wait for an operation in a Workstation client before your request for that operation is canceled (timed out) on a network.

You can request the network timeout function through an administrative option to the WSL: -N. The -N option uses a network timeout to receive data in the Workstation client.

How Network Timeout Works

The network timeout option establishes a waiting period (in seconds) for any BEA Tuxedo operation in the Workstation client that receives data from the network. If the period is exceeded, the operation fails and the client is disconnected from the application. A value of 0 (the default) indicates no timeout.

Each ATMI function returns an error whenever a timeout occurs. When a link times out, the application is notified. An existing error code is used. (Additional error detail on the specific error can be retrieved by a call to tperrordetail(3c).) Once a network timeout occurs, the status of outstanding operations is in doubt: transactions cannot be completed; incoming replies can be lost, and so on. The only safe action is to terminate the connection to the application by doing the equivalent of a tpterm(3c) without communicating with the WSH.

By the time the operation returns, the client is no longer part of the BEA Tuxedo application. The client can rejoin the application in either of two ways:

Limitations When Using the Network Timeout Option

Setting the Network Timeout Option

To use the network timeout option in your BEA Tuxedo application, add the -N option to the WSL CLOPT argument.

Sample Configuration File that Supports Workstation Clients

The following excerpt from a sample configuration file shows how you can add the Workstation component to the bankapp application. It contains modifications to the MACHINES and SERVERS sections.

*MACHINES
SITE1
              ...
              MAXWSCLIENTS=150

              ...
SITE2

              ...
              MAXWSCLIENTS=0
              ...

*SERVERS
              ...
WSL SRVGRP="BANKB1" SRVID=500 RESTART=Y
              CLOPT="-A -- -n //ws.beasys.com:5120 -m 5 -M 30 -x 5"

                 ...

Modifying the MACHINES and SERVERS Sections

The following changes are shown in the MACHINES and SERVERS sections: