Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
WebLogic Enterprise Doc Home   |   Tuxedo ATMI Topics   |   Previous Topic   |   Next Topic   |   Contents   |   Index

ubbconfig-BEA Tuxedo or BEA WebLogic Enterprise System ASCII configuration file

A binary configuration file, called the TUXCONFIG file, contains information used by tmboot(1) to start the servers and initialize the Bulletin Board of a BEA Tuxedo system or BEA WebLogic Enterprise system Bulletin Board instantiation in an orderly sequence. The binary TUXCONFIG file cannot be created directly (although an existing TUXCONFIG file can be dynamically modified through tmconfig(1)). Initially, a UBBCONFIG file of the format described on this reference page must be created. That file is parsed and loaded into the TUXCONFIG file using tmloadcf(1). tmadmin(1) uses the configuration file (or a copy of it) in its monitoring activity. tmshutdown(1) references the configuration file for information needed to shut the application down.

A server is a process that accepts requests and sends replies for clients and other servers. A client originates requests and gets replies.

A resource manager is an interface and associated software providing access to a collection of information and/or processes. An example of a resource manager is a database management system; a resource manager instance is a particular instantiation of a database controlled by a DBMS. A distributed transaction is a transaction that spans multiple resource manager instances, is started with tpbegin, and ended with tpcommit or tpabort.

A server group is a resource manager instance and the collection of servers and/or services providing access to that resource manager instance on a particular machine. The XA interface associated with the group is used for transaction management. If a server does not access a resource manager instance or does not access it as part of a distributed transaction, it must be in a server group with a null XA interface. Similarly, clients run in a special client group that does not have to be specified in the GROUPS section. The client group is not associated with a resource manager.

A remote domain is defined to be an environment for which this configuration's BEA Tuxedo system Bulletin Board is not available. Remote domains are not specified in the UBBCONFIG file, but rather through host-specific environment variables that are specified in host-specific reference pages.

The format of a UBBCONFIG file is as follows:

The file is made up of up to 11 specification sections. Lines beginning with an asterisk (*) indicate the beginning of a specification section. Each such line contains the name of the section immediately following the *. Allowable section names are: RESOURCES, MACHINES, GROUPS, NETGROUPS, NETWORK, SERVERS, MODULES, JDBCCONNPOOLS, SERVICES, INTERFACES, and ROUTING. The RESOURCES and MACHINES sections must be the first two sections in that order; the GROUPS section must be ahead of SERVERS, SERVICES, and ROUTING. The NETGROUPS section must be ahead of the NETWORK section. The SERVERS and MODULES sections must come before the JDBCCONNPOOLS section.

Parameters (except in the RESOURCES section) are generally specified by: KEYWORD = value. This sets KEYWORD to value. Valid keywords are described within each section. KEYWORDs are reserved; they cannot be used as values.

Lines beginning with the reserved word, DEFAULT:, contain parameter specifications that apply to any lines that follow them in the section in which they appear. Default specifications can be used in all sections other than the RESOURCES section. They can appear more than once in the same section. The format for these lines is:

DEFAULT:  [optional KEYWORD=value pairs]  

The values set on this line remain in effect until reset by another DEFAULT: line, or until the end of the section is reached. These values can also be overridden on non-DEFAULT: lines by placing the optional parameter setting on the line. If on a non-DEFAULT: line, the parameter setting is valid for that line only; lines that follow revert to the default setting. If DEFAULT: appears on a line by itself, all previously set defaults are cleared and their values revert to the system defaults.

If a value is numeric, standard C notation is used to denote the base (that is, 0x prefix for base 16 (hexadecimal), 0 prefix for base 8 (octal), and no prefix for base 10 (decimal)). The range of acceptable values for a numeric parameter is given under the description of that parameter.

If a value is an identifier, standard C rules are used. An identifier must start with an alphabetic character or underscore and contain only alphanumeric characters or underscores. The maximum allowable length of an identifier is 30 (not including the terminating null). An identifier cannot be the same as a KEYWORD.

A value that is neither an integer number or an identifier must be enclosed in double quotes. This value is called a string. The maximum allowable length of a string is 78 (not including the terminating null). Exceptions to this are the CLOPT, BUFTYPE, OPENINFO, and CLOSEINFO parameters, which can be 256 characters in length, and the RANGES parameter, which can be 2048 characters in length (except in Domain, where it can be no more than 1024 characters). In the RANGES parameter of the ROUTING section, certain special characters can be escaped inside a string using a backslash.

"\\" translates to a single backslash
"\"" translates to a double quote
"\n" translates to a newline
"\t" translates to a tab
"\f" translates to a formfeed
"\O+" translates to a character whose octal value is O+

where O+ is one, two, or three octal characters. "\0" translates to an embedded null character. "\xH+" or "\XH+" translates to a character whose hexadecimal value is H+ where H+ is one or more hexadecimal characters. "\y" (where "y" is any character other than one of the previously mentioned characters) translates to "y"; this produces a warning.

Some values are required to be an identifier. Other values that can be either an identifier or a string are indicated as a string_value. The maximum allowable length of a string_value is 78 characters if it is a string (not including the terminating null) and 30 characters if it is an identifier.

"#" (pound sign) introduces a comment. A newline ends a comment.

An identifier or a numeric constant must always be followed by white space (space, tab, or newline) or a punctuation character (pound sign, equals sign, asterisk, colon, comma, backslash, or period).

Blank lines and comments are ignored.

Comments can be freely attached to the end of any line.

Lines are continued by placing at least one tab after the newline. Comments cannot be continued.

This section provides for user specification of the system-wide resources, such as the number of servers, and services which can exist within a service area. Lines in the RESOURCES section are of the form: KEYWORD value where KEYWORD is the name of the parameter, and value its associated value. Valid KEYWORDs are as follows:

IPCKEY numeric_value

Specifies the numeric key for the well-known address in a BEA Tuxedo system Bulletin Board. In a single processor environment, this key "names" the Bulletin Board. In a multiple processor environment, this key names the message queue of the DBBL. In addition, this key is used as a basis for deriving the names of resources other than the well-known address, such as the names for Bulletin Boards throughout a multiprocessor. IPCKEY must be greater than 32,768 and less than 262,143. This parameter is required.

MASTER string_value1[,string_value2]

Specifies the machine on which the master copy of the TUXCONFIG is found. Also, if the application is being run in MP mode, MASTER names the machine on which the DBBL should be run. string_value2 names an alternate LMID location used during process relocation and booting. If the primary location is not available, the DBBL is booted at the alternate location and the alternate TUXCONFIG file found there is used. Both LMID values must name machines found in the MACHINES section and must be less than or equal to 30 characters in length. This parameter is required (even in SHM mode).

In an application that supports multiple release levels of the BEA Tuxedo system on different machines, MASTER and BACKUP must always have a release with a number greater than or equal to all other machines in the application. This rule is not enforced during a "Hot Upgrade."

DOMAINID string_value1

Specifies the domain identification string. If not specified, the value "" is used. If the value of DOMAINID is a character string, it may contain a maximum of 30 characters (including the trailing null). If the value of DOMAINID is a string of hexadecimal digits, it may contain a maximum of 30 octets. If DOMAINID is specified, its value is included, as a parameter (-C dom=domainid), in any command output that reports on the processes associated with a particular domain, such as the output of the ps command. This comment is useful for an administrator managing multiple domains, who may have some difficulty, without this comment, in interpreting a single output stream that refers to several domains.

UID numeric_value

Specifies the numeric user ID to be associated with the IPC structures created for the Bulletin Board. This value should be a UNIX system user ID on the local system. If not specified, the value is taken to be the effective user ID of the user executing tmloadcf(1). The RESOURCES value for this parameter can be overridden in the MACHINES section on a per-processor basis.

GID numeric_value

Specifies the numeric group ID to be associated with the IPC structures created for the Bulletin Board. This value should be a valid UNIX system group ID on the local system. If GID is not specified, the effective group ID of the user executing tmloadcf(1) is used. The RESOURCES value for this parameter can be overridden in the MACHINES section on a per-processor basis.

PERM numeric_value

Specifies the numeric permissions associated with the IPC structures that implement the Bulletin Board. It is used to specify the read/write permissions for processes in the usual UNIX system fashion (that is, with an octal number such a 0600). If not specified, the permissions on the IPC structures default to 0666 (read/write access by same user, same group, and any other). The value can be between 0001 and 0777, inclusive. The RESOURCES value for this parameter can be overridden in the MACHINES section on a per-processor basis.

MAXACCESSERS numeric_value

Specifies the default maximum number of processes that can have access to a Bulletin Board on a particular processor at any one time. System administration processes, such as the BBL and tmadmin, need not be accounted for in this figure. This value must be greater than 0 and less than 32,768. If not specified, the default is 50. The RESOURCES value for this parameter can be overridden in the MACHINES section on a per-processor basis.

MAXINTERFACES numeric_value

On a BEA WebLogic Enterprise system, the maximum number of CORBA interfaces to be accommodated in the interface table of the Bulletin Board. Valid values are from 0 to 32,766. If not specified, and if the system is licensed for the domain, the default is 100. If the system is not licensed, any nonzero value is replaced with a value of zero.

