UBBCONFIG(5)


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	e-docs.bea.com \| Site Map \| Search \| PDF Files \| Contact \| Glossary

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

UBBCONFIG(5)

Name

UBBCONFIG—Text version of a BEA Tuxedo configuration file

Description

When a BEA Tuxedo application is booted, the tmboot command refers to a binary configuration file called TUXCONFIG to get the information necessary for starting application servers and initializing the bulletin boards in an orderly sequence. This binary file cannot be created directly; it must be created from a text file called UBBCONFIG. To configure an application, an administrator creates a UBBCONFIG file (with a text editor) and loads the file into a binary version (TUXCONFIG) by running the tmloadcf(1) command. During the life of the application, the TUXCONFIG file is used by various BEA Tuxedo administrative tools. 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. For additional information pertaining to the entire UBBCONFIG file, see UBBCONFIG(5) Additional Information.

Definitions

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 the bulletin board for this BEA Tuxedo system configuration 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.

Configuration File Format

A UBBCONFIG file is made up of nine possible 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, SERVICES, INTERFACES, and ROUTING. The RESOURCES and MACHINES sections must be the first two sections and must be included in that order. The GROUPS section must precede the SERVERS, SERVICES, and ROUTING sections. The NETGROUPS section must precede the NETWORK section.

Parameters (except in the RESOURCES section) are generally specified by: KEYWORD = value; white space (space or tab character) is allowed on either side of the equal sign (=). This format sets KEYWORD to value. Valid keywords are described within each section.

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 (a string value already known to the BEA Tuxedo system such as APP_PW for the SECURITY parameter), standard C rules are typically used. A standard C identifier starts with an alphabetic character or underscore and contains only alphanumeric characters or underscores. The maximum allowable length of an identifier is 30 (not including the terminating NULL).

Note: There is no need to enclose an identifier in double quotes.

A value that is neither an integer number nor an identifier must be enclosed in double quotes. This value is a user-defined string. The maximum allowable length of a user-defined string is 78 characters (not including the terminating NULL). Exceptions to this rule are as follows:

The CLOPT, BUFTYPE, OPENINFO, and CLOSEINFO parameters, which can be 256 characters in length
The SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, and SEC_PRINCIPAL_PASSVAR parameters, which can be 511 characters in length (not including the terminating NULL)
The RANGES parameter, which can be 2048 characters in length (except in Domains, 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.

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

An identifier or a numeric constant must always be followed by white space (space or tab character), a newline character, 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.

RESOURCES Section

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 file 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_value

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 clients and servers that can be simultaneously connected to the bulletin board on any particular machine in this application. This value must be greater than 0 and less than 32,768. If not specified, the default maximum number is 50. The RESOURCES value for this parameter can be overridden in the MACHINES section on a per-machine basis.

System administration processes, such as the BBL, restartsrv, cleanupsrv, tmshutdown(), and tmadmin(), need not be accounted for in this value, but the DBBL, all bridge processes, all system-supplied and application server processes, and all potential client processes at a particular site need to be counted. (Examples of system-supplied servers are AUTHSVR, TMQUEUE, TMQFORWARD, TMUSREVT, TMSYSEVT, TMS—see TMSNAME parameter in GROUPS section, TMS_QM, GWTDOMAIN, and WSL.) If the application is booting workstation listeners (WSLs) at a particular site, both the WSLs and the number of potential workstation handlers (WSHs) that may be booted need to be counted.

Note that for BEA Tuxedo pre-release 7.1 (6.5 or earlier), both the MAXACCESSERS and MAXSERVERS parameters for an application play a part in the user license checking scheme. Specifically, a machine is not allowed to boot if the number of MAXACCESSERS for that machine + the number of MAXACCESSERS for the machine (or machines) already running in the application is greater than the number of MAXSERVERS + user licenses for the application. Thus, the total number of MAXACCESSERS for an application must be less than or equal to the number of MAXSERVERS + user licenses for the application.

Note also that the user license checking scheme in BEA Tuxedo release 7.1 or later considers only the following two factors when performing its checks: the number of user licenses for an application and the number of licenses currently in use for the application. When all user licenses are in use, no new clients are allowed to join the application.

MAXSERVERS numeric_value

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

All instances of system-supplied and application servers available to an application need to be accounted for in the bulletin board server table, which is a global table, meaning that the same server table resides on each machine in the application. Examples of system-supplied servers are AUTHSVR, TMQUEUE, TMQFORWARD, TMUSREVT, TMSYSEVT, TMS (see TMSNAME parameter in GROUPS section), TMS_QM, GWTDOMAIN, and WSL.

Administration of each BEA Tuxedo system site adds approximately one system-supplied server. Additionally, the DBBL process and all BBL, bridge, and WSH processes must be accounted for in the MAXSERVERS value.

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 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 16,384. If not specified, the default is 16,384.

MODEL {SHM | MP}

Specifies the configuration type. This parameter is required and only one of the two settings can be specified. SHM (for shared memory) 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 BEA Tuxedo system 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 {[LAN | MIGRATE | NO_XA | NO_AA],*}

Specifies options that are used. If two or more options are given, they are separated by commas. 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). The identifier NO_XA indicates that XA transactions are not allowed. The identifier NO_AA indicates that the auditing and authorization functions will not be called. This parameter is optional, and the default is no options.

