Managing Workstation Clients (BEA TUXEDO System)

This chapter is specific to the BEA TUXEDO system. If you are using the WLE system and you need to configure remote clients or the Internet Inter-ORB Protocol (IIOP) Listener/Handler, see Chapter 12, "Managing Remote Client Applications (WLE Systems)" for more information.

This chapter discusses the following BEA TUXEDO topics:

• Workstation Terms

• What is a Workstation client?

• Setting Environment Variables

• Setting the Maximum Number of Workstation Clients

• Configuring a Workstation Listener (WSL)

• Modifying the MACHINES Section to Support Workstation Clients

Workstation Terms

Workstation

Workstation Extension-The workstation product that is an extension of the base BEA TUXEDO system.

DLL

Dynamic Link Libraries-A collection of functions grouped into a load module that is dynamically linked with an executable program at run time for a Microsoft Windows or an OS/2 application.

WSC

Workstation Client-A client process running on a remote site.

WSH

Workstation Handler-A client process running on an application site that acts as a surrogate on behalf of the WSC.

WSL

Workstation Listener-A server process running on an application site that listens for WSCs to connect.

The Workstation Extension of the BEA TUXEDO system allows application clients to reside on a machine that does not have a full server-side installation, that is, a machine that does not support any administration or application servers, or a Bulletin Board. All communication between the client and the application takes place over the network.

The client process can be running UNIX, MS-DOS, Windows, or OS/2. The client has access to the ATMI interface for clients. The networking behind the calls is transparent to the user. The client process registers with the system and has the same status as a native client. The client can do the following:

• Send and receive messages

• Begin, end, or commit transactions

• Send and receive unsolicited messages

• Pass application security (on a mandatory basis)

• Communicate information about remote clients through the tmadmin(1) command

  Note: A client process communicates with the native domain through the WSH rather than through a BRIDGE process.

Illustration of an Application with Two Workstation Clients

Figure 11-1 shows an example of an application with two WSCs connected. The client on the left is running on a UNIX system workstation, while the client on the right is running on an MS-DOS workstation. Both WSCs are communicating with the application through the WSH process. Initially, both joined by communicating with the WSL (indicated by the heavily dashed line).

The administrative servers and the application servers are located entirely on SITE1. Any request by a WSC to access the resource manager (RM) is sent over the network to the WSH. This process sends the request to the appropriate server and sends the reply back to the WSC.

The application is running in SHM mode. If the application was distributed over several nodes, the procedure would be very similar. The WSC would communicate with one WSH, and the request would be sent to a BRIDGE process, which would forward it to the correct node.

Note: As used in this book, the term "resource manager" refers to an entity that interacts with the BEA TUXEDO system and implements the XA standard interfaces. The most common example of a resource manager is a database. Resource managers provide transaction capabilities and permanence of actions; they are the entities accessed and controlled within a global transaction.

Figure 11-1 A Bank Application with Two Workstation Clients

How the Workstation Client Connects to an Application

A workstation client connects to an application in the following manner.

1. The client connects to the WSL process using a known network address. This is initiated when the client calls either tpchkauth() or tpinit(). The WSL returns the address of a WSH to the client.

2. The WSL process sends a message to the WSH process informing it of the connection request.

3. The WSC connects to the WSH. (All further communication between the WSC and the application takes place through the WSH.)

Eight environment variables can be used to pass information to the system. All are optional except TUXDIR and WSNADDR. Defaults are available for all except WSENVFILE:

• TUXDIR-This contains the location of the BEA TUXEDO software on this workstation. It must be set for the client to connect.

• WSNADDR- This contains the network address of the WSL that the client wants to contact. This must match the address of a WSL process, as specified in the application configuration file.

• WSDEVICE-This contains the network device to be used. The default is an empty string. WSDEVICE must be set if TLI is being used.

• WSENVFILE-This contains the name of a file in which all environment variables may be set. There is no default for this variable.

• WSTYPE-This contains the machine type. If the value of WSTYPE matches the value of TYPE in the configuration file for the WSL machine, no encoding/decoding is performed. The default is the empty string. Keep in mind, when deciding whether to use the default, that a value of "empty string" will match any other "empty string" value. Be sure to specify the value of WSTYPE whenever that value does not match the value of TYPE on the WSL machine.