MAXSERVERS numeric_value

Specifies the maximum number of servers to be accommodated in the server table of the Bulletin Board. This value must be greater than 0 and less than 8192. If not specified, the default is 50.

MAXSERVICES numeric_value

Specifies the maximum total number of services to be accommodated in the services table of the Bulletin Board. This value must be greater than 0 and less than 32,768. If not specified, the default is 100.

MAXGROUPS numeric_value

Specifies the maximum number of configured server groups to be accommodated in the group table of the Bulletin Board. This value must greater than or equal to 100 and less than 32,768. If not specified, the default is 100.

MAXNETGROUPS numeric_value

Specifies the maximum number of configured network groups to be accommodated in the NETWORK section of the TUXCONFIG file. This value must be greater than or equal to 1 and less than 8192. If not specified, the default is 8.

MAXMACHINES numeric_value

Specifies the maximum number of configured machines to be accommodated in the machine tables of the Bulletin Board. This value must greater than or equal to 256 and less than 8,191. If not specified, the default is 256.

MAXQUEUES numeric_value

Specifies the maximum number of server request queues to be accommodated in the queue table of the Bulletin Board. This value must greater than or equal to 1 and less than 8,192. If not specified, the value is set to the configured value for MAXSERVERS. Interoperability with releases prior to Release 5.0 requires that this value be equal to the configured value for MAXSERVERS.

MAXACLGROUPS numeric_value

Specifies the maximum number of group identifiers that can be used for ACL permissions checking. The maximum group identifier that can be defined is TA_MAXACLGROUPS - 1. This value must be greater than or equal to 1 and less than or equal to 16K. If not specified, the default is 16K.

MODEL { SHM | MP }

Specifies the configuration type. This parameter is required and only one of the two settings can be specified. SHM specifies a single machine configuration; only one machine may be specified in the MACHINES section. MP specifies a multi-machine configuration; MP must be specified if a networked application is being defined. Note: to change value without relinking, servers must be built to support the models needed (see buildserver(1)).

LDBAL { Y | N }

Specifies whether or not load balancing should be performed. If LDBAL is not specified, the default is Y. It is recommended that if each service maps to one and only one queue, then LDBAL should be set to N, since load balancing is automatic.

If you set LDBAL to Y, server load balancing is performed automatically. Each interface request is routed to the server with the smallest total load. The routing of a request to a server causes the server's total to be increased by the LOAD factor of the CORBA interface requested.

When load balancing is not activated and multiple servers offer the same CORBA interface, the first available queue receives the request.

CMTRET { COMPLETE | LOGGED }

Specifies the initial setting of the TP_COMMIT_CONTROL characteristic for all client and server processes in a System/T application. If value is LOGGED, then the TP_COMMIT_CONTROL characteristic is initialized to TP_CMT_LOGGED; otherwise, it is initialized to TP_CMT_COMPLETE. If CMTRET is not specified, the default is COMPLETE. See the description of the BEA Tuxedo system ATMI function, tpscmt, for details on the setting of this characteristic.

OPTIONS identifier[,identifier . . . ]

Specifies options that are used. If more than one option is given, they are separated by commas. The following are the options that can be specified. The identifier LAN indicates that this is a networked application. The identifier MIGRATE indicates that server group migration can be done. If MIGRATE is specified, LAN should also be specified, (except for the case where the configuration runs on a single multiprocessor computer). This parameter is optional and the default is no options.

SYSTEM_ACCESS identifier[,identifier]

Specifies the default mode used by BEA Tuxedo system libraries within application processes to gain access to BEA Tuxedo system's internal tables. Valid access types are FASTPATH or PROTECTED. FASTPATH specifies that the internal tables should be accessible by the libraries via shared memory for fast access. PROTECTED specifies that while the internal tables are accessible by BEA Tuxedo system libraries via shared memory, the shared memory for these tables is not accessible outside of the BEA Tuxedo system libraries. NO_OVERRIDE can be specified (either alone or in conjunction with FASTPATH or PROTECTED) to indicate that the mode selected cannot be overridden by an application process. If SYSTEM_ACCESS is not specified, the default mode is FASTPATH.

SECURITY string_value1

Specifies the type of application security to be enforced. The possible string values are NONE, APP_PW, USER_AUTH, ACL, or MANDATORY_ACL. This parameter defaults to NONE. The value APP_PW indicates that application password security is to be enforced (clients must provide the application password during initialization). Setting APP_PW causes tmloadcf to prompt for an application password. The value USER_AUTH is similar to APP_PW but, in addition, indicates that per-user authentication will be done during client initialization. The value ACL is similar to USER_AUTH but, in addition, indicates that access control checks will be done on service names, queue names, and event names. If an associated ACL is not found for a name, it is assumed that permission is granted. The value MANDATORY_ACL is similar to ACL but permission is denied if an associated ACL is not found for the name.

AUTHSVC string_value

Specifies the name of an application authentication service that is invoked by the system for each client joining the system. This parameter requires that the SECURITY identifier be set to USER_AUTH, ACL, or MANDATORY_ACL. (For upward compatibility, setting both SECURITY APP_PW and AUTHSVC implies SECURITY USER_AUTH.) The parameter value must be 15 characters or less in length. For SECURITY level USER_AUTH, the default service name, if not specified, is AUTHSVC. For SECURITY level ACL or MANDATORY_ACL, the service name must be ..AUTHSVC. (This will be silently enforced if the administrator tries to set it to anything else.)

MAXGTT numeric_value

Specifies the maximum number of simultaneous global transactions in which a particular machine can be involved. It must be greater than or equal to 0 and less than 32,768. If not specified, the default is 100. The RESOURCES value for this parameter can be overridden in the MACHINES section on a per-processor basis.

MAXCONV numeric_value

Specifies the maximum number of simultaneous conversations in which processes on a particular machine can be involved. It must be greater than 0 and less than 32,768. If not specified, the default is 10 if any conversational servers are defined in the SERVERS section and 1 otherwise. The RESOURCES value for this parameter can be overridden in the MACHINES section on a per-processor basis. The maximum number of simultaneous conversations per server is 64.

MAXBUFTYPE numeric_value

Specifies the maximum number of buffer types that can be accommodated in the buffer type table in the Bulletin Board. It must be greater than 0 and less than 32,768. If not specified, the default is 16.

MAXBUFSTYPE numeric_value

Specifies the maximum number of buffer subtypes that can be accommodated in the buffer subtype table in the Bulletin Board. It must be greater than 0 and less than 32,768. If not specified, the default is 32.

MAXDRT numeric_value

Specifies the maximum number of configured data dependent routing criteria entries. It must be greater than or equal to 0 and less than 32,768. If not specified, the default is determined from the configured ROUTING section entries.

MAXRFT numeric_value

Specifies the maximum number of data dependent routing range field table entries. It must be greater than or equal to 0 and less than 32,768. If not specified, the default is determined from the configured ROUTING section entries.

MAXRTDATA numeric_value

Specifies the maximum string pool size for data dependent routing range strings. It must be greater than or equal to 0 and less than 32,761. If not specified, the default is determined from the configured ROUTING section entries.

SCANUNIT numeric_value

Is the interval of time (in seconds) between which periodic scans are done by the BBL to find old transactions and timed-out blocking calls within service requests. This value is used as the basic unit of scanning by the BBL. It affects the granularity with which transaction timeout values can be specified on tpbegin(3c) and the blocking timeout value specified with the BLOCKTIME parameter. The SANITYSCAN, BBLQUERY, DBBLWAIT, and BLOCKTIME parameters are multipliers of this unit for other timed operations within the system. SCANUNIT must be a multiple of 5 greater than 0 and less than or equal to 60 seconds. The default is 10 seconds.

SANITYSCAN numeric_value

Sets a multiplier of the basic SCANUNIT between sanity checks of the system. The value SCANUNIT must be greater than 0. If this parameter is not specified, the default is set so that (SCANUNIT * SANITYSCAN) is approximately 120 seconds. Sanity checks include checking servers as well as the Bulletin Board data structure itself. Each BBL checks that all servers on its machine are viable; that is, the server hasn't terminated abnormally and is not looping. Processes deemed not viable are either cleaned up, or restarted depending on the options with which they were started. Following that, the BBL sends a message (without reply) to the DBBL to indicate it is okay.

DBBLWAIT numeric_value

Sets a multiplier of the basic SCANUNIT for the maximum amount of wall time a DBBL should wait for replies from all its BBLs before timing out. Every time the DBBL forwards a request to its BBLs, it waits for all of them to reply with a positive acknowledgment before replying to the requester. This option can be used for noticing dead or insane BBLs in a timely manner. The value of DBBLWAIT must be greater than 0. If this parameter is not specified, the default is set so that (SCANUNIT * DBBLWAIT) is the greater of SCANUNIT or 20 seconds.

BBLQUERY numeric_value

Sets a multiplier of the basic SCANUNIT between status checks by the DBBL of all BBLs. The DBBL checks to ensure that all BBLs have reported in within the BBLQUERY cycle. If a BBL has not been heard from, the DBBL sends a message to that BBL asking for status. If no reply is received, the BBL is partitioned. The value of BBLQUERY must be greater than 0. If this parameter is not specified, the default is set so that (SCANUNIT * BBLQUERY) is approximately 300 seconds.

