Setting Up a BEA Tuxedo Application

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

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.

To Specify . . .
Set This Environment Variable . . .
The application password. (Useful only for applications in which security is implemented through password usage.) Clients that run from scripts can get the application password from this variable.
APP_PW (Optional)
Specifies the security principal name identification string to be used for authentication purposes when SSL is initiated. This parameter may contain a maximum of 511 characters (excluding the terminating NULL character).
Specifies the location of the file or device where the decryption (private) key for the principal specified in SEC_PRINCIPAL_NAME resides. This parameter may contain a maximum of 1023 characters (excluding the terminating NULL character).
Specifies the variable in which the password for the principal specified in SEC_PRINCIPAL_NAME is stored. This parameter may contain a maximum of 31 characters (excluding the terminating NULL character).
The maximum number of significant bits of the encryption key for link-level encryption. Value can be 0 (if no encryption is used), or 40, 56, 128, or 256 (if the number specified is the number of significant bits in the encryption key).
The minimum number of significant bits of the encryption key for link-level encryption. Value can be 0 (if no encryption is used), or 40, 56, 128, or 256 (if the number specified is the number of significant bits in the encryption key).
The directory in which replies are stored when the WSRPLYMAX limit has been reached. The default is the working directory.
TMPDIR (Optional)
Specifies the code-set encoding name that the workstation machine includes in an allocated MBSTRING typed buffer.
TPMBENC has no default value. For a Workstation client using MBSTRING typed buffers, TPMBENC must be defined on the workstation machine.
TPMBENC (Optional)
Specifies whether the workstation machine automatically converts the data in a received MBSTRING buffer to the encoding defined in TPMBENC. By default, the automatic conversion is turned off, meaning that the data in the received MBSTRING buffer is delivered to the Workstation client as is—no encoding conversion. Setting TPMBACONV to any value, say Y (yes), turns on the automatic conversion.
TPMBACONV (Optional)
The location of the BEA Tuxedo system software on this workstation. The client cannot connect unless this environment variable is set.
TUXDIR (Required)
Specifies whether the workstation machine caches Document Type Definition (DTD), XML schema, and entity files. By default, the caching is turned on (Y). Setting URLENTITYCACHING to N (no) turns off the caching.
Specifies the directory in which the workstation machine caches DTD, schema, and entity files. The URLENTITYCACHEDIR variable specifies the absolute pathname for the cached files. If URLENTITYCACHEDIR is not specified, the default directory becomes URLEntityCachedir, which will be created in the current working directory of the Workstation client process provided that the appropriate write permissions are set.
The network device to be used. The default is an empty string.
WSDEVICE (Optional)
The name of the file in which all environment variables may be set. There is no default for this variable.
WSENVFILE (Optional)
The network address used by the Workstation client when connecting to the Workstation listener or Workstation handler. This variable, along with the WSFRANGE variable, determines the range of TCP/IP ports to which a Workstation client attempts to bind before making an outbound connection. This address must be a TCP/IP address
WSFADDR (Optional)
The range of TCP/IP ports to which a Workstation client process attempts to bind before making an outbound connection. The WSFADDR parameter specifies the base address of the range.
WSFRANGE (Optional)
A list of one or more network addresses of the WSL that the client wants to contact. This address must match the address of a WSL process in the application configuration file.
WSNADDR (Required)
The amount of core memory to be used for buffering application replies. The default is 256,000 bytes.
WSRPLYMAX (Optional)
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.
WSTYPE (optiOnal)


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.

Specifies the maximum number of WSCs that may connect to a machine.
The syntax is MAXWSCLIENTS=number. The default is 0.
If MAXWSCLIENTS is not specified, WSCs may not connect to the machine being described.


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 (--).

Note: For a complete list of the CLOPT command-line options, see servopts(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

Use This Command-line Option . . .
To Specify . . .
-n netaddr
The network address used by WSCs to contact the listener. The WSC must set the appropriate environment variable (WSNADDR) to the value specified after -n.
[-d device]
(Required for some transport interfaces)
Specify the network device name.
This is an optional parameter because only some transport interfaces require it. Sockets, for example, does not require this parameter.
[-t timeout]
The amount of time to allow for a client to connect to the WSH.
To calculate the total amount of time to allow for this purpose, the system multiplies the value of timeout by the value of the SCANUNIT parameter.
The default is 3 in a nonsecure application, and 6 in a secure application. In this context we refer to an application as secure if one of the following parameters is set:
  • ACL
  • APP_PW
[-w name]
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]
The minimum number of handlers that should be booted and always available. The default is 0.
[-M number]
The maximum number of handlers that can be booted. The default is the value of MAXWSCLIENTS for the machine being configured, divided by the multiplexing value (specified with -x).
[-x number]
The maximum number of clients that a WSH can multiplex at one time. The value must be greater than 0. The default is 10.
[-T client_timeout]
The amount of time (in minutes) that a client can remain idle without being disconnected. 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] and [-P maxwshport]
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.
[-z] and [-Z]
The range of bits that can be used, on the WSL side, for link-level encryption: use -z to specify the minimum number of bits, and -Z to specify the maximum number of bits.
[-N network_timeout]
The minimum amount of time (in seconds) that a Workstation client is allowed to wait to receive a response from the WSL/WSH. A value of 0 indicates no network timeout.
[-K {client | handler | both | none}]
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.

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.

Use This Option...
-K client
Generate keep-alive messages from the client machines. If the keep-alive message is not acknowledged, the client machine considers the network down. Subsequent ATMI calls fail with a tperrno of TPESYSTEM.
-K handler
Generate keep-alive messages from the handler machine. If the keep-alive message is not acknowledged, the handler machine considers the network down. The handler then cleans up the entry associated with the client that does not respond. This reduces the possibility that the handler will exhaust the number of clients that a workstation can multiplex at one time (as specified by -x) with stale clients.
-K both
Generate keep-alive message from both the client and handler machines. The availability and timeout thresholds for this component are determined by tunable parameters in the operating system.
-K none
Turn off the keep-alive option. Using this setting has the same effect as not specifying -K at all.

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

CLOPT="-A -- -n // -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.

Note: Any timeout period that you specify applies to the entire system. If you specify a timeout with one application in mind, and you later change the amount of time specified, all applications that use keep-alive are also affected.

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.

Note: The keep-alive operation works only for TCP/IP communications.


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.

Note: Setting this value too low may cause too many disconnects.

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.

Listing 13-1 Sample UBBCONFIG File Supporting Workstation Clients
              CLOPT="-A -- -n // -m 5 -M 30 -x 5"

Modifying the MACHINES and SERVERS Sections

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

  Back to Top       Previous  Next