• WSRPLYMAX-This contains the amount of core memory to be used for buffering application replies. The default is 32,000 bytes.

• TMPDIR-This contains the directory in which to store replies when the WSRPLYMAX limit has been reached. The default is the working directory.

• APP_PW-This contains the password in a secure application. Clients that run from scripts can get the application password from this variable.

Setting the Maximum Number of Workstation Clients

To join workstation clients to 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 accessers through a single accesser slot and, therefore, requires only one semaphore. This points out an additional benefit of the Workstation extension. By putting more clients out on workstations and off 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 MAXACCESSERS, native clients and servers fail at tpinit() time. The following table describes the MAXWSCLIENTS parameter.

Configuring a Workstation Listener (WSL)

Workstation clients access your application through the services of a WSL process and one or more WSH processes. The WSL and WSH are specified in one entry as a server supplied by the BEA TUXEDO system, although they are separate processes. The WSL can support multiple workstation clients and 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 workstation 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 list the Workstation Listener (WSL) processes in the SERVERS section of the UBBCONFIG file. Use the same syntax you use when listing a server.

Format of the CLOPT Parameter

Use the command-line option string (CLOPT) to pass information to a WSL process. 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]"

The -A value indicates that the WSL is to be booted to offer all its services. This is a default, but it is shown to emphasize the distinction between system-supplied servers and application servers. The latter can be booted to offer only a subset of their available services. The -- syntax marks the beginning of a list of parameters that are passed to the WSL after the latter has been booted.

Command-line Options of the CLOPT Parameter

You can specify the following command-line options in the CLOPT string after the -- (double minus signs):

• -n netaddr is the network address that WSCs use to contact the listener. The WSC must set the environment variable (WSNADDR) to this value. This is a required parameter.

• [-d device] is the network device name. This is an optional parameter because some transport interfaces (sockets) do not require it. However, it is required if the provider is TLI.

• [-t timeout] allows more time for a client to join when there is a large number of clients attempting to join simultaneously. The value is multiplied by the SCANUNIT parameter. The default is 3 in a nonsecure application and 6 in an application with security on it.

• [-w name] is the name of the WSH process that should be booted for this listener. The default is WSH, which is the name of the handler provided. If another handler process is built with the buildwsh(1) command, that name is specified here.

• [-m number] specifies the minimum number of handlers that should be booted and always available. The default is 0.

• [-M number] specifies the maximum number of handlers that can be booted. The default is the value of MAXWSCLIENTS for that node divided by the multiplexing value.

• [-x number] specifies the maximum number of clients that a WSH can multiplex at a time. The default is 10 and the value must be greater than 0.

• [-T client-timeout] specifies the inactive client timeout option. The inactive client timeout is the time (in minutes) allowed for a client to stay idle. If a client does not make any requests within this time period, the WSH disconnects the client. If this argument is not given or is set to 0, the timeout is infinite.

• [-p minwshport] [-P maxwshport] specifies the range for port numbers available for use by WSHs associated with this listener server. Port numbers must fall in the range between 0 and 65535. The default is 2048 for minwshport and 65535 for maxwshport.

Modifying the MACHINES Section to Support Workstation Clients

Listing 11-1 shows an example of how you can add the Workstation feature to the bankapp application.

Listing 11-1 UBBCONFIG Configuration

---

Notice the following specifications in the MACHINES and SERVERS sections:

• The MACHINES section shows the default MAXWSCLIENTS as being overridden for two sites. For SITE1, the default is raised to 150, while it is lowered to 0 for SITE2, which will not have WSCs connected to it.

• The SERVERS section shows a WSL process listed for group BANKB1. The WSL has a server ID of 500 and it is marked as restartable.

• The command-line options show the following:

  • The WSL will advertise all of its services (-A).

  • The WSL will listen at network address 0x0002ffffaaaaaaaa (-N).

  • The network provider will be /dev/tcp (-d).

  • A minimum of 5 WSHs will be booted (-m).

  • A maximum of 30 WSHs will be booted (-M).

  • Each handler will be allowed a maximum of 5 clients connected at any one time (-x).