servopts(5)


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| File Formats and Data Descriptions Reference \| Local Topics \| Previous Topic \| Next Topic \| Contents

servopts(5)

Name

servopts—Run-time options for server processes

Synopsis

AOUT CLOPT= [-A][-s{@filename|service[,service...][:func]}]
[-e stderr_file][-p [L][low_water][,[terminate_time]]
[:[high_water][,create_time]][-h][-l locktype][-n prio]
[-o stdout_file][-r][-t][ -- uargs][-v]

Description

servopts is not a command. Rather, it is a list of run-time options recognized by servers in a BEA Tuxedo system.

The server using these options may be one of the BEA Tuxedo system-supplied servers, or it may be an application-supplied server built with the buildserver(1) command.

Running servers in a BEA Tuxedo system is accomplished through the tmboot(1) and tmadmin(1) commands working with servers (and other resources) specified in the application configuration file. Desired selections from the servopts list are specified with the server in the configuration file. The following options are recognized:

-A

Indicates that the server should initially offer all services with which it was constructed. For BEA Tuxedo system-supplied servers, -A is the only way of specifying services.

-s { @filename | service[,service...][:func] }

Specifies the names of services to be advertised when the server is booted. In the most common case, a service is performed by a function that carries the same name; that is, the x service is performed by function x. For example, the specification:

-s x,y,z

will run the associated server initially offering services x, y, and z, each processed by a function of the same name. In other cases, a service (or several services) may be performed by a function of a different name. The specification:

-s x,y,z:abc

runs the associated server with initial services x, y, and z, each processed by the function abc.

Spaces are not allowed between commas. Function name is preceded by a colon. Service names (and implicit function names) must be less than or equal to 15 characters in length. An explicit function name (that is, a name specified after a colon) can be up to 128 characters in length. Names longer than these limits are truncated with a warning message. When retrieved by tmadmin(1) or TM_MIB(5), only the first 15 characters of a name are displayed.

A filename can be specified with the -s option by prefacing the filename with the `@' character. Each line of this file is treated as an argument to the -s option. You may put comments in this file. All comments start with `#' or `:'. The -s option may be specified multiple times.

The runtime association of service name with processing function within a server load module is called the dynamic service capability. The tmadmin advertise command can be used to change the list of services offered as the server continues to run.

Service names beginning with the `.' character are reserved for system servers. Application servers specifying such services will fail to boot.

-e

Specifies the name of a file to be opened as the server's standard error file. Providing this option ensures that a restarted server has the same standard error file as its predecessors. If this option is not used, a default diversion file called stderr is created in the directory specified by $APPDIR.

-p [L][low_water][,[terminate_time]][:[high_water][,create_time]]

This option can be used to support the automatic spawning and decaying of servers, both single-threaded RPC servers and conversational servers. For RPC servers, this option must be used on an MSSQ set with MAX greater than 1. For conversational servers, the MAX must be greater than 1.

The decision to spawn/decay servers is based on the number of requests per server on the queue. However, if the load [L] argument is used with RPC servers, than the load factor of each request is also considered.

Note: For UNIX platforms only—the alarm() system call does not work as expected in servers running under server pool management. Because the code that terminates idle servers uses the alarm() call, user-written code intended to establish a customized signal handler fails to do so, despite the fact that calls to Usignal() do not result in errors.

Depending on which type of server is being used, arguments to the -p option have the following meanings:

RPC Servers

The load argument works only with RPC servers. It also only works in SHM mode with load balancing turned on. The decision to spawn more servers is based on the request load, rather than the number of messages per server. If SHM/LDBAL=Y is not set, then a user log message (LIBTUX_CAT:1542) is printed and no spawning or decaying occurs.

low_water, terminate_time, high_water, and create_time

These arguments are used to control when RPC servers are spawned or deactivated based on the number of messages per server. If the load exceeds high_water for at least create_time seconds, a new server is spawned. If the load drops below low_water for at least terminate_time seconds, a server is deactivated. low_water defaults to an average of 1 message per server on the MSSQ or a workload of 50. high_water defaults to an average of 2 messages per server, or a workload of 100. create_time defaults to 50 and terminate_time defaults to 60.

Conversational Servers

The load option is not applicable to conversational servers.

Note: For BEA Tuxedo 8.0 or later, there are no restrictions for the automatic spawning of multi-threaded or non-MSSQ conversational servers. However, the automatic decay feature will not be implemented for these types of servers.

low_water, terminate_time, high_water, and create_time

These arguments are used to control when conversational servers are spawned or deactivated. Since conversational servers typically run for a longer time than RPC servers, a conversational server checks the mininum low_water percentage and the maximum high_water percentage of other servers that are currently engaged in conversations. If the percentage exceeds the value set for the related time parameters, terminate_time and create_time respectively, then a server may be decayed or spawned, provided that the minimum or maximum number of servers has not been reached.

Also, you can specify a value of 0 seconds for the time parameters so that either a spawn or decay action will occur as soon as the server detects that the percentage has been exceeded. low_water percentage defaults to 0% and the high_water percentage defaults to 80%. terminate_time defaults to 60 seconds and create_time defaults to 0 seconds.

-h

Do not run the server immune to hangups. If not supplied, the server ignores the hangup signal.

-l locktype

Lock the server in core. The argument for locktype is t, d, or p according to whether the text (TXTLOCK), data (DATLOCK), or the entire process (text and data—PROCLOCK), should be locked. See plock(2) for details. The lock fails if the server is not run as root. There is no way to unlock a server once it is locked.

-n prio

nice the server according to the prio argument. Giving the process better priority (a negative argument) requires it to be run with the UID of root. See nice(2) for details.

-o stdout_file

Specifies the name of a file to be opened as the server's standard output file. Providing this option ensures that a restarted server has the same standard output file as its predecessors. If this option is not used, a default diversion file called stdout is created in the directory specified by $APPDIR.

-r

Specifies that the server should record, on its standard error file, a log of services performed. This log may be analyzed by the txrpt(1) command. When the -r option is used, make sure that the ULOGDEBUG variable is not set to "y". The ULOGDEBUG variable prevents debugging messages from being sent to stderr. Debugging messages in the file will be misinterpreted by txrpt.

-t

Specifies that the server in this BEA Tuxedo 7.1 or later application is allowed to interoperate with pre-release 7.1 BEA Tuxedo software. The server may be a workstation listener (WSL) process (which when started with the -t option allows interoperability for all of its workstation handler—WSH—processes), a domain gateway (GWTDOMAIN) process, or a system or application server process.

Marks the end of system-recognized arguments and the start of arguments to be passed to a subroutine within the server. This option is needed only if the user wishes to supply application-specific arguments to the server. The system-recognized options precede the --; application arguments should follow it. Application arguments may be processed by a user-supplied version of the tpsvrinit() function. getopt() should be used to parse them. Because all system arguments are processed prior to the call to tpsvrinit(), when the call is made the external integer, optind points to the start of the user flags. The same option letters (for example, -A) may be reused after the -- argument, and given any meaning appropriate to the application.

-v

Prints out the service name/function name list to standard output, beginning with the following comment lines:

#
# List of services and corresponding handler functions built into the server
#
<servicename>:<functionname><NEWLINE>
<servicename>:<functionname><NEWLINE>
<servicename>:<functionname><NEWLINE>
. . . .
. . . .
where the first three lines are comments and begin with a pound sign (#) character. Each following line includes a service name and its corresponding function name built into the executable. The servicename field on any line can be an empty string if an "-s: functionname" is included on the buildserver command line. The functionname field is always present.

Note: At run time the BEA Tuxedo system automatically adds the following option to each command line for each server:

-c dom=domainid

The -c option adds a comment line, in which the specified domain ID is reported, to any command output that reports on the processes associated with the domain in question, such as the output of the ps command. This comment helps an administrator who is managing multiple domains to interpret a single output stream that refers to several domains.

Examples

See the Examples section of UBBCONFIG(5).