SYSTEM_ACCESS {FASTPATH | PROTECTED}[,NO_OVERRIDE]

Specifies the default mode used by BEA Tuxedo system libraries within application processes to gain access to internal tables of the BEA Tuxedo system. FASTPATH specifies that the internal tables are accessible by BEA Tuxedo system libraries via unprotected 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 using flags available for use with tpinit(3c) or TPINITIALIZE(3cbl). If SYSTEM_ACCESS is not specified, the default mode is FASTPATH.

Limitation: Setting SYSTEM_ACCESS to PROTECTED may not be effective for multithreaded servers because it is possible that while one thread is executing BEA Tuxedo code, which means it is attached to the bulletin board, another thread might be executing user code. The BEA Tuxedo system cannot prevent such situations.

SECURITY {NONE | APP_PW | USER_AUTH | ACL | MANDATORY_ACL}

Specifies the type of application security to be enforced. If not specified, 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 default service name, if not specified, is ..AUTHSVC.

Note that the system-supplied authentication server, AUTHSVR, advertises the authentication service as AUTHSVC when SECURITY is set to USER_AUTH, and as ..AUTHSVC when SECURITY is set to ACL or MANDATORY_ACL. AUTHSVC and ..AUTHSVC point to the same authentication service.

Note also that string values AUTHSVC and ..AUTHSVC are identifiers, meaning that there is no need to surround AUTHSVC or ..AUTHSVC with double quotes.

MAXGTT numeric_value

Specifies the maximum number of simultaneous global transactions in which any particular machine in this application 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-machine basis.

MAXCONV numeric_value

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

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

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

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 native client processes is done by administrative system processes and not by application processes. Therefore, only native clients running with the same UNIX system user identifier as the application administrator can be notified using the SIGNAL method. Workstation clients may use the SIGNAL method, regardless of which user identifier they are running under.

Note: The SIGNAL notification method is not available for MS-DOS clients, and is not available for multithreaded or multicontexted clients.

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 BEA Tuxedo application association. 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.

SEC_PRINCIPAL_NAME string_value [0..511]

Specifies the security principal name identification string to be used for authentication purposes by an application running BEA Tuxedo 7.1 or later software. This parameter may contain a maximum of 511 characters (excluding the terminating NULL character). The principal name specified for this parameter becomes the identity of one or more system processes running in this application.

SEC_PRINCIPAL_NAME can be specified at any of the following four levels in the configuration hierarchy: RESOURCES section, MACHINES section, GROUPS section, and SERVERS section. A principal name at a particular configuration level can be overridden at a lower level. If SEC_PRINCIPAL_NAME is not specified at any of these levels, the principal name for the application defaults to the DOMAINID string specified in the RESOURCES section for this application.

Note that SEC_PRINCIPAL_NAME is one of a trio of parameters, the other two being SEC_PRINCIPAL_LOCATION and SEC_PRINCIPAL_PASSVAR. The latter two parameters pertain to opening decryption keys during application booting for the system processes running in a BEA Tuxedo 7.1 or later application. When only SEC_PRINCIPAL_NAME is specified at a particular level, the system sets each of the other two parameters to a NULL (zero length) string.

SEC_PRINCIPAL_LOCATION string_value [0..511]

Specifies the location of the file or device where the decryption (private) key for the principal specified in SEC_PRINCIPAL_NAME resides. This parameter may contain a maximum of 511 characters (excluding the terminating NULL character).

SEC_PRINCIPAL_LOCATION can be specified at any of the following four levels in the configuration hierarchy: RESOURCES section, MACHINES section, GROUPS section, and SERVERS section. When specified at any of these levels, this parameter must be paired with the SEC_PRINCIPAL_NAME parameter; otherwise, its value is ignored. (SEC_PRINCIPAL_PASSVAR is optional; if not specified, the system sets it to a NULL—zero length—string.)