BLOCKTIME numeric_value

Sets a multiplier of the basic SCANUNIT after which a blocking call (for example, receiving a reply) times out. The value of BLOCKTIME must be greater than 0. If this parameter is not specified, the default is set so that (SCANUNIT * BLOCKTIME) is approximately 60 seconds.

NOTIFY { DIPIN | SIGNAL | THREAD | IGNORE }

Specifies the default notification detection method to be used by the system for unsolicited messages sent to client processes. This default can be overridden on a per-client basis using the appropriate tpinit(3c) flag value. Note that once unsolicited messages are detected, they are made available to the application through the application-defined unsolicited message handling routine identified via the tpsetunsol function (tpnotify(3c)).

The value DIPIN specifies that dip-in-based notification detection should be used. This means that the system will only detect notification messages on behalf of a client process while within ATMI calls. The point of detection within any particular ATMI call is not defined by the system and dip-in detection will not interrupt blocking system calls. DIPIN is the default notification detection method.

The value SIGNAL specifies that signal-based notification detection should be used. This means that the system sends a signal to the target client process after the notification message has been made available. The system installs a signal catching routine on behalf of clients selecting this method of notification. All signaling of client processes is done by administrative system processes and not by application processes. Therefore, only clients running with the same UNIX system user identifier can be notified using the SIGNAL method.

The value THREAD specifies that THREAD notification detection should be used. This means that the system dedicates a separate thread for the receipt of unsolicited messages and dispatches the unsolicited message handler in that thread. Only one unsolicited message handler executes at one time per application. This value is allowed only on platforms that offer support for multi-threading. COBOL clients cannot use THREAD notification. Clients that are written in COBOL or that run on a platform on which threads are not supported will have their notification method changed to DIPIN if they accept the UBBCONFIG default notification method and the UBBCONFIG default notification method is THREAD. In contrast, if such a client specifies thread notification explicitly in the parameters to tpinit() or TPINITIALIZE, then the call to this function will return an error.

The value IGNORE specifies that by default notification messages are to be ignored by application clients. This would be appropriate in applications where only clients that request notification at tpinit time should receive unsolicited messages.

USIGNAL { SIGUSR1 | SIGUSR2 }

Specifies the signal to be used if SIGNAL-based notification is used. The legal values for this parameter are SIGUSR1 and SIGUSR2. SIGUSR2 is the default for this parameter. USIGNAL may be specified even if SIGNAL-based notification is not selected with the NOTIFY parameter, because callers of tpinit may choose signal-based notification.

The MACHINES section specifies the logical names for physical machines for the configuration. It also specifies parameters specific to a given machine. The MACHINES section must contain an entry for each physical processor used by the application. Entries have the form:

ADDRESS  required parameters [optional parameters]  

where ADDRESS is the physical name of a processor, for example, the value produced by the UNIX system uname -n command. The length of the entire ADDRESS must be 30 characters or less. If the name is not an identifier, it must be enclosed in double quotes. If the LAN option is not specified, only one machine name can appear in this section. One of the required KEYWORDs is LMID, which is the logical machine string_value assigned to the physical machine. An LMID string_value must be unique within the MACHINES section of the configuration file.

LMID = string_value

Specifies that string_value is to be used in other sections as the symbolic name for ADDRESS. This name cannot contain a comma, and must be 30 characters or less. This parameter is required. There must be an LMID line for every machine used in a configuration.

The following parameters are required:

TUXCONFIG = string_value

This is the absolute pathname of the file or device where the binary TUXCONFIG file is found on this machine. The maximum string value length is 64 characters. The administrator need only maintain one TUXCONFIG file, namely the one that is pointed to by the TUXCONFIG environment variable on the MASTER machine. Copies on other machines of this master TUXCONFIG file are synchronized with the MASTER machine automatically when the system is booted. This parameter must be specified for each machine. If TUXOFFSET is specified, then the BEA Tuxedo file system starts at that number of blocks from the beginning of the TUXCONFIG device (see TUXOFFSET below). See ENVFILE in the MACHINES section for a discussion of how this value is used in the environment.

TUXDIR = string_value

This is the absolute pathname of the directory where the BEA Tuxedo system or BEA WebLogic Enterprise system software is found on this machine. This parameter must be specified for each machine and the pathname should be local to each machine; in other words, TUXDIR should not be on a remote file system. If the machines of a multiprocessor application have different BEA Tuxedo system releases installed, check the discussion of "Interoperability" in the BEA Tuxedo Release Notes for the higher level release to make sure you will get the functionality you expect. See ENVFILE in the MACHINES section for a discussion of how this value is used in the environment.

APPDIR = string_value

The value specified for this parameter is the absolute pathname of the application directory and is the current directory for all application and administrative servers booted on this machine. The absolute pathname can optionally be followed by a colon-separated list of other pathnames. In a configuration where SECURITY is set, each application must have its own distinct APPDIR. See ENVFILE in the MACHINES section for a discussion of how this value is used in the environment.

The following parameters are optional:

UID = number

Specifies the numeric user id to be associated with the IPC structures created for the Bulletin Board. The valid range is 0-2147483647. If not specified, the default is the value specified in the RESOURCES section.

GID = number

Specifies the numeric group id to be associated with the IPC structures created for the Bulletin Board. The valid range is 0-2147483647. If not specified, the default is the value specified in the RESOURCES section.

PERM = number

Specifies the numeric permissions associated with the IPC structures that implement the Bulletin Board. It is used to specify the read/write permissions for processes in the usual UNIX system fashion (that is, with an octal number such as 0600). The value can be between 0001 and 0777, inclusive. If not specified, the default is the value specified in the RESOURCES section.

MAXACCESSERS = number

Specifies the maximum number of processes that can have access to the Bulletin Board on this processor at any one time. System administration processes, such as the BBL and tmadmin, need not be accounted for in this figure, but all application servers and clients and TMS servers are counted. This value must be greater than 0 and less than 32,768. If not specified, the default is the value specified in the RESOURCES section.

MAXWSCLIENTS = number

Specifies the number of accesser entries on this processor to be reserved for Workstation clients only. The parameter is only used when the BEA Tuxedo system Workstation feature is used. The number specified here takes a portion of the total accesser slots specified with MAXACCESSERS. The appropriate setting of this parameter helps to conserve IPC resources since Workstation client access to the system is multiplexed through a BEA Tuxedo system-supplied surrogate, the Workstation handler. This value must be greater than or equal to 0 and less than 32,768. The default is 0. It is an error to set this number greater than MAXACCESSERS.

MAXACLCACHE = number

Specifies the number of entries in the cache used for ACL entries when SECURITY is set to ACL or MANDATORY_ACL. The appropriate setting of this parameter helps to conserve on shared memory resources and yet reduce the number of disk access to do ACL checking. This value must be greater than or equal to 10 and less than or equal to 30,000. The default is 100.

MAXCONV = number

Specifies the maximum number of simultaneous conversations in which processes on a particular machine can be involved. It must be greater than 0 and less than 32,768. If not specified, the default is the value specified in the RESOURCES section. The maximum number of simultaneous conversations per server is 64.

MAXPENDINGBYTES = number

Specifies a limit for the amount of space that can be allocated for messages waiting to be transmitted by the bridge process. number must be between 100,000 and MAXLONG.

MAXGTT = number

Specifies the maximum number of simultaneous global transactions in which a particular machine can be involved. It must be greater than or equal to 0 and less than 32,768. If not specified, the default is the value specified in the RESOURCES section.

TYPE = string_value

Used for grouping machines into classes. TYPE can be set to any string value that is 15 characters or less. If two machines have the same TYPE value, data encoding/decoding is bypassed when sending data between the machines. TYPE can be given any string value. It is used simply for comparison. The TYPE parameter should be used when the application involves a heterogeneous network of machines or when different compilers are used on the machines in the network. If not specified, the default is the null string, which matches any other entry that does not have a value specified.

CMPLIMIT = string_value1[,string_value2]

Specifies the threshold message size for messages bound to remote processes (string_value1) and local processes (string_value2) respectively, at which automatic data compression will take place. Both values must be either a non-negative numeric value or the string MAXLONG. If not specified, the default for this parameter is MAXLONG,MAXLONG.

NETLOAD = numeric_value

Specifies the additional load to be added when computing the cost of sending a service request from this machine to another machine. It must be greater than or equal to 0 and less than 32,768. If not specified, the default is 0.

SPINCOUNT = numeric_value

Specifies the number of attempts that should be made at user level to lock the Bulletin Board before blocking processes on a UNIX semaphore. This value must be greater than or equal to 0. A value of 0 indicates that the spincount built into the delivered binary should be used. If set, this parameter causes the TMSPINCOUNT environment variable to be ignored. This varies from platform to platform. The default for this parameter is 0.

TLOGDEVICE = string_value

Specifies the BEA Tuxedo file system that contains the DTP transaction log (TLOG) for this machine. The TLOG is stored as a BEA Tuxedo system VTOC table on the device. If this parameter is not specified, then the machine is assumed to not have a TLOG. The maximum string value length is 64 characters.

