PURPOSE

WSL - BEA TUXEDO System Workstation Listener Server

SYNOPSIS

WSL SRVGRP="identifier"
    SRVID="number"
    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} ] "

DESCRIPTION

The workstation listener is a System/T-supplied server that enables access to native services by workstation clients. The application administrator enables workstation access to the application by specifying the workstation listener server as an application server in the *SERVERS section. The associated command line options are used to parameterize the processing of the workstation listener and workstation handlers.

The location, server group, server id, and other generic server related parameters are associated with the workstation listener using the already defined configuration file mechanisms for servers. Workstation listener specific command line options are specified to allow for customization.

Each WSL booted as part of an application facilitates application access for a large number of workstation clients by providing access via a single well known network address to a set of workstation handlers (WSHs) acting as surrogate clients for the users running on the workstations. The WSHs are started and stopped dynamically by the WSL as necessary to meet the incoming load from the application workstations. The advantages to the application administrator are that a small number of native site processes (WSHs) can support a much larger number of clients, thus reducing the process count on the native site, and that the native site does not need to incur the overhead of maintaining bulletin board information on the workstation sites, which may be quite numerous.

The following WSL-specific command line options are available and may be listed after the double-dash (--) in the CLOPT parameter.

-n netaddr

Specifies the network address to be used by a workstation listener to accept connections from TUXEDO System Workstations.

TCP/IP addresses may be specified in the following forms:


"//host.name:port_number"
"//#.#.#.#:port_number"

In the first format, the domain finds an address for hostname using the local name resolution facilities (usually DNS). hostname must be the local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine.

In the second example, the "#.#.#.#" is in dotted decimal format. In dotted decimal format, each # should be a number from 0 to 255. This dotted decimal number represents the IP address of the local machine.

In both of the above formats, port_number is the TCP port number at which the domain process will listen for incoming requests. port_number can either be a number between 0 and 65535 or a name. If port_number is a name, then it must be found in the network services database on your local machine.

The address can also be specified in hexadecimal format when preceded by the characters "0x". Each character after the initial "0x" is a number between 0 and 9 or a letter between A and F (case insensitive). The hexadecimal format is useful for arbitrary binary network addresses such as IPX/SPX or TCP/IP.

The address can also be specified as an arbitrary string. For example, string addresses are used in STARLAN networks. This is the only required parameter.

[-d device]

The device file name used for network access by the workstation listener and its workstation handlers. For Release 6.4 and higher. this parameter is optional. For prior releases. it should be used if required by the transport provider, for example, tli.

[-w WSHname]

The name of the executable providing workstation handler services for this workstation listener. The default value for this is WSH, which corresponds to the system provided workstation handler. Workstation handlers may be customized using the command buildwsh(1). See the buildwsh(1) man page for more details.

[-t timeout-factor]

The number, when multiplied by SCANUNIT, results in the amount of time in seconds that should be allowed for a workstation client to complete initialization processing through the WSH before being timed out by the WSL. The default value for this parameter is 3 in a non-security application and 6 in a security application. The legal range is between 1 and 255.

[-T Client-timeout]

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. The option can be used for client platforms that are unstable (for example, where a user might turn off a personal computer without calling tpterm()). Note that the option also affects clients that get unsolicited message notifications and do not follow up on them. If the argument is not supplied, there is no timeout.

[-m minh]

The minimum number of handlers that should be available in conjunction with this WSL at any given time. The WSL will start this many WSHs immediately upon being booted and will not deplete the supply of WSHs below this number until the administrator issues a shutdown to the WSL. The default value for this parameter is 0. The legal range is between 0 and 255.

[-M maxh]

The maximum number of handlers that should be available in conjunction with this WSL at any given time. Handlers are started as necessary to meet the demand of workstation clients attempting to access the system. The default value for this parameter is equal to the setting for MAXWSCLIENTS on the logical machine divided by the multiplexing factor for this WSL (see -x option below) rounded up by one. The legal range for this parameter is between 1 and 4096. The value must be equal to or greater than minh.

[-x mpx-factor]

An optional parameter used to control the degree of multiplexing desired within each workstation handler. The value for this parameter indicates the number of workstation clients that can be supported simultaneously by each workstation handler. The workstation listener ensures that new handlers are started as necessary to handle new workstation clients. This value must be greater than or equal to 1 and less than or equal to 4096. The default value for this parameter is 10.

[-p minwshport]

[-P maxwshport] This pair of command line options can be used to specify the number range for port numbers available for use by WSHs associated with this listener server. The port numbers must be in the range between 0 and 65535. The default is 2048 for minwshport and 65535 for maxwshport.

[-I init-timeout]

The time, in seconds, that should be allowed for a workstation client to complete initialization processing through the WSH before being timed out by the WSL. The default value for this parameter is 60. The legal range is between 1 and 32,767.

[-c compression-threshold]