SEC_PRINCIPAL_PASSVAR string_value [0..511]

Specifies the variable in which the password for the principal specified in SEC_PRINCIPAL_NAME is stored. This parameter may contain a maximum of 511 characters (excluding the terminating NULL character).

SEC_PRINCIPAL_PASSVAR can be specified at any of the following four levels in the configuration hierarchy: RESOURCES section, MACHINES section, GROUPS section, and SERVERS section. When specified at any of these levels, this parameter must be paired with the SEC_PRINCIPAL_NAME parameter; otherwise, its value is ignored. (SEC_PRINCIPAL_LOCATION is optional; if not specified, the system sets it to a NULL—zero length—string.)

During initialization, the administrator must provide the password for each of the decryption keys configured with SEC_PRINCIPAL_PASSVAR. (tmloadcf(1) prompts for the password.) The system automatically encrypts the password entered by the administrator and assigns each encrypted password to the associated password variable.

SIGNATURE_AHEAD numeric_value (1 <= num <= 2147483647)

Specifies the number of seconds into the future that a digital signature's timestamp is allowed to be, when compared to the local machine's clock. If not specified, the default is 3600 seconds (one hour). This parameter only applies to applications running BEA Tuxedo 7.1 or later software.

SIGNATURE_BEHIND numeric_value (1 <= num <= 2147483647)

Specifies the number of seconds into the past that a digital signature's timestamp is allowed to be, when compared to the local machine's clock. If not specified, the default is 604800 seconds (one week). This parameter only applies to applications running BEA Tuxedo 7.1 or later software.

SIGNATURE_REQUIRED {Y | N}

Specifies whether or not every process running in this application requires a digital signature on its input message buffer. If not specified, the default is N. This parameter only applies to applications running BEA Tuxedo 7.1 or later software.

SIGNATURE_REQUIRED can be specified at any of the following four levels in the configuration hierarchy: RESOURCES section, MACHINES section, GROUPS section, and SERVICES section. Setting SIGNATURE_REQUIRED to Y at a particular level means that signatures are required for all processes running at that level or below.

ENCRYPTION_REQUIRED {Y | N}

Specifies whether or not every process running in this application requires an encrypted input message buffer. If not specified, the default is N. This parameter only applies to applications running BEA Tuxedo 7.1 or later software.

ENCRYPTION_REQUIRED can be specified at any of the following four levels in the configuration hierarchy: RESOURCES section, MACHINES section, GROUPS section, and SERVICES section. Setting ENCRYPTION_REQUIRED to Y at a particular level means that encryption is required for all processes running at that level or below.

MACHINES Section

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. On a Windows system, the value can be set using the Computer Name value in the Network Control Panel and must be specified in upper case. 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.

These 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 filesystem 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.

Note: The pathname specified for this parameter must match exactly (inlcuding case) the pathname specified for the TUXCONFIG environment variable. Otherwise, tmloadcf(1) cannot be run successfully.

TUXDIR = string_value

This is the absolute pathname of the directory where the BEA Tuxedo 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 filesystem. If the machines of a multiprocessor application have different BEA Tuxedo system releases installed, check 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.

Optional parameters are:

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 clients and servers that can be simultaneously connected to the bulletin board on this machine. This value must be greater than 0 and less than 32,768. If not specified, the default is the MAXACCESSERS value specified in the RESOURCES section.

System administration processes, such as the BBL, restartsrv, cleanupsrv, tmshutdown(), and tmadmin(), need not be accounted for in this value, but the DBBL, all bridge processes, all system-supplied and application server processes, and all potential client processes at this site need to be counted. (Examples of system-supplied servers are AUTHSVR, TMQUEUE, TMQFORWARD, TMUSREVT, TMSYSEVT, TMS—see TMSNAME parameter in GROUPS section, TMS_QM, GWTDOMAIN, and WSL.) If the application is booting workstation listeners (WSLs) at this site, both the WSLs and the number of potential workstation handlers (WSHs) that may be booted need to be counted.

Note that for BEA Tuxedo pre-release 7.1 (6.5 or earlier), both the MAXACCESSERS and MAXSERVERS (see MAXSERVERS in RESOURCES section) parameters for an application play a part in the user license checking scheme. Specifically, a machine is not allowed to boot if the number of MAXACCESSERS for that machine + the number of MAXACCESSERS for the machine (or machines) already running in the application is greater than the number of MAXSERVERS + user licenses for the application. Thus, the total number of MAXACCESSERS for an application must be less than or equal to the number of MAXSERVERS + user licenses for the application.