TLOGOFFSET = offset

Specifies the numeric offset in pages (from the beginning of the device) to the start of the BEA Tuxedo file system that contains the DTP transaction log for this machine. The offset must be greater than or equal to 0 and less than the number of pages on the device. The default is 0.

TLOGNAME = string_value

Specifies the name of the DTP transaction log for this machine. If not specified, the default is TLOG. If more than one TLOG exists on the same TLOGDEVICE, they must have unique names. TLOGNAME must be different from the name of any other table on the configuration where the TLOG table is created. It must be 30 characters or less.

TLOGSIZE = size

Specifies the numeric size, in pages, of the DTP transaction log for this machine. It must be greater than 0 and less than or equal to 2048, subject to the amount of available space on the BEA Tuxedo file system. If not specified, the default is 100 pages.

ULOGPFX = string_value

Specifies the absolute pathname prefix of the path for the userlog(3c) message file on this machine. The value of ULOGPFX for a given machine is used to create the userlog(3c) message file for all servers, clients, and administrative processes executed on that machine. If this parameter is not specified, $APPDIR/ULOG is used. "mmddyy" (month, day, year) is appended to the prefix to get the actual log filename.

TUXOFFSET = offset

Specifies the numeric offset in pages (from the beginning of the device) to the start of the BEA Tuxedo file system that contains the TUXCONFIG for this machine. The offset must be greater than or equal to 0 and less than the number of pages on the device. The default offset is 0. The value of TUXOFFSET, if non-zero, is placed in the environment of all servers booted on a machine. See ENVFILE in the MACHINES section for a discussion of how this value is used in the environment.

ENVFILE = string_value

Specifies that all clients and servers on the machine are to be executed with the environment specified in the named file. If the value specifies an invalid filename, no values are added to the environment. Lines must be of the form ident=value where ident begins with an underscore or alphabetic character, and contains only underscore or alphanumeric characters. Within the value, strings of the form ${env} are expanded when the file is processed using variables already in the environment. (Forward referencing is not supported and if a value is not set, the variable is replaced with the empty string). Backslash (\) may be used to escape the dollar sign and itself. All other shell quoting and escape mechanisms are ignored and the expanded value is placed into the environment.

Client programs process only the MACHINES ENVFILE during tpinit()

When booting servers, local servers inherit the environment of tmboot(1) and remote servers (not on the MASTER) inherit the environment of tlisten(1). TUXCONFIG, TUXDIR, and APPDIR are also put into the environment when a server is booted based on the information in the associated MACHINES entry. An attempt to reset these three variables to another value will not be allowed and will result in a warning. tmboot and tlisten process the machine ENVFILE before starting the server, allowing for the environment to indicate necessary pathnames for finding executable and dynamically loaded files. Once the server is running, as part of server initialization (before the application gets control in tpsvrinit), a server will read and export variables from both the machine and server ENVFILE files. If a variable is set in both the machine and server ENVFILE, the value in the server ENVFILE will override the value in the machine ENVFILE.

PATH and LD_LIBRARY_PATH are treated specially. Before a server is activated, the machine ENVFILE is scanned to find the first occurrence of a PATH or LD_LIBRARY_PATH variable; embedded environment variables within either PATH variable are not expanded. PATH and LD_LIBRARY_PATH are used to find pathnames for executable and dynamically loaded files. PATH will always be prefixed with:

${APPDIR}:${TUXDIR}/bin:/bin:

if the value doesn't already begin with this string. This PATH will be used as a search path for servers that are specified with a simple or relative pathname. LD_LIBRARY_PATH will always be prefixed with:

${APPDIR}:${TUXDIR}/lib:/lib:/usr/lib:

if the value doesn't already begin with this string. SHLIB_PATH is set on HPUX and LIBPATH is set on AIX instead of LD_LIBRARY_PATH. LIB is set on Windows NT systems instead of LD_LIBRARY_PATH.

This section provides information about server groups. This section must have at least one server group defined in it (which can be added via tmconfig(1) after the TUXCONFIG file has been created). A server group entry provides a logical name for a collection of servers and/or services on a machine. The logical name is used as the value of the SRVGRP parameter in the SERVERS section to identify a server as part of this group. SRVGRP is also used in the SERVICES section to identify a particular instance of a service with its occurrences in the group. Other GROUPS parameters associate this group with a specific resource manager instance (for example, the employee database). Lines within the GROUPS section have the form:

GROUPNAME required parameters [optional parameters] 

where GROUPNAME specifies the logical name (string_value) of the group. The group name must be unique within all group names in the GROUPS section and LMID values in the MACHINES section and cannot contain an asterisk (*), comma, or colon. It must be 30 characters or less.

Required parameters are:

LMID = string_value1 [, string_value2]

Specifies that this group of servers resides on the machine symbolically named by string_value1 in the MACHINES section (or the default in SHM mode). Each LMID value must be 30 characters or less. Up to two logical machine names can be specified. The second logical name, if given and if server group migration is enabled, indicates the machine to which the server group can be migrated.

GRPNO = number

Specifies the numeric group number associated with this server group. This number must be greater than 0 and less than 30,000, and must be unique among all entries in the GROUPS section.

Optional parameters are:

TMSNAME = string_value

Specifies the name of the transaction manager server a.out associated with this group. This parameter must be specified for any group entry whose servers will participate in distributed transactions (transactions across multiple resource managers-and possibly machines-that are started with tpbegin(3c), and ended with tpcommit(3c)/ tpabort(3c)). It specifies the file (string_value) to be executed by tmboot(1) when booting the server group. The value TMS is reserved to indicate use of the null XA interface. If a non-empty value other than TMS is specified, then a TLOGDEVICE must be specified for the machine(s) associated with the LMID value(s) for this entry. A unique server identifier is selected automatically for each TM server, and the servers will be restartable an unlimited number of times.

ENVFILE = string_value

Specifies that all servers in the group are to be executed with the environment specified in the named file. If the value specifies an invalid filename, no values are added to the environment. Lines must be of the form ident=value where ident contains only underscore or alphanumeric characters. Within the value, strings of the form ${env} are expanded when the file is processed using variables already in the environment. (Forward referencing is not supported and if a value is not set, the variable is replaced with an empty string.) A backslash (\) may be used to escape the dollar sign and itself. All other shell quoting and escape mechanisms are ignored and the expanded value is placed in the environment.

The ENVFILE is read after the MACHINES section ENVFILE (if one exists) and before the SERVERS section ENVFILE (if one is specified).

TMSCOUNT = number

Specifies the number of transaction manager servers to start for the associated group, if TMSNAME is specified. This parameter is optional and the default is 3. If specified and the value is non-zero, the minimum value is 2 and the maximum value is 10. The servers are set up in an MSSQ set automatically.

OPENINFO = "string"

Specifies the resource manager instance-dependent information needed when opening the resource manager. The value must be enclosed in double quotes and must be less than or equal to 256 characters in length. This value is ignored if TMSNAME is not set or is set to TMS. The format of the OPENINFO string is dependent on the requirements of the vendor providing the underlying resource manager. The information required by the vendor must be prefixed with "rm_name:," which is the published name of the vendor's transaction (XA) interface followed immediately by a colon (:).

For BEA Tuxedo system databases, the format is:

OPENINFO="TUXEDO/D:fsconfig:dbname:openmode"

where "TUXEDO/D" is the published name of the BEA Tuxedo XA interface, fsconfig is the name of the FSCONFIG on which the database resides, dbname is the name of the database, and openmode is one of "readonly" or "readwrite". For Windows NT and NetWare, the colon separator after fsconfig and dbname must be a semicolon.

For BEA Tuxedo system/SQL databases, the format is:

OPENINFO="TUXEDO/SQL:fsconfig:dbname:openmode"

where "TUXEDO/SQL" is the published name of the BEA Tuxedo system/SQL XA interface, fsconfig is the name of the FSCONFIG on which the database resides, dbname is the name of the database, and openmode is one of "readonly" or "readwrite". For Windows NT and NetWare, the colon separator after fsconfig and dbname must be a semicolon.

For BEA Tuxedo /Q databases, the format is:

OPENINFO="TUXEDO/QM:qmconfig:qspace"

where "TUXEDO/QM" is the published name of the BEA Tuxedo /Q XA interface, qmconfig is the name of the QMCONFIG on which the queue space resides and qspace is the name of the queue space. For Windows NT and NetWare, the colon separator after qmconfig must be a semicolon.

If TMSNAME is set but the OPENINFO string is set to the null string ("") or this parameter does not appear on the entry, it means that a resource manager exists for the group but does not require any information for executing an open operation.

Passwords that are passed to a resource manager in the OPENINFO string can be stored in either clear text or encrypted form. Encrypting of passwords is done by the tmloadcf utility. To encrypt a password, you first enter a series of five or more continuous asterisks in the OPENINFO string at the place where you want the password to go. When tmloadcf encounters the string of asterisks, it prompts the user to create a password. For example:

>tmloadcf -y e:/wle5/samples/atmi/bankapp/xx
Password for OPENINFO (SRVGRP=BANKB1):

The password is stored in the TUXCONFIG file in encrypted form.