This option determines the compression threshold to be used by workstation clients and handlers. Any buffers sent between workstation clients and handlers will be compressed if they are larger than the given value. The default value for this parameter is 2,147,483,647, which means no compression is done since the legal range is between 0 and 2,147,483,647.

[-k compression-threshold]

This is a special compression option for TUXEDO releases prior to 6.2 with clients from USL France or ITI. If this situation applies to you, you may use -k. It is acceptable to have multiple WSL/WSH pairs, some of which control the compression threshold with the -c option; others, with the -k option. The -k works exactly like -c.

[-z [0|40|128]]

When establishing a network link between a Workstation client and the Workstation Handler, require at least this minimum level of encryption. 0 means no encryption, while 40 and 128 specify the length (in bits) of the encryption key. If this minimum level of encryption cannot be met, link establishment will fail. The default value is 0.

[-Z [0|40|128]]

When establishing a network link between a Workstation client and the Workstation Handler, allow encryption up to this level. 0 means no encryption, while 40 and 128 specify the length (in bits) of the encryption key. The default value is 128. The -z or -Z options are available only if either the International or Domestic BEA TUXEDO Security Add-on Package is installed.

[-H external netadder]

will be combined with a WSH network address to generate a well known network address used by the workstation client to connect to a WSH process. It has the same format as the -n option except that it substitutes the port number with M characters to indicate that the position of the combined network address will be copied from the WSH network address. For example when address template is 0x0002MMMMdddddddd and WSH network address is 0x00021111ffffffff then the well known network address will be 0x00021111dddddddd. When an address template starts with "//" it is assumed that the network address type is IP based; the TCP/IP port number of the WSH network address will be copied into the address template to form the combined network address. This feature is useful when you need to connect a workstation client to a WSH through a router that performs Network Address Translation.

[-N network-timeout]

The network-timeout option will establish a wait period, in seconds, for any TUXEDO operation by the /WS client that receives data from the network. If the period is exceeded, the operation will fail and the client will be disconnected from the application. A value of 0 (zero) indicates no time-out; this is the default. Note: setting this value too low may cause an unacceptably high number of disconnects.

[-K {client|handler|both|none}]

This option directs the /WS client, WSH process, or both, to activate the network provider's KEEPALIVE option. This option improves the speed and reliability of network failure detection, by actively testing an idle connection's state at the protocol stack level. The availability and timeout thresholds for this feature are determined by operating system tunable parameters.

A value of client will configure this option for the /WS client, a value of handler will configure this option for the WSH, and a value of both will configure both sides of the connection. The default value is none, in which case neither side has the KEEPALIVE option configured.

Note that the KEEPALIVE interval is an operating system parameter, so changing the value will affect any other applications that enable KEEPALIVE. Many platforms have a two hour default value that may be longer than desired.

This option is not available on all platforms. A userlog warning message will be generated if the KEEPALIVE option is specified but not available on the WSH's machine. If KEEPALIVE is requested but not available on a /WS client's machine, the setting will be silently ignored.

Any configuration that prevents the WSL from supporting workstation clients will cause the WSL to fail at boot time, for example, if the MAXWSCLIENTS value for the site is 0.

PORTABILITY

WSL is supported as a TUXEDO-supplied server on UNIX operating systems.

INTEROPERABILITY

WSL may be run in an interoperating application, but it must run on a Release 4.2 or later node.

NETWORK ADDRESSES

Suppose the local machine on which the wlisten is being run is using TCP/IP addressing and is named backus.company.com, with address 155.2.193.18. Further suppose that the port number at which the wlisten should accept requests is 2334. Assume that port number 2334 has been added to the network services database under the name bankapp-nlsaddr. The address specified by the -l option could be represented in the following ways:


//155.2.193.18:bankapp-nlsaddr
//155.2.193.18:2334
//backus.company.com:bankapp-nlsaddr
//backus.company.com:2334
0x0002091E9B02C112

The last of these representations is hexadecimal format. The 0002 is the first part of a TCP/IP address. The 091E is the port number 2334 translated into a hexadecimal number. After that each element of the IP address 155.2.193.12 is translated into a hexadecimal number. Thus the 155 becomes 9B, 2 becomes 02, and so on.

For a STARLAN network, a recommended address of uname.wlisten will usually yield a unique name.

EXAMPLES


*SERVERS
WSL SRVGRP="WSLGRP" SRVID=1000 RESTART=Y GRACE=0
	CLOPT="-A -- -n 0x0002ffffaaaaaaaa -d /dev/tcp"
WSL SRVGRP="WSLGRP" SRVID=1001 RESTART=Y GRACE=0
	CLOPT="-A -- -n 0x0002aaaaffffffff -d /dev/tcp -H 0x0002MMMMdddddddd"
WSL SRVGRP="WSLGRP" SRVID=1002 RESTART=Y GRACE=0
	CLOPT="-A -- -n //hostname:aaaa -d /dev/tcp -H //external_hostname:MMMM"