Table of Contents Previous Next PDF


Setting Up Workstation Clients

Setting Up Workstation Clients
This topic includes the following sections:
Defining Workstation Clients
Before a Workstation client can join an Oracle Tuxedo application, the application environment must be prepared to accommodate it. The Oracle Tuxedo system provides the variables described in Table 14‑1 table for setting up your environment. Two (TUXDIR and WSNADDR) are required; the rest are optional. Defaults are available for all parameters except WSENVFILE.
 
APP_PW (Optional)
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).
TMMAXENCRYPTBITS (Optional)
TMMINENCRYPTBITS (Optional)
The directory in which replies are stored when the WSRPLYMAX limit has been reached. The default is the working directory.
TMPDIR (Optional)
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 Oracle Tuxedo system software on this workstation. The client cannot connect unless this environment variable is set.
TUXDIR (Required)
URLENTITYCACHING (Optional)
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.
WSDEVICE (Optional)
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)
WSFRANGE (Optional)
WSNADDR (Required)
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 Oracle 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.
 
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 shown in Table 14‑2 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.
 
-n netaddr
[-d device]
[-t timeout]
[-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]
[-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]
[-T client_timeout]
[-p minwshport] and [-P 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]
[-K {client | handler | both | none}]
See Also
servopts(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
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.
Table 14‑3 shows the keep-alive option.
 
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.
Note:
Limitations When Using the Keep-alive Option
The keep-alive option is supported only on platforms for which the Oracle Tuxedo system uses sockets:
You cannot use this option on any other platform. The Oracle 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:
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 Oracle 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:
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 Oracle Tuxedo application. The client can rejoin the application in either of two ways:
By calling tpinit(3c)
Limitations When Using the Network Timeout Option
Setting the Network Timeout Option
To use the network timeout option in your Oracle 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 in Listing 14‑1 shows how you can add the Workstation component to the bankapp application. It contains modifications to the MACHINES and SERVERS sections.
Listing 14‑1 Sample UBBCONFIG File Supporting Workstation Clients
*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:
In the MACHINES section, the default for MAXWSCLIENTS is overridden in the entries for two sites. For SITE1, the default is raised to 150, while it is lowered to 0 for SITE2, because no Workstation clients will be connected to that site.
In the SERVERS section, a WSL process is specified for group BANKB1. The WSL has a server ID of 500 and it is marked as restartable.
The WSL will listen at network address //ws.beasys.com:5120 (-n).
 

Copyright © 1994, 2017, Oracle and/or its affiliates. All rights reserved.