Note: If the user then generates a UBBCONFIG file using tmunloadcf, the password is printed in encrypted form with @@ as delimiters.

CLOSEINFO = "string"

Specifies the resource manager instance-dependent information needed when closing the resource manager. The value must be enclosed in double quotes and must be less than or equal to 256 characters in length. This value is ignored if TMSNAME is not set or is set to TMS. The format of the CLOSEINFO string is dependent on the requirements of the vendor providing the underlying resource manager. The information required by the vendor must be prefixed with "rm_name:," which is the published name of the vendor's transaction (XA) interface followed immediately by a colon (:). For BEA Tuxedo system/SQL databases, a CLOSEINFO string is not used. If TMSNAME is set but the CLOSEINFO string is set to the null string ("") or this parameter does not appear on the entry, it means that a resource manager exists for the group but does not require any information for executing a close operation.

The NETGROUPS section describes the network groups available to the application in the LAN environment. Any pair of machines may be in any number of network groups. Two communicating nodes use the priority mechanism in order to determine how to communicate between elements of its group.

Every LMID must be a member of the default network group, DEFAULTNET. Machines running BEA Tuxedo releases earlier than Release 6.4 (in which NETGROUPS became available) can belong only to the DEFAULTNET network group. The network group number (NETGRPNO) for DEFAULTNET. is 0 (zero), and may not be changed. The default priority of DEFAULTNET, however, may be modified.

The general format for entries in this section is:

NETGROUP required_parameters [ optional_parameters ]

where NETGROUP is the network group name. If NETGROUP is equal to DEFAULTNET then the entry describes the default network group.

The following parameter is required:

NETGRPNO = numeric_value

This is a unique network group number which must be assigned by the administrator for use in failover and failback situations. If this entry describes DEFAULTNET, then the numeric value must be 0 (zero).

The following parameter is optional:

NETPRIO = numeric_value

Specifies the priority of this network group. A pair of machines in multiple network groups of the same priority will communicate in parallel over the priority band as long as no network group of a higher priority is available. If all the network links of a certain priority band have been torn down by the administrator or by network conditions, then the next lowest priority band is used. Retries of the higher priority bands will be attempted. For more information, see the chapter on BEA Tuxedo networks in the BEA Tuxedo Administrator's Guide This value must be greater than zero and less than 8192. If not specified, the default is 100. Note that this is the only parameter of the DEFAULTNET that can be altered.

Note: In Release 6.4, parallel data circuits are prioritized by network group number (NETGRPNO) within priority group number. In future releases, a different algorithm may be used to prioritize parallel data circuits.

The NETWORK section describes the network configuration for a LAN environment. For each processor on which a bridge server is located, an entry must be placed in the NETWORK section giving the network address of the bridge process. An error is generated if this section exists and LAN is not specified for the OPTIONS parameter of the RESOURCES section.

The general format for entries in this section is:

LMID required parameters [optional parameters] 

where LMID is the logical machine where the bridge process is placed. LMID must have direct access to the network device to be used (as given in the BRIDGE parameter).

The following parameter is required:

NADDR = string_value

Specifies the complete network address to be used by the bridge process placed on the LMID as its listening address. The listening address for a bridge is the means by which it is contacted by other bridge processes participating in the application. If string_value has the form "0xhex-digits" or "\\xhex-digits", it must contain an even number of valid hex digits. These forms are translated internally into a character array containing TCP/IP addresses may also be in either of the following two forms:

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

In the first of these formats, hostname is resolved to a TCP/IP host address at the time the address is bound using the locally configured name resolution facilities accessed via an operating system command. The "#.#.#.#" is the dotted decimal format where each # represents a decimal number in the range 0 to 255. Port_number is a decimal number in the range 0 to 65,535. the hexadecimal representations of the string specified.

The following parameters are optional:

BRIDGE = string_value

Specifies the device name to be used by the bridge process placed on that LMID to access the network. The BRIDGE parameter is not required. In prior releases, for networks that were TLI-based, an absolute pathname for a device was required as the value of BRIDGE. The network transport endpoint file path has the form: /dev/provider_name. For StarLAN this is: /dev/starlan.

NLSADDR = string_value

Specifies the network address used by the tlisten(1) process servicing the network on the node identified by the LMID. The network address used for NLSADDR is of the same format as that specified for the NADDR parameter above. If the address has the form "0xhex-digits" or "\\xhex-digits", it must contain an even number of valid hex digits. TCP/IP addresses may be in the "//#.#.#.#:port" format. tmloadcf(1) prints an error if NLSADDR is missing on any entry but the MASTER LMID, for which it prints a warning. However, if NLSADDR is missing on the MASTER LMID, tmadmin(1) will not be able to run in administrator mode on remote machines; it will be limited to read-only operations. This also means that the backup site will be unable to to reboot the master site after failure.

MINENCRYPTBITS={0|40|128}

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

MAXENCRYPTBITS={0|40|128}

When establishing a network link, negotiate encryption up to this level. 0 means no encryption, while 40 and 128 specify the encryption length (in bits). The default is 128

NETGROUP = string_value

string_value is the network group associated with this network entry. If unspecified, then the default, DEFAULTNET, is assumed. The NETGROUP parameter, if not set to DEFAULTNET, must have previously appeared as a group name in the NETGROUPS section of the file. All network entries with a NETGROUP DEFAULTNET are represented in the T_MACHINE class of the TM_MIB, while NETWORK entries associated with any other NETGROUP are represented in the T_NETMAP class of the TM_MIB to interoperate with previous releases.

This section provides information on the initial conditions for servers started in the system. The notion of a server as a process that continually runs and waits for a server group's service requests to process, may or may not apply to a particular remote environment. For many environments, the operating system or perhaps a remote gateway will be the sole dispatcher of services; when either of these is the case, only SERVICE table entries (see next section) and no SERVER table entries need be specified for remote program entry points; BEA Tuxedo system gateway servers would advertise and queue remote domain service requests. Host-specific reference pages must indicate whether or not UBBCONFIG server table entries apply in their particular environments, and if so, the corresponding semantics. Lines within the SERVERS section have the form:

AOUT required parameters [optional parameters] 

where AOUT specifies the file (string_value) to be executed by tmboot(1). tmboot executes AOUT on the machine specified for the server group to which the server belongs. tmboot searches for the AOUT file on its target machine. Thus, AOUT must exist in a file system on that machine. (Of course, the path to AOUT can include RFS connections to file systems on other machines.) If a relative pathname for a server is given, the search for AOUT is done first in APPDIR, then in TUXDIR/bin, then in /bin, and then in path> where path> is the value of the last PATH= line appearing in the machine environment file, if one exists. The values for APPDIR and TUXDIR are taken from the appropriate machine entry in the TUXCONFIG file. See ENVFILE in the MACHINES section for a more detailed discussion.

The following parameters are required:

SRVGRP = string_value

Specifies the group name for the group in which the server is to run. string_value must be the logical name associated with a server group in the GROUPS section. It must be 30 characters or less. This association with an entry in the GROUPS section means that AOUT is executed on the machine with the LMID specified for the server group. It also specifies the GRPNO for the server group and parameters to pass when the associated resource manager is opened. All server entries must have a server group parameter specified.

SRVID = number

Specifies an integer that uniquely identifies a server within a group. Identifiers must be between 1 and 30,000 inclusive. This parameter must be present on every server entry.

The optional parameters are divided into two categories: boot options and run-time options. Boot options are used by tmboot(1) when it executes a server. Once running, a server reads its entry from the configuration file to determine its run-time options. The unique server ID is used to find the right entry.

Optional boot parameters are:

CLOPT = string_value

Specifies servopts(5) options to be passed to AOUT when booted. If none is specified, the default is -A. string_value can be up to 256 characters in length.

For JavaServer, the CLOPT options are:

CLOPT="-A -- [java_options]"

Where:

• java_options are Java Virtual Machine (JVM) options, similar to the options that are passed to the java interpreter command.

  Note: Use of the archive-file and options parameters to specify the application JAR file was deprecated in BEA WebLogic Enterprise 5.1. For more information, refer to "JavaServer Parameters" and "The MODULES Section".

SEQUENCE = number

Specifies when this server should be booted or shut down relative to other servers. If the SEQUENCE parameter is not specified, servers are booted in the order found in the SERVERS section (and shut down in the reverse order). If a mixture of servers with and without sequence numbers is given, all servers with sequence numbers are booted first from low to high sequence number, then all servers without sequence numbers are booted in the order they appear in the configuration file. Sequence numbers must be in the range between 1 and 9999.

MIN = number

Specifies the minimum number of occurrences of the server to boot by tmboot. If an RQADDR is specified and MIN is greater than 1, then the servers will form an MSSQ set. The server identifiers for the servers will be SRVID up to SRVID + MAX - 1. All occurrences of the server will have the same sequence number, as well as any other server parameters. The value range for MIN is 0 to 1000. If not specified, the default is 1.

MAX = number

Specifies the maximum number of occurrences of the server that can be booted. Initially, tmboot boots MIN servers, and additional servers can be booted up to MAX occurrences using the -i option of tmboot to specify the associated server identifier. The value range for MAX is 0 to 1000. If not specified, the default is the same value as MIN.