MAXWSCLIENTS = number

Specifies the number of accesser entries on this machine to be reserved for Workstation clients (as opposed to native clients). If specified, the value must be greater than or equal to 0 and less than 32,768. If not specified, the default is 0.

The number specified here takes a portion of the total accesser slots specified with MAXACCESSERS, meaning that the accesser slots reserved for MAXWSCLIENTS are unavailable for use by other clients and servers on this machine. It is an error to set this number greater than MAXACCESSERS.

The MAXWSCLIENTS parameter is only used when the BEA Tuxedo system Workstation feature is used. The appropriate setting of this parameter helps to conserve interprocess communication (IPC) resources since Workstation client access to the system is multiplexed through a BEA Tuxedo system-supplied surrogate, the workstation handler (WSH).

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 32,000. The default is 100.

MAXCONV = number

Specifies the maximum number of simultaneous conversations in which clients and servers on this machine can be involved. It must be greater than 0 and less than 32,768. If not specified, the default is the MAXCONV 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 this 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 filesystem 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 filesystem 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 filesystem. 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 filesystem that contains the TUXCONFIG file 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.

SEC_PRINCIPAL_NAME = string_value [0..511]

SEC_PRINCIPAL_LOCATION = string_value [0..511]

SEC_PRINCIPAL_PASSVAR = string_value [0..511]

SIGNATURE_REQUIRED = {Y | N}

Specifies whether or not every process running on this machine requires a digital signature on its input message buffer. If not specified, the default is N. This parameter only applies to applications running BEA Tuxedo 7.1 or later software.

ENCRYPTION_REQUIRED = {Y | N}

Specifies whether or not every process running on this machine requires an encrypted input message buffer. If not specified, the default is N. This parameter only applies to applications running BEA Tuxedo 7.1 or later software.

SICACHEENTRIESMAX = string_value

represents the maximum number of service cache entries any process is to hold on this machine. It must be greater than or equal to 0 and less than 32,768. If a value is not specified, the default value is 500. If the value is set to 0, no service caching will be performed by any process on this machine. The maximum value this attribute can take is 32,767. All clients on this machine will use this value.

Note: Unlike the corresponding attribute in the SERVERS section, this parameter cannot take the string DEFAULT as a valid value.

GROUPS Section

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, wtmconfig(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 30000, 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(), and ended with tpcommit()/ tpabort()). 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.

SEC_PRINCIPAL_NAME = string_value [0..511]

SEC_PRINCIPAL_LOCATION = string_value [0..511]

SEC_PRINCIPAL_PASSVAR = string_value [0..511]

SIGNATURE_REQUIRED = {Y | N}

Specifies whether or not every process running in this group requires a digital signature on its input message buffer. If not specified, the default is N. This parameter only applies to applications running BEA Tuxedo 7.1 or later software.

ENCRYPTION_REQUIRED = {Y | N}

Specifies whether or not every process running in this group requires an encrypted input message buffer. If not specified, the default is N. This parameter only applies to applications running BEA Tuxedo 7.1 or later software.

OPENINFO = string_value

Specifies the resource manager dependent information needed when opening the resource manager for this group. 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 the TMSNAME parameter for this group is not set or is set to TMS. If the TMSNAME parameter is set to a value other than TMS but the OPENINFO string is set to the NULL string ("") or is not specified, a resource manager exists for the group but does not require any information for executing an open operation.

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 the published name of the vendor's transaction (XA) interface followed immediately by a colon (:).

For BEA Tuxedo /Q databases, the format is:

# On UNIX #
OPENINFO = "TUXEDO/QM:qmconfig:qspace"

# On Windows #
OPENINFO = "TUXEDO/QM:qmconfig;qspace"

# In AS/400 environment #
OPENINFO = "TUXEDO/QM:qmconfig;qspace"

# In OpenVMS environment #
OPENINFO = "TUXEDO/QM,[a.b.c]qmconfig,qspace"

where TUXEDO/QM is the published name of the BEA Tuxedo /Q XA interface, qmconfig is replaced with the name of the QMCONFIG (see qmadmin(1)) on which the queue space resides, and qspace is replaced with the name of the queue space. For Windows and AS/400, the separator after qmconfig must be a semicolon (;). For OpenVMS, the separator after <