MAXDISPATCHTHREADS = number

Specifies the maximum number of concurrently dispatched threads which each server process may spawn. If MAXDISPATCHTHREADS > 1, then as separate dispatcher thread is used and does not count against this limit. It is required that MINDISPATCHTHREADS <= MAXDISPATCHTHREADS. If not specified, the default value for this parameter is 1.

MINDISPATCHTHREADS = number

Specifies the number of server dispatch threads started on initial server boot. The separate dispatcher thread that is used when MAXDISPATCHTHREADS > 1 is not counted as part of the MINDISPATCHTHREADS value. It is required that MINDISPATCHTHREADS <= MAXDISPATCHTHREADS. The default value for this parameter is 0.

THREADSTACKSIZE = number

Specifies the stack size in bytes for each server thread after the initial thread. If not specified or specified as 0, the operating system default value is used. This option has an effect on the server only when a value greater than 1 is specified for MAXDISPATCHTHREADS.

The optional run-time parameters are as follows:

ENVFILE = string_value

Requests the addition of the values in this file to the environment of the server during its initialization. If a server is associated with a server group that can be migrated to a second machine, the ENVFILE must be in the same location on both machines.

Note that this file is processed after the server starts. Therefore, it cannot be used to set the pathnames used to find executable or dynamically loaded files needed to execute the server; use the machine ENVFILE instead. See ENVFILE in the MACHINES section for a discussion of how this file is used to modify the environment.

CONV = { Y | N }

Specifies whether or not the server is a conversational server. Connections can only be made to conversational servers, and rpc requests (via tpacall(3c) or tpcall(3c)) can only be made to non-conversational servers. The default is N.

RQADDR = string_value

Specifies the symbolic name of the request queue for AOUT. It must be 30 characters or less. If not specified, a unique key (GRPNO.SRVID) is chosen for a queue that AOUT accesses. Specifying the same RQADDR for more than one server is the way multiple server, single queue (MSSQ) sets are achieved. If two servers are given an RQADDR with the same queue name, they must be in the same server group.

RQPERM = number

Specifies the numeric permissions on the request queue. number is specified in the usual UNIX fashion (for example, 0600). If RQPERM is not specified, and a PERM is specified in the RESOURCES section, then that value is used. Otherwise, a value 0666 is used. The value can be between 0001 and 0777, inclusive.

REPLYQ = { Y | N }

Specifies whether a reply queue should be established for the AOUT. If Y is specified, the reply queue is created on the same LMID as the AOUT. The default is N. For servers in an MSSQ set, servers that expect replies should have REPLYQ set to Y.

RPPERM = number

Specifies the numeric permissions on the reply queue. number is specified in the usual UNIX fashion (for example, 0600). If RPPERM is not specified, the default value 0666 is used. If requests and replies are both read from the same queue, only RQPERM need be specified; RPPERM is ignored. The value can be between 0001 and 0777, inclusive.

RCMD = string_value

If AOUT is restartable, this parameter specifies the command that should be executed when AOUT abnormally terminates. The string, up to the first space or tab, must be the name of an executable UNIX file, either a full pathname or relative to APPDIR (do not attempt to set a shell variable at the beginning of the command). The command name may be optionally followed by command-line arguments. Two additional arguments are appended to the command line: the GRPNO and SRVID associated with the restarting server. string_value is executed in parallel with restarting the server.

MAXGEN = number

If AOUT is restartable, this parameter specifies that it can be restarted at most number - 1 times within the period specified by GRACE. The value must be greater than 0 and less than 256. If not specified, the default is 1 (which means that the server can be started once, but not restarted).

GRACE = number

If AOUT is restartable, this parameter specifies that it can have up to MAXGEN lives within the specified number of seconds. The value must be greater than or equal to 0 and less than 2147483648. If 0, the AOUT can be restarted an unlimited number of times. If GRACE is not specified, the default is 86,400 seconds (24 hours).

RESTART = { Y | N }

Specifies whether or not AOUT is restartable. The default is N. If server migration is specified, RESTART must be set to Y. Note that a server terminated with a SIGTERM signal cannot be restarted; it must be rebooted.

SYSTEM_ACCESS identifier[,identifier]

Specifies the default mode used by BEA Tuxedo system libraries within application processes to gain access to BEA Tuxedo system's internal tables. Valid access types are FASTPATH or PROTECTED. FASTPATH specifies that the internal tables should be accessible by the libraries via shared memory for fast access. PROTECTED specifies that while the internal tables are accessible by BEA Tuxedo system libraries via shared memory, the shared memory for these tables is not accessible outside of the BEA Tuxedo system libraries. NO_OVERRIDE can be specified (either alone or in conjunction with FASTPATH or PROTECTED) to indicate that the mode selected cannot be overridden by an application process. If SYSTEM_ACCESS is not specified, the default mode is determined by the setting of the SYSTEM_ACCESS keyword in the RESOURCES section.

The following parameters are specific to JavaServer:

SRVTYPE=JAVA

If SRVTYPE is set to JAVA, it indicates that the server is a JavaServer. If at least one MODULE attribute is specified for this server or the name of the server is JavaServer (not case sensitive), JAVA becomes the default value.

• SRVGRP-the name of the BEA WebLogic Enterprise group in the GROUPS section of the UBBCONFIG file.

• SRVID-a numeric identifier of the server in the group.

• MAXEJBCACHE-the capacity of the EJB cache. You use this parameter to specify the maximum number of beans that can be cached (that is, not passivated) at one time. This parameter is used for performance tuning. The following values can be specified:

  Note: By default, if MAXEJBCACHE is not specified, the cache size is set to the larger of 10 or the number of threads (-M option) + 1.

  n	The maximum number of beans that can be contained in the cache where n is greater than zero.
  0	Disables the cache and results in the same behavior as in BEA WebLogic Enterprise 5.0.

  Note: It is very important that you set the cache accurately for your EJB application as it directly affects performance. For more information, refer to the BEA WebLogic Enterprise Administration Guide.

• EJBCACHE_FLUSH-the number of minutes between EJB cache flushes. At the interval specified by this value, all beans that are not currently involved in a transaction or a method invocation are passivated and their memory is released. You can specify the following values:

  n	The flush time in minutes, where n is greater than zero.
  0	No time-determined flush. The beans are passivated only when the cache becomes full. This is the default if EJBCACHE_FLUSH is not set.

• java options-The JavaServer command-line options (CLOPT) are Java Virtual Machine (JVM) options, similar to the options that are passed to the java interpreter command. For more information on these options, refer to the BEA WebLogic Enterprise Administration Guide.

  Note: The JavaServer MODULE, archive_file, and options parameters were deprecated in BEA WebLogic Enterprise 5.1. To replace the MODULE parameter, the MODULES section was added to the UBBCONFIG file. For a description of the MODULES section, refer to "The MODULES Section".

The MODULES Section

When you use BEA WebLogic Enterprise 5.1 or later software to write applications in Java, you specify the JavaServer parameters in the SERVERS and MODULES section of the UBBCONFIG file.

Notes: In the 5.1 release, a MODULES section was added to the UBBCONFIG file to replace the MODULE line(s) and the archive_file and options parameters in the JavaServer command-line options (CLOPT) in the SERVERS section. The deprecated parameters are described in section "JavaServer Parameters". The MODULES section must follow the SERVERS section in the UBBCONFIG file.

The MODULES section format is as follows:

*MODULES
<module_name>    SRVGRP=<group_name>
                 SRVID=<server_id>
                 FILE=<filename>
                 [ARGS=<arguments>]
                 [CLASSPATH=<local_classpath>]
[<module_name2>   ...] 

The MODULES section parameters are as follows:

<module_name>

Identifies this module within this domain. This is a logical name that will be used when referring to this module (required parameter).

SRVGRP=<group_name>

Specifies the name of the server group (required parameter).

SRVID=<server_id>

Specifies the ID of the server (required parameter).

FILE=<filename>

Specifies the JAR file that contains the EJB or CORBA descriptor, the remote and home interfaces, the implementation classes for the remote and home interfaces, the classes for the stubs and keys, and so on (required parameter). The JAR file typically contains the class that actually implements the module's business logic, but it is not required to do so.

ARGS=<arguments>

Provides values that will be used to initialize the module (optional parameter).

CLASSPATH=<local_classpath>

Indicates a "local class path" that can specify additional classes that may be required by the main JAR (optional parameter). For example, this parameter can be used for third party utility classes, business libraries, and so on. This parameter follows the standard Java class path semantics and is searched after searching the system/server class path and the main jar of the module. For the BEA WebLogic Enterprise 5.1 and later releases, only JAR or ZIP files may be specified.

For all files, if an absolute path is given, that path will be used. If a relative path is specified, it will be relative to the APPDIR specified earlier in the UBBCONFIG file. Since APPDIR represents one or more paths (separated by ";"), all path combinations are checked when a relative path is used and the first match is used.

Note: The UBBCONFIG parser will recognize illegal fields and inform the user. The order of the fields does not matter.

For more information about using the MODULES section, refer to the BEA WebLogic Enterprise Administration Guide.

This section is used to configure connection pooling for Java Database Connectivity (JDBC). Pooling of JDBC connections is provided by the BEA WebLogic Enterprise infrastructure to conserve resources and improve performance. Each entry in the section represents a JDBC connection pool. This section has the following characteristics:

• The entries in this section start with the names of connection pools.

• The SRVID and SRVGRP statements must refer to a Java server that is specified in the SERVERS section.

• Only the SRVGRP, SRVID, MAXCAPACITY, and CAPACITYINCR attributes are required for entries.

• Some attributes are dependent on the version of the JDBC driver.

Required parameters are:

SRVID=number

wait_interval defines the interval (in seconds) for an application to wait for a connection to become available. wait_interval can be any number 0 or larger.

The SERVICES Section

This section provides information on services used by the application. Lines within the SERVICES section have the form:

SVCNM [optional parameters]

where SVCNM is the (string_value) name of the service. SVCNM must be 15 characters or fewer in length.

There are no required parameters. Services need not be listed if no optional parameters need to be set. Optional parameters are:

LOAD = number

Specifies that SVCNM imposes a load on the system of number. number can be between 1 and 32767 inclusive. If not specified, the default is 50. A higher number indicates a greater load.

PRIO = number

Specifies that SVCNM has a dequeuing priority of the specified number. The value must be greater than 0 and less than or equal to 100, with 100 being the highest priority. The default is 50.

SRVGRP = string_value

This parameter says that any parameters specified apply to SVCNM within server group string_value. The use of SRVGRP allows the same service to have different parameter settings within different server groups. It must be 30 characters or less.

BUFTYPE = "type1[:subtype1[,subtype2 . . . ]][;type2[:subtype3[, . . . ]]] . . .

A list of types and subtypes of data buffers accepted by this service. This parameter can be up to 256 characters in length and a maximum of 32 type/subtype combinations are allowed. Types of data buffers provided with BEA Tuxedo system are FML (for FML buffers), VIEW, X_C_TYPE, or X_COMMON (for FML views), STRING (for NULL terminated character arrays) and CARRAY or X_OCTET (for a character array that is neither encoded nor decoded during transmission). Of these types, only VIEW, X_C_TYPE, and X_COMMON have subtypes. A view subtype gives the name of the particular view expected by the service. Application types and subtypes can also be added (see tuxtypes(5)). For a TYPE that has subtypes, "*" can be specified for the subtype to indicate that the service accepts all subtypes for the associated type.

A single service can only interpret a fixed number of buffer types, namely those found in its buffer type switch (see tuxtypes(5)). If the BUFTYPE parameter is set to ALL, that service will accept all buffer types found in its buffer type switch. Omitting the BUFTYPE parameter is equivalent to setting it to ALL. If multiple entries exist for the same service name but with different SRVGRP parameters, the BUFTYPE parameter must be the same for all of these entries.

A type name can be 8 characters or less in length and a subtype name can be 16 characters or less in length. Note that type and subtype names should not contain semicolon, colon, comma, or asterisk characters (this will make it hard to see where type and subtype values end).

Some examples of valid BUFTYPE specifications are:

BUFTYPE=FML implies that the service takes FML buffers.
BUFTYPE=VIEW:* implies that the service takes all subtypes
of FML views.

ROUTING = string_value

Specifies the name of the routing criteria used for this service when doing data dependent routing. If not specified, data dependent routing is not done for this service. string_value must be 15 characters or less in length. If multiple entries exist for the same service name but with different SRVGRP parameters, the ROUTING parameter must be the same for all of these entries.

SVCTIMEOUT = number

Specifies the amount of time, in seconds, that is allowed for processing of the indicated service. The value must be greater than or equal to 0. A value of 0 indicates that the service will not be timed out. A timed-out service will cause the server processing the service request to be terminated with a SIGKILL signal. The default for this parameter is 0.

The following parameters are for DTP applications only:

AUTOTRAN = { Y | N }

Specifies whether or not a transaction should automatically be started if a request message is received that is not already in transaction mode. The default is N.

TRANTIME = number

Specifies the default timeout value in seconds for a transaction automatically started for the associated service. The value must be greater than or equal to 0 and less than 2147483648. The default is 30 seconds. A value of 0 implies the maximum timeout value for the machine.

The INTERFACES Section

This section provides information for defining application-wide default parameters for CORBA or EJB interfaces used by the application. There are no required parameters for CORBA interfaces unless you are implementing factory-based routing, a BEA WebLogic Enterprise feature that allows you to distribute processing to specific server groups. If you are implementing factory-based routing, you must specify the following parameters:

Table 0-46 Factory-based Routing Parameters

In this section...	You must specify...
INTERFACES	Names of the interfaces being used Names of the routing criteria that the system should apply to each interface
ROUTING	Routing criteria
GROUPS	Names of the server groups

You do not need to list any CORBA interfaces if you do not want to specify any parameters.

The following optional parameters are available.

AUTOTRAN = {Y | N }

Indicates that you want the system to automatically initiate a transaction on every operation invocation and end it upon return from the invocation. The AUTOTRAN parameter is only honored for interfaces that have the optional transaction policy. Otherwise, this parameter is ignored. The default is N.

The transactional policy is specified in an implementation configuration file. This transactional policy will become the transactional policy attribute of the associated T_IFQUEUE MIB object at runtime.

Before setting the AUTOTRAN value, the system administrator must know the value of the transactional policy assigned to the interface by the programmer. Without knowing the policy, the administrator's expectations of run-time AUTOTRAN functionality may be wrong.

If AUTOTRAN is set to Y, you must also set the TRANTIME parameter.

AUTOTRAN=Y is not supported for EJB interfaces.

FACTORYROUTING = criterion-name

Specifies the name of the routing criterion to be used for factory-based routing for this CORBA interface. You must specify a FACTORYROUTING parameter for transactions requesting factory-based routing. This feature is not supported for EJB.

LOAD = number

An arbitrary number between 1 and 100 that represents the relative load that the CORBA interface is expected to impose on the system. The numbering scheme is relative to the LOAD numbers assigned to other CORBA interfaces used by this application. The default is 50. The value of LOAD is used by the BEA WebLogic Enterprise system to select the best machine to enqueue a request. The routing of the request causes the server's total load to be increased by the LOAD factor of the CORBA interface requested.

PRIO = number

Specifies the dequeuing priority number for all methods of the CORBA interface. The value must be greater than 0 and less than or equal to 100. 100 is the highest priority. The default is 50.

SRVGRP = server-group-name

Indicates that any parameter defined in this portion of the INTERFACES section applies to the interface within the specified server group. This feature lets you define, for a given CORBA interface, different parameter values in different server groups.

TRANTIME = number

The length of the timeout (in seconds) for the transactions to be computed. If AUTOTRAN is set to Y, you must set the TRANTIME parameter. The value must be greater than or equal to zero and must not exceed 2,147,483,647 (2³¹ - 1), or about 70 years. A value of 0 implies there is no time out for the transaction. (The default is 30 seconds.) This feature is not supported for EJB.

TIMEOUT = number

Indicates the amount of time (in seconds) to allow for processing of a method for this CORBA or EJB interface. The value must be greater than or equal to 0. A value of 0 indicates that the interface cannot time out. A timed-out method causes the server processing the method for the interface to terminate with a SIGKILL event. We recommend specifying a time out value for the longest-running method for the interface.

The ROUTING Section

This section provides information for data dependent routing of service requests using FML buffers and views. The routing criteria specified here are used only if the default routing functions, _froute and _vroute, are being used (see tuxtypes(5)). Lines within the ROUTING section have the form:

CRITERION_NAME required parameters 

where CRITERION_NAME is the (string_value) name of the routing entry that was specified on the services entry. CRITERION_NAME must be 15 characters or less in length.

Required parameters are:

TYPE

Specifies the routing type. The default is TYPE=SERVICE to ensure that existing UBBCONFIG files used in BEA Tuxedo environments continue to work properly. Use TYPE=FACTORY if you are implementing factory-based routing for a BEA WebLogic Enterprise interface.

FIELD = string_value

Specifies the name of the routing field. It must be 30 characters or less. This field is assumed to be an FML buffer or view field name that is identified in an FML field table (using the FLDTBLDIR and FIELDTBLS environment variables) or an FML view table (using the VIEWDIR and VIEWFILES environment variables), respectively. This information is used to get the associated field value for data-dependent routing during the sending of a message. If a field in an FML32 buffer will be used for routing, it must have a field number less than or equal to 8191.

FIELDTYPE=value

Specifies the type of the routing field. Field types supported are:

SHORT -215 ... 215 - 1 (16 bit)

LONG -231 ... 231 - 1 (32 bit)

FLOAT IEEE single-precision floating point numbers

DOUBLE IEEE double-precision numbers

CHAR A single character; an 8-bit quantity

STRING A null-terminated character array

RANGES = "string"

Specifies the ranges and associated server groups for the routing field. string must be enclosed in double quotes. string can be up to 2048 characters in length (except in Domains, where string can be up to 1024 characters). The format of string is a comma-separated ordered list of range/group_name pairs (see Example below).

A range is either a single value (signed numeric value or character string in single quotes), or a range of the form "lower - upper" (where lower and upper are both signed numeric values or character strings in single quotes). Note that "lower" must be less than or equal to "upper". To embed a single quote in a character string value (as in O'Brien, for example), it must be preceded by two backslashes ('O\\'Brien'). The value MIN can be used to indicate the minimum value for the data type of the associated FIELD on the machine. The value MAX can be used to indicate the maximum value for the data type of the associated FIELD on the machine. Thus, "MIN - -5" is all numbers less than or equal to -5 and "6 - MAX" is all numbers greater than or equal to 6. The meta-character "*" (wildcard) in the position of a range indicates any values not covered by the other ranges previously seen in the entry; only one wildcard range is allowed per entry and it should be last (ranges following it will be ignored).

The routing field can be of any data type supported in FML. A numeric routing field must have numeric range values, and a string routing field must have string range values.

String range values for string, carray, and character field types must be placed inside a pair of single quotes and cannot be preceded by a sign. Short and long integer values are strings of digits, optionally preceded by a plus or minus sign. Floating point numbers are of the form accepted by the C compiler or atof: an optional sign, then a string of digits optionally containing a decimal point, then an optional e or E followed by an optional sign or space, followed by an integer.

The group name indicates the associated group to which the request is routed if the field matches the range. A group name of "*" indicates that the request can go to any group where a server offers the desired service.

Within a range/group pair, range is separated from the group name by a ":".

BUFTYPE = "type1[:subtype1[,subtype2 . . . ]][;type2[:subtype3[, . . . ]]] . . ."

A list of types and subtypes of data buffers for which this routing entry is valid. This parameter can be up to 256 characters in length and a maximum of 32 type/subtype combinations are allowed. The types are restricted to be either FML, VIEW, X_C_TYPE, or X_COMMON. No subtype can be specified for type FML, and subtypes are required for type VIEW, X_C_TYPE, and X_COMMON ("*" is not allowed). Note that subtype names should not contain semicolon, colon, comma, or asterisk characters. Duplicate type/subtype pairs cannot be specified for the same routing criteria name; more than one routing entry can have the same criteria name as long as the type/subtype pairs are unique. This parameter is required. If multiple buffer types are specified for a single routing entry, the data types of the routing field for each buffer type must be the same.

An example of a routing entry is:

BRNCH FIELD=B_FLD RANGES="0-2:DBG1,3-5:DBG2,6-9:DBG3" BUFTYPE="FML"

which sends buffers with field B_FLD values 0-2 to server group DBG1, values 3-5 to server group DBG2, and values 6-9 to DBG3; no other values are allowed.

If the field value is not set (for FML buffers), or does not match any specific range and a wildcard range has not been specified, an error is returned to the application.

Files

The TUXCONFIG and TUXOFFSET environment variables are used to find the TUXCONFIG configuration file on the MASTER machine.

Example

# The following configuration file defines a 2-site# configuration with two machine types. Data dependent# routing is used.*RESOURCESIPCKEY    80952  # key for well known addressDOMAINID   My_Domain_NameUID      4196  # user id for ipc structuresGID      601   # group id for ipc structuresPERM     0660  # permissions for ipc accessMAXSERVERS  20   # at most 20 simultaneous serversMAXSERVICES  40   # offering at most 40 servicesMAXGTT    20   # at most 20 simultaneous global transactionsMASTER    SITE1SCANUNIT   10SANITYSCAN  12BBLQUERY   180BLOCKTIME   30DBBLWAIT   6NOTIFY    DIPINOPTIONS    LAN,MIGRATESECURITY   USER_AUTHAUTHSVC    AUTHSVC 
 
 
 
     MP  # a multiprocessor based bulletin boardLDBAL     Y  # perform load balancing#*MACHINESmach1     LMID=SITE1 TUXDIR="/usr4/tuxbin"       MAXACCESSERS=25       APPDIR="/usr2/apps/bank"       ENVFILE="/usr2/apps/bank/ENVFILE"       TLOGDEVICE="/usr2/apps/bank/TLOG" TLOGNAME=TLOG       TUXCONFIG="/usr2/apps/bank/tuxconfig" TYPE="3B2"       ULOGPFX="/usr2/apps/bank/ULOG"       SPINCOUNT=5mach386    LMID=SITE2 TUXDIR="/usr5/tuxbin"       MAXACCESSERS=100       MAXWSCLIENTS=50       APPDIR="/usr4/apps/bank"       ENVFILE="/usr4/apps/bank/ENVFILE"       TLOGDEVICE="/usr4/apps/bank/TLOG" TLOGNAME=TLOG       TUXCONFIG="/usr4/apps/bank/tuxconfig" TYPE="386"       ULOGPFX="/usr4/apps/bank/ULOG"#*GROUPSDEFAULT:   TMSNAME=TMS_SQL  TMSCOUNT=2# For NT/NetWare, :bankdb: becomes ;bankdb;BANKB1    LMID=SITE1  GRPNO=1  OPENINFO="TUXEDO/SQL:/usr2/apps/bank/bankdl1:bankdb:readwrite"# For NT/NetWare, :bankdb: becomes ;bankdb;BANKB2    LMID=SITE2  GRPNO=2  OPENINFO="TUXEDO/SQL:/usr4/apps/bank/bankdl2:bankdb:readwrite"DEFAULT:AUTHGRP    LMID=SITE1  GRPNO=3#*NETWORKSITE1     NADDR="mach1.80952" BRIDGE="/dev/starlan"       NLSADDR="mach1.serve"#SITE2     NADDR="mach386.80952" BRIDGE="/dev/starlan"       NLSADDR="mach386.serve"*SERVERS#DEFAULT: RESTART=Y MAXGEN=5 REPLYQ=Y CLOPT="-A"TLR      SRVGRP=BANKB1  SRVID=1  RQADDR=tlr1       CLOPT="-A -- -T 100"TLR      SRVGRP=BANKB1  SRVID=2  RQADDR=tlr1       CLOPT="-A -- -T 200"TLR      SRVGRP=BANKB2  SRVID=3  RQADDR=tlr2       CLOPT="-A -- -T 600"TLR      SRVGRP=BANKB2  SRVID=4  RQADDR=tlr2       CLOPT="-A -- -T 700"XFER     SRVGRP=BANKB1  SRVID=5XFER     SRVGRP=BANKB2  SRVID=6ACCT     SRVGRP=BANKB1  SRVID=7ACCT     SRVGRP=BANKB2  SRVID=8BAL      SRVGRP=BANKB1  SRVID=9  BAL      SRVGRP=BANKB2  SRVID=10BTADD     SRVGRP=BANKB1  SRVID=11BTADD     SRVGRP=BANKB2  SRVID=12AUTHSVR    SRVGRP=AUTHGRP SRVID=20#*SERVICESDEFAULT:   LOAD=50     AUTOTRAN=NWITHDRAWAL  PRIO=50     ROUTING=ACCOUNT_IDDEPOSIT    PRIO=50     ROUTING=ACCOUNT_IDTRANSFER   PRIO=50     ROUTING=ACCOUNT_IDINQUIRY    PRIO=50     ROUTING=ACCOUNT_IDCLOSE_ACCT  PRIO=40     ROUTING=ACCOUNT_IDOPEN_ACCT   PRIO=40     ROUTING=BRANCH_IDBR_ADD    PRIO=20     ROUTING=BRANCH_IDTLR_ADD    PRIO=20     ROUTING=BRANCH_IDABAL     PRIO=30     ROUTING=b_idTBAL     PRIO=30     ROUTING=b_idABAL_BID   PRIO=30     ROUTING=b_idTBAL_BID   PRIO=30     ROUTING=b_id SVCTIMEOUT=300##*ROUTINGACCOUNT_ID  FIELD=ACCOUNT_ID  BUFTYPE="FML" RANGES="MIN - 9999:*,10000-59999:BANKB1,60000-109999:BANKB2,*:*"BRANCH_ID   FIELD=BRANCH_ID   BUFTYPE="FML" RANGES="MIN - 0:*,1-5:BANKB1,6-10:BANKB2,*:*"b_id     FIELD=b_id  BUFTYPE="VIEW:aud" RANGES="MIN - 0:*,1-5:BANKB1,6-10:BANKB2,*:*"

Interoperability

In an interoperating application, the master site must be the latest release available. Parameter values for PMID (machine ADDRESS), LMID, TLOGNAME, group names, RQADDR, service names, and ROUTING (routing criteria names) must be identifiers (valid C identifiers that are not UBBCONFIG keywords) when interoperating with BEA Tuxedo system.

Network Addresses

Suppose the local machine on which the bridge 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 bridge should accept requests is 2334. Assume that port number 2334 has been added to the network services database under the name bankapp-naddr. The address could be represented in the following ways:

//155.2.193.18:bankapp-naddr//155.2.193.18:2334
//backus.company.com:bankapp-naddr
//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.1 is translated into a hexadecimal number. Thus the 155 becomes 9B, 2 becomes 02 and so

See Also

buildserver(1), tmadmin(1), tmboot(1), tmshutdown(1), tmloadcf(1), tmunloadcf(1), tpinit(3c), buffer(3c), servopts(5), BEA Tuxedo Administrator's Guide, BEA Tuxedo Programmer's Guide, BEA WebLogic Enterprise Administration Guide

 

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.