Skip navigation.

Setting Up a Tuxedo Application

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

Creating the Configuration File

This topic includes the following sections:

 


How to Create a Configuration File

Configuration file requirements are determined by the needs of your application. Following are instructions for several types of configurations:

See Also

 


How to Create the Configuration File for a Single-machine Application

For a single-machine configuration, you need to create the following sections of the configuration file. Click on each task for instructions on completing that task.

You can also click on any area of the following diagram to learn how to create the section named in that area.

Example of a Network Grouping


 

 


How to Create the Configuration File for a Multiple-machine (Distributed) Application

For a distributed ATMI application, you need to create the following sections of the configuration file. Click any of the following tasks for instructions on completing that task.

Note: For detailed information about creating a configuration file for a distributed CORBA application in the BEA Tuxedo system, refer to the Scaling, Distributing, and Tuning CORBA Applications guide.

You can also click on any area of the following diagram to learn how to create the section named in that area.

Example of a Network Grouping


 

 


How to Create the Configuration File for a Multiple-domain Application

For a multiple-domain configuration, you need to create two configuration files for each participating domain:

For an application that consists of two domains (for example, lapp and rapp for local and remote domains, respectively), the following tasks are required.

Click on each task for instructions on completing that task.

Figure 3-1 Configuration Tasks for a Sample Multiple-domain Application

Configuration Tasks for a Sample Multiple-domain Application


 

The following diagram shows which sections of the UBBCONFIG and DMCONFIG files you need to configure for a two-domain application. One domain represents the local domain; the other, the remote domain.

Click on any area of the following diagram for instructions on creating that section of the configuration file.

Figure 3-2 Configuring a Multiple-domain Application

Configuring a Multiple-domain Application


 

See Also

 


How to Create the RESOURCES Section of the Configuration File

The first section of every configuration file must be the RESOURCES section. The parameters defined in this section control the application as a whole and serve as system-wide defaults. The values of RESOURCES parameters can be overridden, however, on a per-machine basis by assigning other values in the MACHINES section.

For each parameter in the RESOURCES section, the following table provides a description and links to reference pages and additional information.

To Specify This Information in the RESOURCES Section

Set This Parameter (Required/Optional)

For More Information, Click the Following

Unique address of interprocess communication (IPC) resources

IPCKEY (Required)

Shared memory address

Security access

UID, GID, and PERM (Optional)

Security access

Maximum number of processes that can be simultaneously connected to a bulletin board

MAXACCESSERS (Optional)

IPC limits

Maximum number of server table entries in a bulletin board

MAXSERVERS (Optional)

IPC limits

Maximum number of service table entries in a bulletin board

MAXSERVICES (Optional)

IPC limits

Maximum number of CORBA interfaces

MAXINTERFACES (Optional)

IPC limits

Maximum number of CORBA objects

MAXOBJECTS (Optional)

IPC limits

Distinguished Bulletin Board Liaison (DBBL) location at which booting, shutdown, and other administrative tasks are performed

MASTER (Required)

Master processor

Bulletin board architecture

MODEL, SHM or MP, and LAN or MIGRATE options (Required)

Application type

Security level

SECURITY, AUTHSVC (Optional)

Security levels

Principal name of the process used for identification, location of private key of principal user, and the environment variable containing the password

SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, and SEC_PRINCIPAL_PASSVAR

Security attributes

Default method for clients to detect unsolicited messages

NOTIFY, USIGNAL (Optional)

Unsolicited notification

Protecting shared memory

SYSTEM_ACCESS (Optional)

Shared memory protection

Whether server load balancing is enabled

LDBAL (Optional)

Load balancing

Maximum number of buffer types and subtypes

MAXBUFTYPE, MAXBUFSTYPES (Optional)

Buffer types/subtypes

Maximum number of conversations allowed on a machine

MAXCONV (Optional)

Conversation limits

Maximum number of network groups

MAXNETGROUPS (Optional)

Network groups

Sanity check frequency and amount of time allowed for blocking calls

SCANUNIT, SANITYSCAN, BLOCKTIME (Optional)

Sanity check frequency and blocking timeouts


 

Sample RESOURCES Section

The following is a sample RESOURCES section of a configuration file.

*RESOURCES
IPCKEY 39211
UID 0
GID 1
PERM 0660
MAXACCESSERS 75
MAXSERVERS 40
MAXSERVICES 55
MASTER SITE1, SITE2
MODEL MP
OPTIONS LAN, MIGRATE
SECURITY APP_PW
AUTHSVC "AUTHSVC"
NOTIFY DIPIN
SYSTEM_ACCESS PROTECTED, NO_OVERRIDE
LDBAL Y

See Also

 


Defining the Application Type

Among the architectural decisions needed for a BEA Tuxedo application are the following:

Use the MODEL and OPTIONS parameters to define the application type.

The MODEL parameter specifies whether an application runs on a single processor. It is set to SHM for uniprocessors and also for multiprocessors with global shared memory. A MODEL value of MP is used for multiprocessors that do not have global shared memory, as well as for networked applications. This is a required parameter.

The OPTIONS parameter is a comma-separated list of application configuration options. Two available options are LAN (indicating a networked configuration) and MIGRATE (indicating that application server migration is allowed).

Characteristics of the MODEL and OPTIONS Parameters


 

Parameter

Characteristics

MODEL

It is a required parameter. A value of SHM indicates a single machine with global shared memory. A value of MP indicates either multiple machines without global shared memory, or a networked application.

OPTIONS

It is a comma-separated list of application configuration options. A value of LAN indicates a local area network. A value of MIGRATE enables server migration.

In the sample RESOURCES section, MODEL is set to MP; OPTIONS is set to LAN and MIGRATE.


 

Example Settings

The following is a sample setting in the RESOURCES section of a configuration file.

 *RESOURCES
MODEL MP
OPTIONS LAN, MIGRATE

 


Controlling the Number of Buffer Types and Subtypes

You can control the number of buffer types and subtypes allowed in the application with the MAXBUFTYPE and MAXBUFSTYPE parameters, respectively. Unless you are creating many user-defined buffer types, you can omit MAXBUFTYPE. If you intend to use many different VIEW types, you may want to set MAXBUFSTYPE to a value higher than its current default.

Characteristics of the MAXBUFTYPE and MAXBUFSTYPES Parameters

Parameter

Characteristics

MAXBUFTYPE

Maximum number of buffer types allowed in the system. Use only if you create 8 or more user-defined buffer types. The value of MAXBUFTYPE must be greater than 0 and less than 32,768. If not specified, the default is 16.

Example: MAXBUFTYPE 20

MAXBUFSTYPE

Maximum number of buffer subtypes allowed in the system. The value of MAXBUFSTYPE must be greater than 0 and less than 32,768. If not specified, the default is 32.

Example: MAXBUFSTYPE 40

l


 

Example Settings

In this example, the maximum number of buffer types is 20; the maximum number of subtypes is 40.

*RESOURCES
MAXBUFTYPE 20
MAXBUFSTYPE 40

 


Controlling the Number of Conversations

You can specify the maximum number of simultaneous conversations on a machine with the MAXCONV parameter. The value of MAXCONV must be greater than 0 and less than 32,768.

Characteristics of the MAXCONV Parameter

The MAXCONV parameter has the following characteristics:

Example Setting

In this example, the maximum number of simultaneous conversations allowed on each machine is 15.

*RESOURCES
MAXCONV 15

 


Defining IPC Limits

Because most interprocess communication (IPC) and shared memory bulletin board tables are statically allocated for speedy processing, it is important to tune them correctly. If they are sized too generously, memory and IPC resources are wasted; if too small, processes fail when the limits are exceeded. You can use the tmloadcf -c command to find out the maximum IPC resources required by a specific application. (See tmloadcf(1) in the BEA Tuxedo Command Reference.)

MAXACCESSERS, MAXSERVERS, MAXSERVICES, MAXINTERFACES, and MAXOBJECTS are the tunable parameters that control IPC sizing. The amount of shared memory allocated in an application is controlled by the MAXGTT and MAXCONV parameters.

Characteristics of MAXACCESSERS, MAXSERVERS, MAXSERVICES, MAXINTERFACES, and MAXOBJECTS Parameters

Parameter

Characteristics

MAXACCESSERS

Maximum number of overall processes that can be simultaneously connected to the bulletin board at any particular site in the BEA Tuxedo application. This number includes all clients and system-supplied and application servers, but does not include administrative processes such as the Bulletin Board Liaison (BBL) and tmadmin(), which have reserved access slots to the bulletin board.

The value of MAXACCESSERS must be greater than 0 and less than 32,768. If not specified, the default is 50. You can overwrite MAXACCESSERS, on a per-machine basis, in the MACHINES section.

MAXSERVERS

Maximum number of server processes available to the application. This number includes all system-supplied and application servers.

The value of MAXSERVERS must be greater than 0 and less than 8,192. If not specified, the default is 50.

MAXSERVICES

Maximum number of different BEA Tuxedo services that can be advertised in the application. The value of MAXSERVICES must be greater than 0 and less than 32,768. If not specified, the default is 100.

Note: For CORBA environments, each CORBA interface is mapped to a BEA Tuxedo service. Make sure you account for the number of services generated.

MAXINTERFACES

For CORBA environments, the maximum number of CORBA interfaces that can be advertised in the application. The value of MAXINTERFACES must be greater than 0 and less than 32,766. If not specified, the default is 100.

Note: All instances of an interface occupy and reuse the same slot in the interface table in the bulletin board. For example, if server SVR1 advertises interfaces IF1 and IF2, server SVR2 advertises interfaces IF2 and IF3, and server SVR3 advertises interfaces IF3 and IF4, the interface count is 4 (not 6) when calculating MAXINTERFACES.

MAXOBJECTS

For CORBA environments, the maximum number of active CORBA objects in the application. The value of MAXOBJECTS must be greater than 0 and less than 32,766. If not specified, the default is 100.


 

Note: Examples of system-supplied servers are AUTHSVR, TMQUEUE, TMQFORWARD, TMUSREVT, TMSYSEVT, TMS, TMS_QM, GWTDOMAIN, and WSL.

The cost incurred by increasing MAXACCESSERS is one additional semaphore per site per client or server process (accesser—see note that follows). There is a small fixed semaphore overhead for system processes in addition to that added by the MAXACCESSERS value. The cost of increasing MAXSERVERS and MAXSERVICES is a small amount of shared memory that is kept for each server, service, and client entry, respectively. The general idea for these parameters is to allow for future growth of the application. It is more important to scrutinize MAXACCESSERS.

Note: The system allocates one semaphore for each access slot to the bulletin board. A semaphore is a latch circuit that prevents more than one process from accessing the same shared memory in the bulletin board at the same time.

For BEA Tuxedo releases prior to release 7.1, 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.

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.

Example Settings

In this example, at most 75 processes (clients and servers) can access the system at any one time. There is room for 40 servers advertising 55 services in the bulletin board.

*RESOURCES
MAXACCESSERS 75
MAXSERVERS 40
MAXSERVICES 55

 


Enabling Load Balancing

You can control whether a load balancing algorithm is used on the BEA Tuxedo application as a whole. When load balancing is used, a load factor is applied to each service within the system, allowing you to track the total load on every server. Every service request is sent to the qualified server that is least loaded.

To specify whether load balancing should be used, set the LDBAL parameter to Y (Yes) or N (No). By default, it is set to N.

You should use load balancing only if necessary; that is, whenever a service is offered by servers that use more than one queue. Load balancing is not appropriate for services offered by only one server, or by servers in an MSSQ (Multiple Server, Single Queue) set. If you have only these types of services in your configuration, set the LDBAL parameter to N. If LDBAL is set to N and multiple queues offer the same service, the first available queue is selected.

Characteristics of the LDBAL Parameter

The LDBAL parameter has the following characteristics:

Example Settings

In this example, load balancing is enabled for the application.

*RESOURCES
LDBAL Y

See Also

 


Identifying the Master Machine

The MASTER machine controls the booting and administration of the entire application. You must specify a MASTER machine for every application by setting the MASTER parameter. The value of MASTER is the Logical Machine Identifier (LMID) for the appropriate computer. The LMID, in turn, is defined as an alphanumeric string, chosen by the administrator, that is assigned to the LMID parameter in the MACHINES section. Therefore, for example, if the value of the LMID parameter is SITE1, then the value of MASTER must also be SITE1.

If you want to be able to bring down the MASTER machine without shutting down the application, you must be able to migrate the MASTER. To enable migration, you must specify two values for LMID: the primary MASTER and the backup MASTER.

Characteristics of the MASTER Parameter

The MASTER parameter has the following characteristics:

Example Settings

Site1 is the MASTER machine; SITE2 is the backup machine.

*RESOURCES
MASTER SITE1, SITE2

 


Specifying the Maximum Number of Network Groups

To specify the maximum number of configured network groups, set the MAXNETGROUPS parameter. The value must be greater than or equal to 1 and less than 8192. The default is 8. This parameter is optional.

 


Specifying the Number of Sanity Checks and Blocking Timeouts

Periodically (every 120 seconds, by default) the Bulletin Board Liaison (BBL) checks the sanity of the servers on its machine. You can change the frequency of these checks, however, by setting the SCANUNIT and SANITYSCAN parameters.

Use the SANITYSCAN parameter to specify how many SCANUNITs elapse between sanity checks of the servers. Its current default is set so that SANITYSCAN * SCANUNIT is approximately 120 seconds.

In addition, you can specify the number of timeout periods for blocking messages, transactions, and other system activities by setting the BLOCKTIME parameter.

Note: Nontransactional blocking time values can be set on a per service, per ATMI call, and per context basis. These blocktime values override the system-wide default BLOCKTIME values set in the RESOURCES section of the UBBCONFIG file. For further information see Specifying Nontransactional Service-Level Blocktime.

Characteristics of the SCANUNIT, SANITYSCAN, and BLOCKTIME Parameters

Parameter

Characteristics

SCANUNIT

Controls the granularity of check intervals and timeouts. SCANUNIT must be a multiple of 2 or 5 between 0 and 60 seconds.
Example: SCANUNIT 10

The default is 10.

SANITYSCAN

Specifies how many scan units elapse between sanity checks of the servers.

SANITYSCAN may be any number up to 32,767.

The default is such that SCANUNIT * SANITYSCAN is approximately 120 seconds.

BLOCKTIME

Controls how long a message can block before it times out.

SCANUNIT * BLOCKTIME must not exceed 32,767.

The default is such that SCANUNIT * BLOCKTIME is approximately 60 seconds.


 

Timeouts for Blocking ATMI Operations

The term timeout is used to refer, collectively, to the amount of time that elapses while a client:

The term blocking timeout refers to the amount of time spent by a client request waiting for a blocking condition to clear up. Block timeouts for asynchronous service requests and conversations apply to individual send and receive operations. When a process sends a message using tpacall (3c), tpconnect (3c), or tpsend (3c), the timeout applies only to the period during which the request waits to get on the queue if the queue is full. When a client process issues a tpgetrply (3c) or tprecv(3c) call to receive a message, the timeout specifies how long the client may wait for the incoming message if its queue is empty.

Example Settings

In this example, sanity scans are performed every 30 seconds and requests block for no more than 10 seconds. A SCANUNIT of 10 and a SANITYSCAN of 3 allow 3 blocks of 10 seconds or 30 seconds to elapse before the BBL scans.

*RESOURCES
SCANUNIT 10
SANITYSCAN 3
BLOCKTIME 1

 


Establishing Operating System-level Security

You can restrict access to BEA Tuxedo administrative functions to authorized administrators only, by setting three parameters: UID, GID, and PERM.

The defaults of UID and GID are the user ID and group ID, respectively, of the person who runs the tmloadcf(1) command on the configuration, unless overriding values have been specified in the MACHINES section.

Characteristics of the UID, GID, and PERM Parameters


 


 


 


 


 


 


 

Parameter

Characteristics

UID

The user ID of the administrator. The value is a numeric string corresponding to the UNIX system user ID of the person who boots and shuts down the system.

The default is the user ID of the person who runs tmloadcf(1).

Example: UID=3002

Note: On Windows, this value must be set to 0.

GID

The numeric group ID of the administrator.

The default is the group ID of the person who runs tmloadcf(1).

Example: GID=100

Note: On Windows, this value must be set to 0.

PERM

The value is an octal number that specifies permissions for the IPC resources created when the application is booted. This parameter provides the first level of defense of the BEA Tuxedo system IPC structures against unauthorized access. These values should be specified for production applications.

The default is 0666, which gives read/write access to all.

Example: PERM=0660


 

Note: You can overwrite the values assigned to these parameters for remote machines. The user and group IDs on a remote machine are not required to be the same as the user and group IDs on the MASTER machine. You can override the defaults by specifying different user and group IDs in the MACHINES section of the configuration file. If not specified, values specified in the RESOURCES section are used.

 


Specifying the Security Level

You can set the following three levels of security:

Characteristics of the SECURITY and AUTHSVC Parameters

Parameter

Characteristics

SECURITY

Security level that requires a password to join an application. Accepted values are: NONE (default), APP_PW, USER_AUTH—>ACL, and MANDATORY_ACL.

To enable the LDAP single security administration the SECURITY level must be set to USER_AUTH, MANDATORY_ACL, or ACL.

Default is NONE.

Example: SECURITY APP_PW

AUTHSVC

The name of the authentication service.

SECURITY APP_PW or higher must be specified.

Default is no authentication service.

Client authentication with Kerberos is possible.

Example: AUTHSVC "AUTHSVC''


 

See Also

 


Defining the Security Attributes of a Server

You can use the SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, and SEC_PRINCIPAL_PASSVAR parameters to identify the security attributes of any servers used for authentication.

Note: These policies apply to the Workstation handler, Domains gateway processes, and interoperating application servers.

See Also

 


Protecting Shared Memory

You can shield system tables kept in shared memory from application clients and/or servers using the SYSTEM_ACCESS parameter. This parameter is useful when applications are being developed because faulty application code can inadvertently corrupt shared memory with a bad pointer. Once an application is fully debugged and tested, the value of this parameter can be changed to allow for faster responses. Following are valid values for this parameter:

Once you select a value, you can specify NO_OVERRIDE, which means that the selected option cannot be changed either by the client, in the TPINIT structure of the tpinit() call, or by the administrator, in the SERVERS section for servers.

Characteristics of the PROTECTED, FASTPATH, and NO_OVERRIDE Parameters

Parameter

Characteristics

PROTECTED

Internal structures in shared memory are not corrupted inadvertently by application processes.

FASTPATH (Default)

Application processes join the application with access to shared memory at all times.

NO_OVERRIDDE

The specified option (either PROTECTED or FASTPATH) cannot be changed.


 

Example Settings

 SYSTEM_ACCESS PROTECTED, NO_OVERRIDE

 


Setting the Address of the System Resources for an Application

To set the address of shared memory, set the IPCKEY parameter. This parameter is used by the BEA Tuxedo system to allocate application IPC resources such that they may be located easily by new processes joining the application. This key and its variations are used internally to allocate the bulletin board, message queues, and semaphores that must be available to new application processes. In single processor mode, this key names the bulletin board; in multiprocessor mode, this key names the message queue of the DBBL.

Characteristics of the IPCKEY Parameter

The IPCKEY parameter has the following characteristics:

Example Settings

*RESOURCES
IPCKEY 39211

 


Specifying How Clients Receive Unsolicited Notification

You can select the default method by which clients receive unsolicited messages by setting the NOTIFY parameter. The client, however, can override this choice when calling tpinit().

Following are four possible methods:

The USIGNAL parameter specifies the signal to be used if SIGNAL-based notification is used. Two types of signals can be generated: SIGUSR1 and SIGUSR2. The default is SIGUSR2. This method has the advantage of immediate notification, but is limited when you are running a native client. In that case, you must have the same user ID as the sending process. Workstation clients do not have this limitation.

Note: This method is not available on all platforms.

Characteristics of the NOTIFY and USIGNAL Parameters

Parameter

Characteristics

NOTIFY

Value of IGNORE means clients should ignore unsolicited messages.

Value of DIPIN means clients should receive unsolicited messages only when they call tpchkunsol() or when they make an ATMI call.

Value of SIGNAL means clients should receive unsolicited messages by signals.

Default is DIPIN

Example: NOTIFY SIGNAL

USIGNAL

Value of SIGUSR1 and SIGUSR2 means notify clients with this type of signal.

Default is SIGUSR2

Example: USIGNAL SIGUSR1


 

 


How to Create the MACHINES Section of the Configuration File

The second section of every configuration file must be the MACHINES section. The MACHINES section defines parameters for each machine in an application. These parameters provide the following information:

Note: For a particular machine, you can override the following system-wide parameters: UID, GID, PERM, MAXACCESSERS, MAXOBJECTS, MAXCONV, and MAXGTT. Each parameter, except MAXGTT, is described in the RESOURCES section.

For each parameter in the MACHINES section, the following table provides a description and links to reference pages and additional information.

To Specify This Information in the MACHINES Section

Set This Parameter (Required/Optional)

For More Information, Click the Following

The number of entries in the cache used for ACL entries when SECURITY is set to ACL or MANDATORY_ACL.

MAXACLCACHE (Optional)

ACL entries in the cache

The additional load to be added when computing the cost of sending a service request from this machine to another machine.

NETLOAD (Optional)

Additional loads

The address is the name of the physical processor, which all other entries describe. The LMID parameter specifies the logical name of the computer.

LMID (Required)

Address and machine ID

The number of attempts that should be made at user level to lock the bulletin board before blocking processes on a UNIX semaphore.

SPINCOUNT (Optional)

Bulletin board locking limit

A value used for grouping machines into classes.

TYPE (Optional)

Class grouping value

The absolute pathname of the file or device where the binary TUXCONFIG file is found on this machine.

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

TUXCONFIG (Required)

Configuration file location

The maximum number of simultaneous conversations in which processes on a particular machine can be involved.

MAXCONV (Optional)

Conversation limits

The numeric size, in pages, of the DTP transaction log for this machine.

TLOGSIZE (Optional)

DTP TLOG size

The name of the DTP transaction log for this machine.

TLOGNAME (Optional)

DTP transaction log name

A value that specifies that all clients and servers on the machine are to be executed with the environment specified in the named file.

ENVFILE (Optional)

Environment variable settings

The BEA Tuxedo filesystem that contains the DTP transaction log (TLOG) for this machine.

TLOGDEVICE (Optional)

Filesystem containing the TLOG

The maximum number of processes that can have access to the bulletin board on this processor at any one time.

MAXACCESSERS (Optional)

IPC limits

For CORBA environments, the maximum number of CORBA objects that can be accommodated in the Active Object Table on this processor at any one time.

MAXOBJECTS (Optional)

IPC limits

The maximum number of simultaneous global transactions in which a particular machine can be involved.

MAXGTT (Optional)

Limit of simultaneous global transactions

The number of accesser entries on this processor to be reserved for Workstation clients. The parameter is only used when the BEA Tuxedo system Workstation component is used.

MAXWSCLIENTS (Optional)

Limit of workstation accesser entries

A limit for the amount of space that can be allocated for messages waiting to be transmitted by the bridge process.

MAXPENDINGBYTES (Optional)

Message space limits

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.

TLOGOFFSET (Optional)

Numeric offset containing the DTP TLOG

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.

TUXOFFSET (Optional)

Numeric offset containing the TUXCONFIG

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.

GID (Optional)

Security access

The numeric permissions associated with the IPC structures that implement the bulletin board. This parameter 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.

PERM (Optional)

Security access

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.

UID (Optional)

Security access

Principal name of the process used for identification, location of private key of principal user, and the environment variable containing the password

SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, SEC_PRINCIPAL_PASSVAR

Security attributes

The absolute pathname of the application directory (APPDIR), which is the current directory for all application and administrative servers booted on this machine; and the absolute pathname of the directory where the BEA Tuxedo system software is found on this machine.

TUXDIR (Required)

System and application software locations

The threshold message size for messages—bound to remote processes (string_value1) and local processes (string_value2), respectively—on which automatic data compression will be performed.

CMPLIMIT (Optional)

Threshold message size

The full pathname to be used as the prefix of the name of the userlog(3c) message file on this machine.

ULOGPFX (Optional)

ULOG pathname


 

Sample MACHINES Section

Following is a sample MACHINES section of a configuration file in an ATMI environment.

*MACHINES
gumby LMID=SITE1
TUXDIR="/tuxdir"
APPDIR="/home/apps/mortgage"
TUXCONFIG="/home/apps/mortgage/tuxconfig"
ENVFILE="/home/apps/mortgage/ENVFILE"
ULOGPFX="/home/apps/mortgage/logs/ULOG"
MAXACCESSERS=100
MAXCONV=15

Following is a sample MACHINES section of a configuration file in a CORBA environment.

*MACHINES
gumby LMID=SITE1
TUXDIR="/tuxdir"
APPDIR="/home/apps/mortgage"
TUXCONFIG="/home/apps/mortgage/tuxconfig"
ENVFILE="/home/apps/mortgage/ENVFILE"
MAXOBJECTS=700
ULOGPFX="/home/apps/mortgage/logs/ULOG"
MAXACCESSERS=100

Sample MACHINES Parameters

In the preceding sample MACHINES section, the following parameters and values are specified.

Parameter

Meaning

gumby

The machine name obtained with the command uname -n on UNIX systems. On a Windows system, the value can be set using the Computer Name value in the Network Control Panel and must be specified in uppercase.

LMID=SITE1

The logical machine identifier of the machine gumby.

TUXDIR

The full path to the installed BEA Tuxedo software (shown in double quotation marks).

APPDIR

The full path to the application directory (shown in double quotation marks).

TUXCONFIG

The full pathname of the configuration file (shown in double quotation marks).

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

ENVFILE

The full pathname of a file containing environment information (shown in double quotation marks).

ULOGPFX

The full pathname to be used as the prefix of the name of the log file (shown in double quotation marks).

MAXACCESSERS

For this machine, override the system-wide value (defined in the RESOURCES section) with 100.

MAXOBJECTS

(For the CORBA example.) For this machine, override the system-wide value (defined in the RESOURCES section) with 700.

MAXCONV

For this machine, override the system-wide value (defined in the RESOURCES section) with 15.


 

How to Customize the Sample MACHINES Section

You can customize the MACHINES section by indicating the following:

Note: On a Windows system, the machine name must be specified in UPPERCASE.

See Also

 


Specifying the Maximum Number of ACL Entries in the Cache

You can use the MAXACLCACHE parameter to specify the number of ACL entries in the cache when SECURITY is set to ACL or MANDATORY_ACL. By setting of this parameter to an appropriate value, you can:

The value must be a number greater than or equal to 10, and less than or equal to 30,000. The default is 100.

 


Defining an Additional Service Request Load

You can use the NETLOAD parameter to specify a load to be added when computing the cost of sending a service request from one machine to another. The value must be a number greater than or equal to 0, and less than 32,768. The default is 0.

See Also

 


Reserving the Physical Address and Machine ID

You initially define the address of your MASTER machine in the address portion, which is the basis for a MACHINES section entry. All other parameters in the entry describe the machine specified by this address. You must set the address to the value printed by calling uname -n on UNIX systems. On Windows systems, see the Computer Name value in the Network Identification dialog from the Network Control Panel.

The LMID parameter is mandatory. It specifies a logical name used to designate the computer for which an address has just been provided. It may be any alphanumeric value, but it must be unique among other machines in the application.

Characteristics of the Address and the LMID Parameter

The address and machine ID have the following characteristics:

 


Setting the Number of Lock Spins

For some BEA Tuxedo system operations (such as service name lookups and transactions), the bulletin board must be locked for exclusive access: that is, it must be accessible by only one process. If a process or thread finds that the bulletin board is locked by another process or thread, it retries, or spins on the lock for SPINCOUNT number of times before giving up and going to sleep on a waiting queue. Because sleeping is a costly operation, it is efficient to do some amount of spinning before sleeping.

Characteristics of the SPINCOUNT Parameter

Though the value of the SPINCOUNT parameter is application- and system-dependent, it may be helpful to keep the following basic guidelines in mind:

 


Specifying Machines as Types

You can use the TYPE parameter to group machines into classes. You can set TYPE to any string that contains 15 or fewer characters.

Characteristics of the TYPE Parameter

 


Identifying the Location of the Configuration File

To identify the configuration file location and filename for an entry that identifies a machine, set TUXCONFIG, a required parameter. The value of the TUXCONFIG parameter is enclosed in double quotes and represents a full pathname, which may contain up to 64 characters.

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

Characteristics of the TUXCONFIG Parameter

The TUXCONFIG parameter has the following characteristics:

 


Indicating the Size of the DTP Transaction Log

Use the TLOGSIZE parameter to indicate the size, in pages, of the DTP transaction log for this machine. The value must be a number greater than 0, and less than or equal to 2048, subject to the amount of space available on the operating system filesystem. The default is 100 pages.

 


Defining the DTP Transaction Log Name

Use the TLOGNAME parameter to define the name of the DTP transaction log for this machine. The default is TLOG. If more than one TLOG exists on the same TLOGDEVICE, each must have a unique name. The value of TLOGNAME must be different from the name of any other table in the VTOC (Volume Table of Contents) on the TLOGDEVICE where the TLOG table is created. The value of TLOGNAME must be an alphanumeric string containing 30 or fewer characters.

 


Specifying Environment Variable Settings

With the ENVFILE parameter, you can specify a file that contains environment variable settings for all processes to be booted by the BEA Tuxedo system. The system sets TUXDIR and APPDIR for each process, so these parameters should not be specified in this file.

You can, however, specify settings for the following parameters because they affect an application's operation:

Characteristics of the ENVFILE Parameter

ENVFILE is an optional parameter with the following characteristics:

For more information about setting environment variables, refer to tuxenv(5) in File Formats, Data Descriptions, MIBs, and System Processes Reference.

 


Defining the BEA Tuxedo Filesystem Containing the TLOG

Use the TLOGDEVICE parameter to specify 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 specified device. The value of TLOGDEVICE must be a string containing a maximum of 64 characters.

If this parameter is not specified, then it is assumed that the machine does not have a TLOG.

 


Specifying a Machine's Maximum Number of Simultaneous Global Transactions

Use the MAXGTT parameter to indicate the maximum number of simultaneous global transactions in which a particular machine can be involved. The value must be a number greater than or equal to 0, and less than 32,768. You can override the value specified in the RESOURCES section with a value specified in the MACHINES section for an individual machine.

 


Defining the Number of Accesser Entries on a Workstation Client

Use the MAXWSCLIENTS parameter to define the number of entries on a machine to be reserved for Workstation clients. Set the number of accesser slots reserved for MAXWSCLIENTS cautiously, since this number takes a portion of the total accesser slots specified with MAXACCESSERS for this machine; the accesser slots reserved for MAXWSCLIENTS are unavailable for use by other clients and servers on this machine. By setting this parameter to an appropriate value, you can help conserve IPC resources because Workstation client access to the system is multiplexed through a BEA Tuxedo system-supplied surrogate, the BEA Tuxedo Workstation Handler (WSH).

The value of MAXWSCLIENTS must be greater than or equal to 0 and less than 32,768. If not specified, the default is 0. It is an error to set this parameter to a number greater than MAXACCESSERS.

Note: The value of MAXWSCLIENTS is constrained by the number of your licensed users.

 


Defining Space Limits for Messages Transmitted by the BRIDGE

Use the MAXPENDINGBYTES parameter to define a limit for the amount of space that can be allocated for messages waiting to be transmitted by the BRIDGE process. This number must be between 100,000 and MAXLONG.

There are two situations when MAXPENDINGBYTES is significant:

You can configure larger computers that have more memory and disk space, with larger MAXPENDINGBYTES, and smaller computers with smaller MAXPENDINGBYTES.

 


Indicating the Offset for the DTP Transaction Log

Every BEA Tuxedo filesystem has a Volume Table of Contents (VTOC): a list of the files on the devices named in the Universal Device List (UDL). The UDL specifies the location of the physical storage space for BEA Tuxedo system tables. In a BEA Tuxedo system application, all system files might be stored together on the same raw disk slice or operating system filesystem file.

Use the TLOGOFFSET parameter to indicate the 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 a number greater than or equal to 0, and less than the number of pages on the device. The default is 0.

 


Defining the Offset for TUXCONFIG

Every BEA Tuxedo filesystem has a Volume Table of Contents (VTOC): a list of the files on the devices named in the Universal Device List (UDL). The UDL specifies the location of the physical storage space for BEA Tuxedo system tables. In a BEA Tuxedo system application, all system files might be stored together on the same raw disk slice or operating system filesystem file.

Use the TUXOFFSET parameter to define the offset in pages (from the beginning of the device) to the start of the BEA Tuxedo filesystem that contains the TUXCONFIG for this machine. (For information on how this value is used in the environment, see the ENVFILE parameter in the MACHINES section.)

Characteristics of the TUXOFFSET Parameter

 


Identifying the Locations of the System Software and Application Server Software

Each machine in an application that supports servers must have a copy of the BEA Tuxedo system software and application software. You identify the location of system software with the TUXDIR parameter. You identify the location of the application software with the APPDIR parameter. Both parameters are mandatory. The APPDIR parameter becomes the current working directory of all server processes. The BEA Tuxedo software looks in TUXDIR/bin and APPDIR for executables.

Characteristics of the APPDIR and TUXDIR Parameters

Parameter

Characteristics

APPDIR

The syntax requires a full pathname enclosed in double quotes: APPDIR="APPDIR".

APPDIR identifies the location of application software.

APPDIR is a required parameter.

APPDIR becomes the current working directory of server processes.

TUXDIR

The syntax requires a full pathname enclosed in double quotes: TUXDIR="TUXDIR".

TUXDIR identifies the location of the BEA Tuxedo software.

TUXDIR is a required parameter.


 

 


Indicating a Threshold Message Size for Compression

Use the CMPLIMIT parameter to define the threshold message sizes at which automatic data compression is performed for messages bound to remote processes (string_value1) and local processes (string_value2), respectively.

Both values must be either a non-negative numeric value or the string MAXLONG. If not specified, the default is MAXLONG,MAXLONG.

Note: Set the CMPLIMIT value and observe your application throughput. Because you can tune the CMPLIMIT value using the TMIB, you can adjust it while the system is running.

Example

CMPLIMIT=string_value1,string_value2

 


Specifying the Pathname for the ULOG

Set the ULOGPFX parameter to specify the full pathname to be used as the prefix of the name of 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, the path specified by the APPDIR environment variable is used. mmddyy (month, day, year) is appended to the prefix to form the full name of the log file.

Characteristics of the ULOGPFX Parameter

The ULOGPFX parameter has the following characteristics:

See Also

 


How to Create the GROUPS Section of the Configuration File

Use the GROUPS section to designate logically grouped sets of servers, which can later be used to access resource managers, and facilitate server group migration. The GROUPS section of the configuration file contains definitions of server groups. You must define at least one server group for a machine to have application servers running on it. If no group is defined for a machine, the group can still be part of the application and you can run the administrative command tmadmin(1) from that site.

For nontransactional, nondistributed systems, groups are relatively simple. You only need to map the group name to the number and logical machine ID for each group. Additional flexibility is available to support distributed transactional systems.

For each parameter in the GROUPS section, the following table provides a description and links to reference pages and additional information.

To Specify This Information in the GROUPS Section

Set This Parameter (Required/Optional)

For More Information, Click the Following

The logical name of the group.

GROUPNAME (Required)

Group name

The 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.

GRPNO (Required)

Group number

The resource manager dependent information needed when closing the resource manager.

CLOSEINFO (Optional)

Information for closing the resource manager

The resource manager dependent information needed when opening the resource manager.

OPENINFO (Optional)

Information for opening the resource manager

The number of transaction manager servers to start for the associated group, if TMSNAME is specified.

TMSCOUNT (Optional)

Number of TMS servers in the group

Principal name of the process used for identification, location of private key of principal user, and the environment variable containing the password.

SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, SEC_PRINCIPAL_PASSVAR

Security attributes

A value that specifies that all servers in the group are to be executed with the environment specified in the named file.

ENVFILE (Optional)

Server group environment

A value that 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).

LMID (Required)

Server group location

The name of the transaction manager server process associated with this group.

TMSNAME (Optional)

Transaction manager server for group


 

Sample GROUPS Section for ATMI

Following is a sample GROUPS section of a configuration file in an ATMI environment.

##EVBGRP1 LMID=SITE1      GRPNO=104
DEFAULT:TMSNAME=TMS_SQL TMSCOUNT=2 LMID=SITE1
BANKB1GRPNO=1 OPENINFO="TUXEDO/SQL:APPDIR1/bankdl1:bankdb:readwrite"
BANKB2GRPNO=2 OPENINFO="TUXEDO/SQL:APPDIR1/bankdl2:bankdb:readwrite"
BANKB3GRPNO=3 OPENINFO="TUXEDO/SQL:APPDIR1/bankdl3:bankdb:readwrite"

Sample GROUPS Section for CORBA

The followiing sample GROUPS section is from the UBBCONFIG file in the Tuxedo CORBA University sample Production application. In this sample, the groups specified by the RANGES identifier in the ROUTING section of the UBBCONFIG file need to be identified and configured.

The Production sample specifies four groups: ORA_GRP1, ORA_GRP2, APP_GRP1, and APP_GRP2. These groups mst be configured, and the machines on which they run on must be identified.

*GROUPS

APP_GRP1
LMID = SITE1
GRPNO = 2
TMSNAME = TMS

APP_GRP2
LMID = SITE1
GRPNO = 3
TMSNAME = TMS

ORA_GRP1
LMID = SITE1
GRPNO = 4
OPENINFO = "ORACLE_XA:Oracle_XA+Acc=P/scott/tiger+SesTm=100+LogDir=.+MaxCur=5"
   CLOSEINFO = ""
TMSNAME = "TMS_ORA"

ORA_GRP2
LMID = SITE1
GRPNO = 5
OPENINFO = "ORACLE_XA:Oracle_XA+Acc=P/scott/tiger+SesTm=100+LogDir=.+MaxCur=5"
CLOSEINFO = ""
TMSNAME = "TMS_ORA"

The preceding example shows how the ORA_GRP1, ORA_GRP2, APP_GRP1, and APP_GRP2 groups are configured. See the section CORBA Factory-based Routing in the University Production Sample Application on page 3-92 to understand how the names in the GROUPS section match the group names specified in the ROUTING section. This match is critical for the routing function to work correctly. Also, any change in the way groups are configured in an application must be reflected in the ROUTING section.

Note: The Production sample application packaged with the BEA Tuxedo software is configured to run entirely on one machine. However, you can easily configure this application to run on multiple machines by specifying the other machines in the LMID parameter. This step assumes that you specify the MODEL MP parameter in the RESOURCES section.

See Also

 


Specifying a Group Name, Number, and LMID

The group name, which is the basis for a GROUPS section entry, is an alphanumeric name by which the group is identified; it specifies the logical name (string_value) of the group. It is given a mandatory, unique group number (GRPNO). Each group must reside wholly on one logical machine (LMID).

The LMID specifies that this group of servers resides on the machine symbolically named by string_value1 in the MACHINES section.

Characteristics of the Group Name, Group Number, and LMID

Parameter

Characteristics

Group_name required_ parameters [optional_ parameters]

It is required.

It is an alphanumeric name by which the group is identified.

It is unique and specifies the logical name of the group.

GRPNO (Group Number)

It is required and is unique.

LMID=string_value1 [,string_value2]

It is required.

Each LMID value must be an alphanumeric string containing 30 or fewer characters.

Up to two logical machine names can be specified. If a second logical name is given and server group migration is enabled, the machine with which the server group is associated can be migrated.


 

See Also

 


Indicating a Transaction Manager Server Name and Numbers per Group

The name of the transaction manager server (TMS) must be specified in the entry for any group with servers that will participate in distributed transactions (transactions across multiple resource managers—and possibly machines). To specify a TMS, set the TMSNAME parameter. This parameter 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. This interface can be used for server groups that do not have resource managers. If you do not have a resource manager, you may not need a TMS. This server group may be infected with transactional messages. 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. Servers are restartable an unlimited number of times.

If TMSNAME is specified, TMSCOUNT=number must also be specified to indicate the number of transaction manager servers to start for the associated group. The default for TMSCOUNT is 3. If specified and the value is non-zero, the minimum value is 2 and the maximum value is 256. The servers are set up in an MSSQ set automatically.

 


Identifying the Environment File Location for Servers in a Group

If the value of the ENVFILE environment variable (ENVFILE=string_value) is an invalid filename, no values are added to the environment. Lines must be of the form ident=value where ident contains only underscores or alphanumeric characters.

Within value, strings of the form ${env} are expanded when the file is processed using variables already defined for the environment. (Forward referencing is not supported. If a value is not set, the variable is replaced with an empty string.) You can use a back slash (\) to escape dollar signs and other back slashes. All other shell quoting and escape mechanisms are ignored and the expanded value is placed in the environment.

Environment files are provided in at least two sections of the configuration file. The BEA Tuxedo system reads them in the following order:

  1. MACHINES section ENVFILE
  2. GROUPS section ENVFILE
  3. SERVERS section ENVFILE (Optional)

Values in the SERVERS section override values in the GROUPS section. Values in the GROUPS section override values in the MACHINES section.

 


Defining Information Needed When Opening and Closing the Resource Manager

The values of both the OPENINFO and CLOSEINFO parameters must be alphanumeric strings that contain a maximum of 256 characters, and are enclosed in double quotation marks. These settings specify the resource manager dependent information needed when opening and closing the resource manager for this group (that is, for this group name).

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. If the TMSNAME parameter is set to a value other than TMS but the CLOSEINFO 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 a close 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 of OPENINFO is as follows:

In all these settings, 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) in the BEA Tuxedo Command Reference) on which the queue space resides, and qspace is replaced with the name of the queue space. For Windows, the separator after qmconfig must be a semicolon (;).

Note: The CLOSEINFO string is not used for BEA Tuxedo /Q databases.

For other vendors' databases, the format of the OPENINFO string is specific to the particular vendor providing the underlying resource manager. As an example, the following OPENINFO string demonstrates the type of information needed when opening the Oracle resource manager.

OPENINFO="Oracle_XA: Oracle_XA+Acc=P/Scott/*****+SesTm=30+LogDit=/tmp"

Oracle_XA is the published name of the Oracle XA interface. The series of five asterisks (*) in the OPENINFO string pertains to the encrypting of a password, which is described in the paragraphs that follow.

Passwords passed to a resource manager in the OPENINFO string can be stored in either clear text or encrypted form. To encrypt a password, first enter a series of five or more continuous asterisks in the OPENINFO string at the place where you want the password to go. Then load the UBBCONFIG file by running tmloadcf(1). When tmloadcf() encounters the string of asterisks, it prompts you to create a password. For example:

tmloadcf -y /usr5/apps/bankapp/myubbconfig
Password for OPENINFO (SRVGRP=BANKB3):
password

tmloadcf() stores the password in the TUXCONFIG file in encrypted form. If you then regenerate the UBBCONFIG file from the TUXCONFIG file using tmunloadcf(1), the password is printed in the regenerated UBBCONFIG file in encrypted form with @@ as delimiters. For example:

OPENINFO="Oracle_XA: Oracle_XA+Acc=P/Scott/@@A0986F7733D4@@+SesTm=30+LogDit=/tmp"

When tmloadcf() encounters an encrypted password in a UBBCONFIG file generated by tmunloadcf(), it does not prompt the user to create a password.

 


How to Create the NETWORK Section of the Configuration File

If you have more than one machine in your distributed application, you need to create a NETWORK section in your configuration file. This section sets up communications among your machines. You can configure network groups in both the NETGROUPS and NETWORK sections of an application's UBBCONFIG file.

For each parameter in the NETWORK section, the following table provides a description and links to reference pages and additional information.

To Specify This Information in the NETWORK Section

Set This Parameter (Required/Optional)

For More Information, Click the Following

The device name to be used by the BRIDGE process placed on that LMID to access the network.

BRIDGE (Optional)

BRIDGE device name

The complete network address to be used by the BRIDGE process; that is, the listening address on the LMID.

NADDR (Required)

BRIDGE network address

The minimum level of encryption required when a network link to this machine is being established.

MINENCRYPTBITS (Optional)

Encryption levels

The maximum level of encryption allowed when a network link is being established.

MAXENCRYPTBITS (Optional)

Encryption levels

The network group associated with this network entry. If unspecified, then the default, DEFAULTNET, is assumed. (If not set to DEFAULTNET, this parameter must be defined as a group name in the NETGROUPS section.)

NETGROUP (Optional)

Network group

The network address used by the tlisten(1) process servicing the network on the node identified by the LMID.

NLSADDR (Optional)

tlisten network address


 

Sample NETWORK Section

The following configuration file excerpt shows a NETWORK section for a two-site configuration.

   *NETWORK
SITE1 NADDR="//mach1:80952"
NLSADDR="//mach1:serve"
# SITE2 NADDR="//mach386:80952"
NLSADDR="//mach386:serve"

See Also

 


Specifying a Device Name for the BRIDGE Process

To specify the device name to be used by the BRIDGE process placed on the LMID to access the network, set the BRIDGE parameter as follows:

BRIDGE=string_value 

If you are using TCP/IP, you do not need to specify the device name for the BRIDGE.

The pathname for the network transport endpoint file has the following form:

/dev/provider_name 

 


Assigning a BRIDGE Network Address

To specify the complete network address to be used by the BRIDGE process placed on the LMID as its listening address, set the NADDR parameter as follows:

NADDR = string_value

The listening address for a BRIDGE is the location at which it is contacted by other BRIDGE processes participating in the application.

The listening address for a BRIDGE may also be specified in one of the following three forms:

In the first of these formats, host.name is resolved to the address of the TCP/IP host address at the time the address is bound. This format is based on locally configured name resolution facilities accessed via an operating system command. The value of port_number can be a symbolic name or a decimal number.

In the second format, the string #.#.#.# represents four decimal numbers (each of which is between 0 and 255), separated by periods. The value of port_number is a decimal number in the range 0 to 65,535 (the hexadecimal representations of the string specified). The value of port_number can be a symbolic name or a decimal number.

In the third format, the string 0xhex-digits or \\xhex-digits must contain an even number of valid hex digits. A string in either of these forms is translated internally into a character array containing TCP/IP addresses.

Note: On some platforms lower numbers may be reserved for the system.

 


Assigning Encryption Levels

To set up the minimum level of encryption required when establishing a network link to the machine, set the MINENCRYPTBITS parameter. Valid values are 0, 56, and 128. 0 means no encryption, while 56, and 128 specify the encryption key length (in bits). If this minimum level of encryption cannot be met, link establishment fails. The default is 0.

To set up a maximum level of encryption when establishing a network link, set the MAXENCRYPTBITS parameter. Valid values are 0, 56, and 128. 0 means no encryption, while 56, and 128 specify the encryption key length (in bits). The default is 128.

Example

MAXENCRYPTBITS=128
MINENCRYPTBITS=0

See Also

 


Assigning a tlisten Network Address

To specify the network address used by the tlisten(1) process servicing the network on the machine identified by the LMID, set the NLSADDR parameter as follows:

NLSADDR=string_value

The value of string is a network address in the same format as that specified for the NADDR parameter.

The tlisten address for NLSADDR may be specified in one of the following three forms:

In the first of these formats, host.name is resolved to the address of the TCP/IP host address at the time the address is bound. This format is based on locally configured name resolution facilities accessed via an operating system command. The value of port_number can be a symbolic name or a decimal number.

In the second format, the string #.#.#.# represents four decimal numbers (each of which is between 0 and 255), separated by periods. The value of port_number is a decimal number in the range 0 to 65,535 (the hexadecimal representations of the string specified). The value of port_number can be a symbolic name or a decimal number.

In the third format, the string 0xhex-digits or \\xhex-digits must contain an even number of valid hex digits. A string in either of these forms is translated internally into a character array containing TCP/IP addresses.

tmloadcf(1) prints an error if NLSADDR is missing from an entry for any machine besides the MASTER LMID, for which it prints a warning. If NLSADDR is missing from the MASTER LMID, tmadmin(1)cannot run in administrator mode on remote machines; it is limited to read-only operations. In addition, the backup site cannot reboot the MASTER site after failure.

 


How to Create the NETGROUPS Section of the Configuration File

The NETGROUPS section of the UBBCONFIG file describes the network groups available to an application in a LAN environment. There is no limit to the number of network groups to which you can assign a pair of machines. The method of communication to be used by members of different networks in a network group is determined by the priority mechanism (NETPRIO).

Every LMID must be a member of the default network group (DEFAULTNET). The network group number for this group (that is, the value of NETGRPNO) must be zero. However, you can modify the default priority of DEFAULTNET. Networks defined in the BEA Tuxedo system prior to release 6.4 are assigned to the DEFAULTNET network group.

For each parameter in the NETGROUPS section, the following table provides a description and links to reference pages and additional information.

To Specify This Information in the NETGROUPS Section (Optional)

Set This Parameter (Required/Optional)

For More Information, Click the Following

Allow more netgroups to be defined than the default (8). This value is specified in the RESOURCES section.

MAXNETGROUPS (Optional)

Maximum netgroups

The maximum size of data waiting for the network to become available. This value is specified in the MACHINES section.

MAXPENDINGBYTES (Optional)

Message space limits

The network group associated with this network entry.

NETGROUP (Required)

Network group name

A unique network group number that you must assign to use in failover and failback situations.

NETGRPNO (Required)

Network group number

The priority of this network group.

NETPRIO (Optional)

Network group priority


 

Sample Network Groups Configuration

You can associate network addresses with a network group. The following example illustrates how this capability may be useful.

First State Bank has a network of five machines (A-E). Each machine belongs to two or three of four netgroups that you have defined in the following way:

Every machine belongs to DEFAULTNET (the corporate WAN). In addition, each machine is associated with either the MAGENTA_GROUP or the BLUE_GROUP. Finally, some machines in the MAGENTA_GROUP LAN also belong to the private GREEN_GROUP. The following illustration shows machines A through E in the networks for which they have addresses.

Figure 3-3 Example of a Network Grouping

Example of a Network Grouping


 

The following table shows which machines have addresses for which groups.

This Machine

Has Addresses for These Groups

A and B

DEFAULTNET (the corporate WAN)

MAGENTA_GROUP (LAN)

GREEN_GROUP (LAN)

C

DEFAULTNET (the corporate WAN)

MAGENTA_GROUP (LAN)

D and E

DEFAULTNET (the corporate WAN)

BLUE_GROUP (LAN)


 

Note: Because the local area networks are not routed among locations, machine D (in the BLUE_GROUP LAN) may contact machine A (in the GREEN_GROUP LAN) only by using the single address they have in common: the corporate WAN network address.

Configuring a Sample UBBCONFIG File with Netgroups

To set up the configuration just described, the First State Bank system administrator defines each group in the NETGROUPS section of the UBBCONFIG file, as shown in the following configuration file sample.

Listing 3-1 Sample NETGROUPS and NETWORK Sections

*NETGROUPS

DEFAULTNET NETGRPNO = 0 NETPRIO = 100 #default
BLUE_GROUP NETGRPNO = 9 NETPRIO = 200
MAGENTA_GROUP NETGRPNO = 125 NETPRIO = 200
GREEN_GROUP NETGRPNO = 13 NETPRIO = 300

*NETWORK

A NETGROUP=DEFAULTNET NADDR="//A_CORPORATE:5723"
A NETGROUP=MAGENTA_GROUP NADDR="//A_MAGENTA:5724"
A NETGROUP=GREEN_GROUP NADDR="//A_GREEN:5725"
B	NETGROUP=DEFAULTNET				NADDR="//B_CORPORATE:5723"
B NETGROUP=MAGENTA_GROUP NADDR="//B_MAGENTA:5724"
B NETGROUP=GREEN_GROUP NADDR="//B_GREEN:5725"
C	NETGROUP=DEFAULTNET				NADDR="//C_CORPORATE:5723"
C NETGROUP=MAGENTA_GROUP NADDR="//C_MAGENTA:5724"

D NETGROUP=DEFAULTNET NADDR="//D_CORPORATE:5723"
D NETGROUP=BLUE_GROUP NADDR="//D_BLUE:5726"

See Also

 


Assigning a Name to a Network Group

To assign a name to a network group, set the NETGROUP parameter as follows:

NETGROUP required_parameters [optional_parameters]

If you set NETGROUP to DEFAULTNET, then the entry describes the default network group. All network entries with a NETGROUP parameter of 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, so they can interoperate with previous releases.

 


Assigning a Network Group Number

To accommodate circumstances in which you may need to use failover and failback, you must set the NETGRPNO parameter as follows:

NETGRPNO=numeric_value

If this entry describes DEFAULTNET, the value of NETGRPNO must be zero.

 


Assigning a Priority to the Network Group

A pair of machines in multiple network groups of the same priority can communicate simultaneously over the circuits with the highest priority. To assign network group priorities, use the NETPRIO parameter. If all network circuits of a certain priority are torn down by an administrator or by network conditions, the next lower priority circuit is used. Retries of the higher priority circuits are attempted. The value of the NETPRIO parameter must be a number greater than zero and less than 8,192. The default is 100.

 


How to Create the SERVERS Section of the Configuration File

The SERVERS section of the configuration file contains information specific to a server process. While this section is not required, an application without this section has no application servers and little functionality. Each entry in this section represents a server process to be booted in the application and includes the following information:

Note: Command-line options supported by the BEA Tuxedo system are described in servopts(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

For each parameter in the SERVERS section, the following table provides a description and links to reference pages and additional information.

To Specify This Information in the SERVERS Section (Optional)

Set This Parameter (Required/Optional)

For More Information, Click the Following

Whether the server is a conversational server. Connections can be made only to conversational servers, and rpc requests (via tpacall(3c) or tpcall(3c)) can be made only to non-conversational servers.

CONV (optional run-time parameter)

Conversational server

Principal name of the process used for identification, location of the principal user's private key, and the environment variable containing the password

SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, SEC_PRINCIPAL_PASSVAR

Security attributes

When this server should be booted or shut down relative to other servers.

SEQUENCE (Optional boot parameter)

Server boot order

The minimum number of occurrences of the server to be booted by tmboot.

MIN (Optional boot parameter)

Server boot order

The maximum number of occurrences of the server that can be booted.

MAX (Optional boot parameter)

Server boot order

A list of servopts(5) options to be passed to a server process at boot time. If none are specified, the default is -A. string_value may contain up to 256 characters.

CLOPT (Optional boot parameter)

Server command-line options

A request for 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.

ENVFILE (Optional run-time parameter)

Server environment file

The name of 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.

SRVGRP (Required)

Server group

An integer that uniquely identifies a server within a group. Identifiers must be between 1 and 30,000 inclusive.

SRVID (required)

Server ID

The symbolic name of the request queue for the process.

RQADDR (Optional run-time parameter)

Server queue information

The numeric permissions on the request queue.

RQPERM (Optional run-time parameter)

Server queue information

Whether a reply queue should be established for the process.

REPLYQ (Optional run-time parameter)

Server queue information

The numeric permissions on the reply queue.

RPPERM (Optional run-time parameter)

Server queue information

The command that should be executed when the process abnormally terminates, if the process is restartable.

RCMD (Optional run-time parameter)

Server restart information

The maximum number minus one time that the process can be restarted within the period specified by GRACE, if the process is restartable.

MAXGEN (Optional run-time parameter)

Server restart information

A parameter that specifies that the process can have up to MAXGEN lives within the specified number of seconds, if the process is restartable.

GRACE (Optional run-time parameter)

Server restart information

Whether the process is restartable. Default is N. If server migration is specified, RESTART must be set to Y. (A server terminated with a SIGTERM signal must be rebooted.)

RESTART (Optional run-time parameter)

Server restart information

The default mode used by BEA Tuxedo system libraries within application processes to gain access to BEA Tuxedo system internal tables.

SYSTEM_ACCESS (Optional run-time parameter)

System access to servers

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

MINDISPATCHTHREADS

Threads

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

MAXDISPATCHTHREADS

Threads

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

THREADSTACKSIZE

threads

The WebLogic Server embedded LDAP-based authentication server. It is a System /T provided server that offers the authentication service while the user security information is located in WebLogic Server. This server may be used in a secure application to provide per-user authentication when clients join the application.

SECURITY USER_AUTH or higher must be specified.

Default uses the file $TUXDIR/udataobj/tpldap to get LDAP configuration information.

Example: LAUTHSVR SRVGRP= "AUTH''SRVID=100
CLOPT="-A--
-f/usr/tuxedo/udataobj/tpldap"

LAUTHSVR (Optional)

LAUTHSVR(5)


 

Sample SERVERS Section

Following is a sample SERVERS section of a configuration file.

*SERVERS
DEFAULT: RESTART=Y MAXGEN=5 GRACE=3600
REPLYQ=N CLOPT="-A"
ENVFILE="/usr/home/envfile"
SYSTEM_ACCESS=PROTECTED

RINGUP1 SRVGRP=GROUP1 SRVID=1 MIN=3
RQADDR="ring1"
RINGUP2 SRVGRP=GROUP1 SRVID=4 MIN =3
RQADDR="ring2"

Note: Omitted from this sample are SEQUENCE (the order of booting is 1 to 6), REPLYQ and RPPERM (the server does not receive replies), RCMD (no special commands are desired on restart), and CONV (servers are not conversational). Defaults are applied to all servers unless a different setting is specified for a specific server.

Sample SERVERS Section Parameters

In the preceding sample SERVERS section, the following parameters and values are specified.

Parameter

Meaning

RESTART=Y (default)

Restart the servers.

MAXGEN=5 (default)

The MAXGEN parameter specifies a number greater than 0 and less than 256 that controls the number of times a server can be started within the period specified by the GRACE parameter. The default is 1. If the server is to be restartable, MAXGEN must be >= 2. The number of restarts is at most number - 1 times. RESTART must be Y or MAXGEN is ignored.

GRACE=3600 (default)

If RESTART is Y, the GRACE parameter specifies the time period (in seconds) during which this server can be restarted as MAXGEN - 1 times. The number assigned must be equal to or greater than 0. The maximum is 2,147,483,648 seconds (or a little more than 68 years). If GRACE is not specified, the default is 86,400 seconds (24 hours). As soon as one GRACE period is over, the next grace period begins. Setting the grace period to 0 removes all limitations; the server can be restarted an unlimited number of times.

REPLYQ=N (default)

There is no reply queue.

CLOPT="-A" (default)

Specify -A on the command line of each server.

ENVFILE="/usr/home/envfile" (default)

Read environment settings from the file ENVFILE.

SYSTEM_ACCESS=PROTECTED (default)

Deny access to internal tables outside system code.

RINGUP1

Sample name of the first server to be booted.

SRVGRP=GROUP1 SRVID=1 MIN=3

RQADDR="ring1"

Three instances of the sample server will be booted in group GROUP1 with server IDs of 1, 2, and 3, respectively. The three servers will form an MSSQ set and will read requests from queue ring1.

Note: RQADDR assigns a symbolic name to the request queue of this server. MSSQ sets are established by using the same symbolic queue name for more than one server, as well as same executable name for all the servers (and by specifying a value greater than 1 for MIN).

RINGUP2

Name of the second sample server to be booted.


 

See Also

 


Specifying a Server as Conversational

If a server is conversational (that is, if it establishes a two-way connection between a client and a dedicated server), the CONV parameter is required and must be set to Y. The default is N, indicating that the server will not be part of a conversation.

Characteristics of the CONV Parameter

The CONV parameter has the following characteristics:

 


Setting the Order in Which Servers Are Booted

To specify the sequence of servers to be booted, set the SEQUENCE parameter for each server. The value of SEQUENCE can be any number between 1 and 10,000. A server with a smaller SEQUENCE value is booted before a server with a larger value. If the SEQUENCE parameter is not set for any servers, the servers are booted in the order in which they are listed in the SERVERS section. If some, but not all servers are sequenced, the sequenced servers are booted first. The order in which servers are shut down is the reverse of the order in which they were booted.

The SEQUENCE parameter is optional. It may be helpful in a large application in which control over boot order is important.

Warning: In CORBA environments, there is a strict order in which the system EventBroker, the FactoryFinder object, and the application factories must be booted. A CORBA application program will not boot if the order is changed. See the section Required Order in Which to Boot CORBA C++ Servers on page 3-63 for details.

To boot multiple servers, set the MIN parameter, which provides a shortcut to booting. All servers share the same options. If you specify RQADDR, the servers form an MSSQ set. The default for MIN is 1.

To specify the maximum number of servers that can be booted, set the MAX parameter. The tmboot(1) command boots MIN servers at run time. Additional servers can be booted up to MAX. The default is MIN.

The MIN and MAX parameters are helpful in keeping the size of the configuration files for large applications manageable. Allowances for MAX values must be made in the IPC resources. The MIN and MAX parameters are also used for conversational services and automatic server spawning.

Required Order in Which to Boot CORBA C++ Servers

The following is the correct order in which to boot the servers In a BEA Tuxedo CORBA environment. A CORBA application program will not boot if the order is changed.

  1. The system EventBroker, TMSYSEVT.
  2. The TMFFNAME server with the -N option and the -M option, which starts the NameManager service (as a Master). This service maintains a mapping of application-supplied names to object references.
  3. The TMFFNAME server with the -N option only, to start a Slave NameManager service.
  4. The TMFFNAME server with the -F option, to start the FactoryFinder object.
  5. The application C++ servers that are advertising factories.

Listing 3-2 shows the order in which servers are booted for the BEA Tuxedo CORBA University Basic application, which is one of the sample applications included with the BEA Tuxedo software. This SERVERS section is excerpted from an edited version of the ubb_b.nt configuration file.

Listing 3-2 Edited SERVERS Section from a University Sample UBBCONFIG

*SERVERS
# By default, restart a server if it crashes, up to 5 times
# in 24 hours.
#
DEFAULT:
RESTART = Y
MAXGEN = 5

# Start the BEA Tuxedo System EventBroker. This event broker
# must be started before any servers providing the
# NameManager Service
#
TMSYSEVT
SRVGRP = SYS_GRP
SRVID = 1

# TMFFNAME is a BEA Tuxedo CORBA provided server that
# runs the NameManager and FactoryFinder services.

# The NameManager service is a BEA Tuxedo CORBA-specific
# service that maintains a mapping of application-supplied names
# to object references.

# Start the NameManager Service (-N option). This name
# manager is being started as a Master (-M option).
#
TMFFNAME
SRVGRP = SYS_GRP
SRVID = 2
CLOPT = "-A -- -N -M"

# Start a slave NameManager Service
#
TMFFNAME
SRVGRP = SYS_GRP
SRVID = 3
CLOPT = "-A -- -N"

# Start the FactoryFinder (-F) service
#
TMFFNAME
SRVGRP = SYS_GRP
SRVID = 4
CLOPT = "-A -- -F"

# Start the interface repository server
#
TMIFRSVR
SRVGRP = SYS_GRP
SRVID = 5

# Start the university server
#
univb_server
SRVGRP = ORA_GRP
SRVID = 6
RESTART = N

# Start the listener for IIOP clients
#
# Specify the host name of your server machine as
# well as the port. A typical port number is 2500
#
ISL
SRVGRP = SYS_GRP
SRVID = 7
CLOPT = "-A -- -n //TRIXIE:2500"

In the example, after the TMSYSEVT and TMFFNAME servers are started, servers are started for:

Note: When migrating or shutting down and restarting groups or machines for any reason, if there are active slave NameManagers in other groups, be sure to organize your UBBCONFIG file so that a FactoryFinder or a slave NameManager is never restarted before the master NameManager is active. For example, if you have a FactoryFinder in the same group as the master NameManager, arrange the order of these servers in the UBBCONFIG file so the master NameManager is started first.

 


Characteristics of the SEQUENCE, MIN, and MAX Parameters

Parameter

Characteristics

SEQUENCE

It is an optional parameter with a numeric range of 1 - 10,000.

Smaller values are booted before larger values.

Servers for which this parameter is not set are booted in the order in which they are listed in the SERVERS section.

All sequenced servers are booted before any unsequenced servers.

MIN

It represents the minimum number of servers to boot during run time.

If RQADDR is specified and MIN>1, an MSSQ set is created.

All instances have the same server options.

The range of values is 0 to 1000.

The default is 1.

MAX

It represents the maximum number of servers to boot.

The range of values for MAX is 0 to 1000. If MAX is not specified, the default is the value of MIN.


 

 


Specifying Server Command-line Options

The BEA Tuxedo system allows you to specify options that are used when a server processes a request. These options are defined in servopts, which lists the run-time options for server processes. The server may need to obtain information from the command line. The CLOPT parameter allows you to specify command-line options that can change some defaults in the server, or pass user-defined options to the tpsvrinit() function.

The standard main() of a server parses one set of options ending with the argument --, and passes the remaining options to tpsvrinit(). The default for CLOPT is -A, which tells the server to advertise all the services built into it with buildserver(1) or buildobjserver(1). The following table provides a partial list of the available options.

Use This Option

To

-o filename

Redirect standard output to file filename.

-e filename

Redirect standard error to file filename.

-s services

Advertise services. For example, -s x,y,z to advertise services x, y, and z.

-s x,y,z:funcname

Advertise services x, y, and z, but process requests for those services with function funcname. This is called aliasing a function name.

-r

Specify that the server should log the services performed.

-v

Print out the list of the service name/function name to standard output.

This option cannot be used in the CLOPT in the UBBCONFIG. It must be used when manually invoking the server.


 

Note: You can find other standard main() options listed on servopts(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

Characteristics of the CLOPT Parameter

In the BANKAPP sample application, command-line options are specified as follows:

CLOPT="-A -- -T 10"

The server is given the option of advertising all services (-A) and teller ID of 10 so it can update a specific teller record with each operation. The use of this option, especially the options passed to tpsvrinit(), require communication between the system administrator and the application programmer.

See Also

 


Identifying the Location of the Server Environment File

Use the ENVFILE parameter in the MACHINES section to specify environment settings. You can also specify the same parameter for a specific server process; the semantics are the same. If both the MACHINES section ENVFILE and the SERVERS section ENVFILE are specified, both go into effect. For any overlapping variable defined in both the MACHINES and SERVERS sections, the setting in the SERVERS section prevails.

Characteristics of the Server Environment File

ENVFILE, the parameter that defines the server environment file, has the following characteristics:

For more information about setting environment variables, refer to tuxenv(5) in File Formats, Data Descriptions, MIBs, and System Processes Reference.

 


Defining Server Name, Group, and ID

You initially assign a name to a server in the SERVERS section. The name you specify must be the name of an executable file built with one of the following commands:

You must also specify a group identifier (SRVGRP) for each server. The value of SRVGRP must be the name specified in the beginning of a GROUPS section entry. Finally, you must also provide each server process in a given group with a unique numeric identifier (SRVID). Every server entry must include the SRVGRP and SRVID parameters. Because the entries describe machines to be booted and not just applications, it is possible that in some cases the same server name will be displayed in many entries.

Characteristics of the Server Name, SRVGRP, and SRVID Parameters

Parameter

Characteristics

Server_name

It identifies the executable to be booted.

It is built with buildserver(1) for ATMI.

It is built with buildobjserver(1) for CORBA.

It is required, but may not be unique within a server group.

SRVGRP (Server Group)

It identifies the group affiliation.

The group name begins with a GROUPS section entry.

It is required.

SRVID (Server ID)

It is numeric.

It is required and unique within a server group.


 

 


Identifying Server Queue Information

Server queue information controls the creation and access of server message queues. On a BEA Tuxedo system, you can create Multiple Server, Single Queue (MSSQ) sets by using the RQADDR parameter. For any given server, you can set this parameter to an alphanumeric value. By specifying the same value for RQADDR on all servers that offer the same services, you can consolidate those services under one message queue, thus creating an MSSQ set and establishing load balancing.

MSSQ Example

An MSSQ set is similar to a bank staff. Four tellers may be available to handle the business requests of many customers who wait in a single line. All customers are assured of an equitable wait in line. Understandably, a loan officer is not included in the group of tellers handling requests from customers in that line. The loan officer cannot handle requests for deposits and withdrawals (as the tellers can), and not all customers want loans. Similarly, a server cannot join an MSSQ set if the services it offers are not the same as the services offered by the servers in an MSSQ set.

The RQPERM parameter allows you to specify the permissions for server request queues, along the lines of the UNIX system convention (for example, 0666). This setting allows services to control access to the request queue.

If the service routines within an MSSQ server perform service requests, they must receive replies to their requests on a reply queue. You can set up such a reply queue by specifying REPLYQ=Y. By default, REPLYQ is set to N. If REPLYQ is set to Y, you can also assign permissions to it with the RPPERM parameter.

Characteristics of the RQADDR, RQPERM, REPLYQ, and RPPERM Parameters

Parameter

Characteristics

RQADDR

It is an alphanumeric value that allows MSSQ sets to be created. The value is the same for all members of an MSSQ set. All members of an MSSQ set must offer the same set of services and the servers in an MSSQ set should have the same executable name. In order to boot multiple servers, set the value greater than 1 for Min parameter.

RQPERM

Represents the permissions on a request queue. If no parameter is specified, the permissions of the bulletin board, as specified by PERM in the RESOURCES section, are used. If no value is specified there, the default of 0666 is used. When the default is used, your application is available to anyone with a login on the system.

REPLYQ

Specifies whether a reply queue, separate from the request queue, is to be set up for this server. If only one server is using the request queue, replies can be picked up from the request queue without causing problems. On a BEA Tuxedo system, if the server is a member of an MSSQ set and contains services programmed to receive reply messages, REPLYQ should be set to Y so that an individual reply queue is created for this server. If not, the reply is sent to the request queue shared by all servers of the MSSQ set, and there is no way of assuring that it will be picked up by the server that is waiting for it. Multithreaded servers automatically create REPLYQs even if this parameter is not set.

RPPERM

Assigns permissions to the reply queue. This parameter is useful only when REPLYQ=Y. If requests and replies are read from the same queue, only RQPERM is needed; RPPERM is ignored.


 

 


Defining Server Restart Information

A properly debugged server should not terminate on its own. By default, servers that do terminate while the application is running are not restarted by the BEA Tuxedo system. You can set the RESTART parameter to Y if you want the server to restart. The RCMD, MAXGEN, and GRACE parameters are relevant to a server if RESTART=Y.

The RCMD parameter lets you specify a command to be performed in parallel with restarting a server. For example, you may want to have e-mail sent to the developer of the server or to someone who is auditing such activity.

The MAXGEN parameter represents the total number of lives to which a server is entitled within the period specified by GRACE. The server can then be restarted MAXGEN-1 times during GRACE seconds. If GRACE is set to zero, there is no limit on server restarts. MAXGEN defaults to 1 and may not exceed 256. GRACE must be greater than or equal to zero and must not exceed 2,147,483,647 (231 - 1).

Note: A fully debugged server should not need to be restarted. RESTART and associated parameters should have two settings: one for the testing phase, and another for production.

Characteristics of the RESTART, RCMD, MAXGEN, and GRACE Parameters

Parameter

Characteristics

RESTART

A setting of Y enables a server to restart.

The default is N.

RCMD

Specifies an executable file to be run at restart time.

Allows you to take an action when a server is restarted.

MAXGEN

Represents the maximum number of server lives in a specific interval.

The default is 1; the maximum is 256.

GRACE

Represents the interval used by MAXGEN.

Zero represents unlimited restart.

It must be between 0 and 2147,483,647 (231 - 1).

The default is 24 hours.


 

 


Defining Server Access to Shared Memory

The SYSTEM_ACCESS parameter determines whether a server process may attach to shared memory and thus have access to internal tables outside system code. During application development, we recommend that such access be denied (PROTECTED). When the application is fully tested, you can change the value of SYSTEM_ACCESS to FASTPATH to yield better performance.

This parameter setting overrides the value specified in the RESOURCES section unless the NO_OVERRIDE value has been specified. In this case, the parameter is ignored. The NO_OVERRIDE value may not be used in this section.

Characteristics of the SYSTEM_ACCESS Parameter

The SYSTEM_ACCESS parameter has the following characteristics:

 


Defining the Server Dispatch Threads

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

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

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

 


Setting Security Parameters for ISL Servers

In CORBA environments the IIOP Listener (ISL) process listens for remote clients requesting a connection. The ISL process is specified in one entry as a server supplied by the BEA Tuxedo system.

The Secure Socket Layer (SSL) protocol defines how processes can communicate in a secure manner over IIOP. Use the -s option on the ISL command to set the required parameters. You only need to set these parameters if you are using the SSL protocol, which is installed in the BEA Tuxedo Security Pack.

Table 3-1 lists the SSL parameters characteristics.

Table 3-1 ISL and SSL Parameters Characteristics

Parameter

Characteristics

SEC_PRINCIPAL_NAME

Specifies the identity of the IIOP Listener/Handler.

SEC_PRINCIPAL_LOCATION

Specifies the location of the private key for the IIOP Listener/Handler.

SEC_PRINCIPAL_PASSWORD

Specifies the phrase for the private key of the IIOP Listener/Handler.

:


 

For more information about setting these parameters, see Using Security in CORBA Applications.

 


How to Create the SERVICES Section of the Configuration File

Detailed information about the services in your application can be entered in the SERVICES section of the configuration file. For nontransactional, nondistributed applications, such information is relatively simple. The SERVICES section includes the following types of information:

There are no required parameters for services. You need to list services only if you are setting optional parameters.

For each parameter in the SERVICES section, the following table provides a description and links to reference pages and additional information.

To Specify This Information in the SERVICES Section

Set This Parameter (Required/Optional)

For More Information, Click the Following

Whether a transaction should be started automatically when a request message is received that is not already in transaction mode.

AUTOTRAN (For DTP applications only)

Automatic starts for transactions

A list of types and subtypes of data buffers accepted by this service. This parameter may contain up to 256 characters with a maximum of 32 type/subtype combinations.

BUFTYPE (Optional)

Buffer types

A load factor to be imposed on the system by SVCNAM.

LOAD (Optional)

Load balancing

The name of the routing criteria used for this service when data- dependent routing is used.

ROUTING (Optional)

Routing criteria name

The name of the sever group from which SVCNAM gets all group parameter settings.

SRVGRP (Optional)

Server group parameters

The dequeuing priority of SVCNM.

PRIO (Optional)

Service priorities

Set the nontransactional blocking time value, in seconds, of the indicated service.

BLOCKTIME (Optional)

Specifying Nontransactional Service-Level Blocktime

The amount of time, in seconds, that is allowed for processing of the indicated service.

SVCTIMEOUT (Optional)

Service processing time

The default timeout interval, in seconds, for a transaction automatically started for the associated service.

TRANTIME (For DTP applications only)

Timeout values for transactions


 

Sample SERVICES Section

Following is a sample of the SERVICES section of a configuration file.

*SERVICES
#
DEFAULT: LOAD=50 PRIO=50
RINGUP BUFTYPE="VIEW:ringup"

In this example, the default load and priority of a service are 50; the one service declared is a RINGUP service that accepts a RINGUP VIEW as its required buffer type.

See Also

 


Specifying Automatic Starts and Timeout Intervals for Transactions

You can determine whether a transaction should be started automatically if a request message is already in transaction mode by coding the AUTOTRAN ={Y|N} parameter. The default is N.

You can specify a timeout interval between the time at which a transaction for a service begins and the time at which it is rolled back if not completed. To specify a timeout interval that will be used automatically, set the TRANTIME parameter as follows:

TRANTIME=number

The default is 30 seconds. A value of 0, the maximum timeout value for the computer, means a transaction will never time out.

An additional transaction timeout property named MAXTRANTIME is available from the RESOURCES section of the UBBCONFIG file. If the MAXTRANTIME timeout value is less than the TRANTIME timeout value or the timeout value passed in a tpbegin(3c) call to start a transaction, the timeout for a transaction is reduced to the MAXTRANTIME value.

Note: MAXTRANTIME has no effect on a transaction started on a machine running BEA Tuxedo 8.0 or earlier, except that when a machine running BEA Tuxedo 8.1 or later is infected by the transaction, the transaction timeout value is capped—reduced if necessary—to the MAXTRANTIME value configured for that node.

See Also

 


Specifying a List of Allowable Buffer Types for a Service

With the BUFTYPE parameter, you can tune a service to check buffer types independently of the service code. Set this parameter with a list of allowable buffer types for a service in the following format:

type[:subtype[,subtype]]

To allow all subtypes, set the value of subtype to *.

If the value of the BUFTYPE parameter for a service is ALL, this service accepts all buffer types. The default is ALL.

Examples of the BUFTYPE Parameter

BUFTYPE Example

Meaning

BUFTYPE="FML;VIEW:aud,aud2"

FML and VIEW buffer types with subtypes aud and aud2 are allowed.

BUFTYPE="FML;VIEW:*"

All FML and VIEW buffer types are allowed.

BUFTYPE=ALL

All buffer types are allowed (the default).


 

 


Designating How Much Time to Process a Request

Sometimes an unexpected system error occurs, freezing a service or causing it to run out of control while it is processing a request. Obviously, it is a good idea to remove these processes, but it is difficult to detect them or determine how they developed errors. The BEA Tuxedo system provides a mechanism for terminating such processes even when you cannot identify them. To use this mechanism, set the SVCTIMEOUT parameter.

The SVCTIMEOUT parameter allows you to designate an amount of time (in seconds) in which a service should be able to process a request. If the interval defined by this parameter elapses and a service has not finished processing a request, the process for that request is killed. In essence, the service timeout mechanism acts like a scavenger for frozen or out of control application servers. By default, the BEA Tuxedo system does not terminate any service process; you must set the SVCTIMEOUT parameter to activate this feature.

You can assign a value to the SVCTIMEOUT parameter in the UBBCONFIG file or by dynamically changing the TA_SVCTIMEOUT attribute in TM_MIB. We recommend that you set the value of SVCTIMEOUT or TA_SVCTIMEOUT to at least two to three times the number of seconds it takes for your longest running service to process a request. Setting the service timeout in this way guarantees that the BEA Tuxedo system removes only frozen processes.

This section describes the causes and results of service timeout errors, and explains how the BEA Tuxedo system reports such errors. Advice about how to handle errors is also provided.

What Happens When a Timeout Occurs

When a timeout occurs, the BEA Tuxedo system terminates the server process running the frozen service (but not its child processes, if any). It then returns a TPESVCERR error, indicating that an unknown problem occurred during processing. In a conversational service, the conversation event TPEV_SVCERR is returned.

How a Service Timeout Is Reported

The BEA Tuxedo system reports a service timeout through the following three mechanisms:

Because the SVCTIMEOUT value is configurable, it is important for clients to be able to easily distinguish between a TPESVCERR caused by exceeding the value set for SVCTIMEOUT, and a TPESVCERR caused by other situations. Although the ULOG contains this information, it is difficult for client programs to extract it. To differentiate a service timeout TPESVCERR from others, a program can include a call to the tperrordetail(3c) routine (after a TPESVCERR has been detected), which yields TPED_SVCTIMEOUT when a service timeout occurs.

In addition, a system event, .SysServiceTimeout, is generated when a service timeout occurs. When a .SysServiceTimeout event occurs, it is reflected in the ULOG in the following way:

ERROR: .SysServiceTimeout: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID server killed due to a service timeout 

How to Control a Service Timeout

 


Specifying Nontransactional Service-Level Blocktime

Different services take different amounts of time and need individual BLOCKTIME values. Sometimes, an application needs or desires to override the default blocktime value for an individual client or for an individual service call.

The UBBCONFIG file SERVICES section BLOCKTIME parameter allows you to designate the blocking time value, per second, for individual nontransactional services. It overrides the default RESOURCES section BLOCKTIME parameter value for the designated service. Per service BLOCKTIME parameter values can also be set for remote services using the DMCONFIG file. For more information, see UBBCONFIG(5), SERVICES section and DMCONFIG(5), DM_IMPORT section.

Unlike the SVCTIMEOUT parameter, the BLOCKTIME parameter does not terminate a service application. Instead, it lets the client know that (after a specified time in seconds), no reply has been received by the server while the service request is still processing.

Note: Application programmers can also set nontransactional blocktime requests and retrieve blocktime values by using the tpsblktime(3c) and tpgblktime(3c)functions.

 


Enabling Load Balancing

To activate load balancing, set the RESOURCES section parameter LDBAL to Y. A load factor is assigned to each service performed (via the LOAD parameter) and the BEA Tuxedo system keeps track of the total load of services that each server has performed. Each service request is routed to the server with the smallest total load. The routing of that request causes the server's total to be increased by the LOAD factor of the service requested.

Load information is stored only on the site originating the service request. It would be inefficient for the BEA Tuxedo system to make continuous attempts to propagate load information to all sites in a distributed application. When performing load balancing in such an environment, each site knows only about the load it originated and performs load balancing accordingly. This means that each site has different load statistics for a given server (or queue). The server perceived as being the least busy differs from site to site.

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

Characteristics of the LDBAL Parameter

The LDBAL parameter has the following characteristics:

 


Defining the Name of the Routing Criteria

When using data-dependent routing, you need to specify the routing criteria to be used for a service. To specify such criteria, set the ROUTING parameter as follows:

ROUTING=string_value

If this parameter is not set, the service does not perform data-dependent routing.

The maximum value of string is 15 characters. No more than one value may be assigned to the ROUTING parameter for a given service. Even if you have multiple entries for one service and those entries contain different SRVGRP parameters, the value of ROUTING must be the same in all entries.

 


Specifying Service Parameters for Different Server Groups

You can assign the same service to multiple groups and assign different values to the various service-specific parameters you set for the service entries for the different groups. To do this, create a separate entry for the service for each group, specifying a group-specific value for the SRVGRP parameter.

 


Controlling the Flow of Data by Service Priority

You can exert significant control over the flow of data in an application by assigning service priorities using the PRIO parameter. The value of PRIO must be a number between 0 and 100. The higher the number, the higher the priority of the service to which it is assigned. Higher priority services are dequeued before lower priority services, but the system dequeues every tenth request in FIFO order to prevent a message from waiting indefinitely on the queue.

For instance, Server 1 offers Services A, B, and C. Services A and B have a priority of 50 and Service C has a priority of 70. A service requested for C will always be dequeued before a request for A or B. Requests for A and B are dequeued equally with respect to one another.

Note: A priority can also be changed dynamically with the tpsprio()call.

Characteristics of the PRIO Parameter

The PRIO parameter has the following characteristics:

Sample SERVICES Section Using Different Priorities

The following sample from the SERVICES section of a configuration file shows how priorities are assigned to services:

*SERVICES
A SRVGRP=GRP1 PRIO=50 LOAD=60
A SRVGRP=GRP2 PRIO=70 LOAD=30

In this example, different service-specific parameters are assigned to two server groups. Service A is assigned a priority of 50 and a load of 60 in server group GRP1, and a priority of 70 and a load of 30 in server group GRP2.

 


Indicating Service Processing Time

To indicate the maximum amount of time, in seconds, allowed for processing a service, set the SVCTIMEOUT parameter as follows:

SVCTIMEOUT=number

The value must be greater than or equal to 0. A value other than 0 indicates that the service will be timed out: the server processing the server request will be terminated with a SIGKILL signal. The default for this parameter is 0.

 


How to Create the INTERFACES Section of the Configuration File

Note: This section applies only to the CORBA environments.in BEA Tuxedo.

The INTERFACES section in the configuration file is used to define parameters for CORBA environments in the BEA Tuxedo system. In this section, you define application-wide default parameters for CORBA interfaces used by the application. For a CORBA interface participating in factory-based routing, you define the interface names and specify the name of the routing criteria that the Tuxedo CORBA environment should apply to each interface. Factory-based routing is a feature that lets you distribute processing to specific server groups.

In addition to defining the INTERFACES section, you must specify routing criteria in the ROUTING section and the names of groups in the GROUPS section when you implement factory-based routing. For details about the parameters and more information about factory-based routing, see the section How to Create the ROUTING Section of the Configuration File in this chapter.

Specifying CORBA Interfaces in the INTERFACES Section

You indicate specific information about CORBA interfaces used by your application in the INTERFACES section of the configuration file. There are no required parameters. CORBA interfaces need not be listed if no optional parameters are desired. The INTERFACES section includes the following types of information:

Table 3-2 lists the AUTOTRAN, FACTORYROUTING, LOAD, PRIO, SRVGRP, TRANTIME, and TIMEOUT parameters characteristics.

Table 3-2 INTERFACES Section Parameters Characteristics 

Parameter

Characteristic

AUTOTRAN = {Y | N }

For each CORBA interface, set AUTOTRAN to Y if you want a transaction to start automatically when an operation invocation is received. AUTOTRAN=Y has no effect if the interface is already in transaction mode. The default is N.

The effect of specifying a value for AUTOTRAN is dependent on the transactional policy specified by the system designer in the implementation configuration file (ICF) or Server Description File (XML) for the interface. This transactional policy will become the transactional policy attribute of the associated T_IFQUEUE MIB object at run time. The only time this value actually affects the behavior of the application is if the system designer specified a transaction policy of optional.

Note: To work properly, this feature may be dependent on personal communication between the system designer and the system administrator. If the system administrator sets this value to Y without prior knowledge of the ICF or XML parameters set by the programmer, the actual run-time effort of the parameter might be unknown.

FACTORYROUTING = criterion-name

Specify the name of the routing criteria to be used for factory-based routing for this CORBA interface. You must specify a FACTORYROUTING parameter for interfaces requesting factory-based routing.

LOAD = number

This is 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 number is used by the BEA Tuxedo system to select the best server to route the request.

PRIO = number

Specify 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

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

TRANTIME = number

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

TIMEOUT=number

The amount of time, in seconds, to allow for processing of a method for this CORBA interface. The values 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. You should consider specifying a timeout value for the longest-running method for the interface.


 

Specifying FACTORYROUTING Criteria

For each CORBA interface, the INTERFACES section specifies what kinds of criteria the interface routes on. The INTERFACES section specifies the routing criteria via an identifier, FACTORYROUTING.

University Sample

The University Production sample application demonstrates how to code factory-based routing (see Listing 3-3). You can find the UBBCONFIG files (ubb_p.nt or ubb_p.mk) for this sample in the directory where the BEA Tuxedo software is installed. Look in the \samples\corba\university\production subdirectory.

Listing 3-3 Production Sample INTERFACES Section

*INTERFACES

"IDL:beasys.com/UniversityP/Registrar:1.0"
FACTORYROUTING = STU_ID

"IDL:beasys.com/BillingP/Teller:1.0"
FACTORYROUTING = ACT_NUM

The preceding example shows the fully qualified interface names for the two interfaces in the University Production sample. The FACTORYROUTING identifier specifies the names of the routing values, which are STU_ID and ACT_NUM, respectively.

To understand the connection between the INTERFACES FACTORYROUTING parameter and the ROUTING section, see the section CORBA Factory-based Routing in the University Production Sample Application on page 3-92.

Bankapp Sample

Listing 3-4 shows how factory-based routing is specified in the Bankapp sample application.

Listing 3-4 Bankapp Sample Factory-based Routing

*INTERFACES
"IDL:BankApp/Teller:1.0"
FACTORYROUTING=atmID
*ROUTING
atmID
TYPE = FACTORY
FIELD = "atmID"
FIELDTYPE = LONG
RANGES = "1-5:BANK_GROUP1,
6-10: BANK_GROUP2,
*:BANK_GROUP1

In this example, the IDL:Bankapp/Teller interface uses a factory-based routing scheme called atmID, as defined in the ROUTING section. In the ROUTING section, the sample indicates that the processing will be distributed across two groups. BANK_GROUP1 processes interfaces used by the application when the atmID field is between 1 and 5, or greater than 10. BANK_GROUP2 processes interfaces used by the application when the atmID field is between 6 and 10, inclusive.

Enabling Load Balancing

In BEA Tuxedo CORBA envirionments, load balancing is always enabled.

A LOAD factor is assigned to each CORBA interface invoked, which keeps track of the total load of CORBA interfaces that each server process has performed. Each interface request is routed to the server with the smallest total load. The routing of that request 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.

For more information about load balancing in BEA Tuxedo CORBA environments, refer to "Enabling System-controlled Load Balancing," in the Scaling, Distributing, and Tuning CORBA Applications manual.

Support for parallel objects in CORBA environments has been added for release 8.0 of BEA Tuxedo, which introduces load balancing across mulitple servers in a local domain. For more information about parallel objects in BEA Tuxedo CORBA environments, refer to the "Using Parallel Objects" section in Scaling, Distributing, and Tuning CORBA Applications.

Controlling the Flow of Data by Interface Priority

You can control the flow of data in a BEA Tuxedo client or server application by assigning interface priorities using the PRIO parameter. For instance, Server 1 offers Interfaces A, B, and C. Interfaces A and B have a priority of 50 and Interface C has a priority of 70. An interface requested for C will always be dequeued before a request for A or B. Requests for A and B are dequeued equally with respect to one another. The system dequeues every tenth request in FIFO order to prevent a message from waiting indefinitely on the queue.

The PRIO parameter has the following characteristics:

Specifying Different Interface Parameters for Different Server Groups

You can specify different load, priority, or other interface-specific parameters for different server groups. To do this, you should repeat the interface's entry for each group with different values for the SRVGRP parameter.

 


How to Create the ROUTING Section of the Configuration File

The ROUTING section of UBBCONFIG allows you to provide a full definition of the routing criteria named in the SERVICES section (for ATMI data-dependent routing) or in the INTERFACES section (for CORBA factory-based routing).

Note: For more information about configuring factory-based routing for CORBA environments, refer to the Scaling, Distributing, and Tuning CORBA Applications guide.

For each parameter in the ROUTING section, the following table provides a description and links to reference pages and additional information.

To Specify This Information in the ROUTING Section (Optional)

Set This Parameter (Required/Optional)

For More Information, Click the Following

Ranges and associated server groups for the routing field.

RANGES (Required)

Range criteria

The value must be a string with a maximum length of 15 characters.

For ATMI, the routing criteria name specified as the value of the ROUTING parameter in the SERVICES section for data-dependent routing.

For CORBA, the routing criteria name specified in the INTERFACES section as the FACTORYROUTING parameter factory-based routing.

criterion_name (required)


Specifies the routing type.

For ATMI, the default is TYPE=SERVICE to ensure that existing UBBCONFIG files used in Tuxedo ATMI environments continue to work properly.

For CORBA, use TYPE=FACTORY when implementing factory-based routing for a CORBA interface.

TYPE


Name of the routing field, which is assumed to be an FML buffer, XML element or element attribute, view field name identified in an FML field table (using FLDTBLDIR and FIELDTBLS environment variables), or an FML view table (using the VIEWDIR and VIEWFILES environment variables), respectively. This information is used to obtain the associated field value for data-dependent routing when sending a message.

In CORBA factory-based routing, this value specifies the name of the routing field. The maximum length is 30 characters. It must correspond to a field name specified for factory-based routing in a factory's call to: TP::create_object_reference (C++) or com.beasys.Tobj.TP::create_object_
reference
(Java) for the interface.

FIELD (Required)

Routing buffer field and type

A list of types and subtypes of data buffers for which this routing entry is valid. This parameter may contain up to 256 characters with a maximum of 32 type/subtype combinations.

BUFTYPE (required)

Buffer types and subtypes


 

ROUTING Section Example

The following is a sample ROUTING section from a configuration file:

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

 


Defining the Routing Buffer Field and Field Type

The following table describes the routing buffer field and field type.


 

Parameter

Characteristics

FIELD

The name of the buffer field on which the routing is performed. It may contain up to 30 characters.

In BEA Tuxedo data-dependent routing, the value of this parameter is one of the following: the name of an FML field (for FML buffers); an XML element or attribute; a VIEW field name 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). This information is used to obtain the associated field value for data-dependent routing during message processing. If a field in an FML32 buffer is used for routing, it must have a field number less than or equal to 8191.

In routing XML documents, the FIELD syntax contains either a routing element type (or name) or a routing element attribute name. You must define the FIELD parameter with the following syntax:

root_element[/child_element][/child_element][/. . .][/@attribute_name]

The element is assumed to be an element type (or name) or an element attribute name of an XML document or datagram. This information is used to obtain the associated element content or element attribute value for data-dependent routing when a document or datagram is being sent. Because indexing is not supported, the BEA Tuxedo system recognizes only the first occurrence of a given element type when processing an XML buffer for data-dependent routing.

In CORBA factory-based routing, this value specifies the name of the routing field. The maximum length is 30 characters. It must correspond to a field name specified for factory-based routing in a factory's call to:

TP::create_object_reference (C++) or com.beasys.Tobj.TP::create_object_reference (Java) for the interface.

FIELDTYPE

This parameter is used only for routing XML buffers. It indicates the type of the routing field specified in FIELD.The syntax is as follows:

FIELDTYPE=type

where type is one of the following: string, char, short, long, float, or double.

The default type of the routing field is string.


 

 


Specifying Range Criteria

The RANGES parameter allows you to map field values to a group name as follows:

RANGES="[val1[-val2]:group1] [,val3[-val4]:group2]...[,*:groupn]"

where val1, val2, and so on, are values of a field and groupn may be either a group name or the wildcard character (*) denoting that any group may be selected. The * character occupying the place of val at the end is a catch-all choice, that is, it specifies if the data does not fall into any range that has been specified then it goes to the default group on the other hand if the data fall into the range but there is no viable server in the group associated with the range entry, then the service request is forwarded to the default group specified on the wildcard "*" range entry. The value of val1 may be:

There is no limit to the number of ranges that may be specified, but routing information incurs a cost because it is stored in shared memory.

Note: Overlapping ranges are allowed, but values that belong to both ranges map to the first group. For example, if RANGES is specified as RANGES="0-5:Group1,3-5:Group2", then a range value of 4 routes to Group1.

 


Defining Buffer Types

For BEA Tuxedo data-dependent routing, the BUFTYPE parameter determines the buffer type allowed. This parameter is similar to its SERVICES section counterpart in that it restricts the routing criteria to a specific set of buffer types and subtypes. Only FML, XML and VIEW types can be used for routing. The syntax is the same as the syntax in the SERVICES section, a semicolon-separated list of type:subtype[,subtype]. You can specify only one type for routing criteria. This restriction limits the number of buffer types allowed in routing services.

 


CORBA Factory-based Routing in the University Production Sample Application

The CORBA University Production sample application demonstrates how to implement factory-based routing in BEA Tuxedo. You can find the ubb_p.nt or ubb_p.mk UBBCONFIG files for this sample in the directory where the BEA Tuxedo software is installed. Look in the \samples\corba\university\production subdirectory.

The following INTERFACES, ROUTING, and GROUPS sections from the ubb_b.nt configuration file show how you can implement factory-based routing in a CORBA application in BEA Tuxedo.

The INTERFACES section lists the names of the interfaces for which you want to enable factory-based routing. For each interface, this section specifies what kinds of criteria the interface routes on. This section specifies the routing criteria via an identifier, FACTORYROUTING, as in the example in Listing 3-5.

Listing 3-5 Production Sample INTERFACES Section

*INTERFACES

"IDL:beasys.com/UniversityP/Registrar:1.0"
FACTORYROUTING = STU_ID

"IDL:beasys.com/BillingP/Teller:1.0"
FACTORYROUTING = ACT_NUM

The preceding example shows the fully qualified interface names for the two interfaces in the Production sample in which factory-based routing is used. The FACTORYROUTING identifier specifies the names of the routing values, which are STU_ID and ACT_NUM, respectively.

The ROUTING section specifies the following data for each routing value:

Listing 3-6 shows the ROUTING section of the UBBCONFIG file used in the Production sample application.

Listing 3-6 Production Sample ROUTING Section

*ROUTING

STU_ID
FIELD = "student_id"
TYPE = FACTORY
FIELDTYPE = LONG
RANGES = "100001-100005:ORA_GRP1,100006-100010:ORA_GRP2"

ACT_NUM
FIELD = "account_number"
TYPE = FACTORY
FIELDTYPE = LONG
RANGES = "200010-200014:APP_GRP1,200015-200019:APP_GRP2"

The preceding example shows that Registrar objects for students with IDs in one range are instantiated to one server group, and Registrar objects for students with IDs in another range are instantiated in another group. Likewise, Teller objects for accounts in one range are instantiated to one server group, and Teller objects for accounts in another range are instantiated in another group.

The groups specified by the RANGES identifier in the ROUTING section of the UBBCONFIG file need to be identified and configured. For example, the Production sample specifies four groups: ORA_GRP1, ORA_GRP2, APP_GRP1, and APP_GRP2. These groups need to be configured, and the machines where they run need to be identified.

Listing 3-7 shows the GROUPS section of the Production sample UBBCONFIG file. Notice how the names in the GROUPS section match the group names specified in the ROUTING section; this is critical for factory-based routing to work correctly. Furthermore, any change in the way groups are configured in an application must be reflected in the ROUTING section. (Note that the Production sample packaged with the BEA Tuxedo software is configured to run entirely on one machine. However, you can easily configure this application to run on multiple machines.)

Listing 3-7 Production Sample GROUPS Section

*GROUPS

APP_GRP1
LMID = SITE1
GRPNO = 2
TMSNAME = TMS

APP_GRP2
LMID = SITE1
GRPNO = 3
TMSNAME = TMS

ORA_GRP1
LMID = SITE1
GRPNO = 4
OPENINFO = "ORACLE_XA:Oracle_XA+Acc=P/scott/tiger+SesTm=100+LogDir=.+MaxCur=5"
   CLOSEINFO = ""
TMSNAME = "TMS_ORA"

ORA_GRP2
LMID = SITE1
GRPNO = 5
OPENINFO = "ORACLE_XA:Oracle_XA+Acc=P/scott/tiger+SesTm=100+LogDir=.+MaxCur=5"

CLOSEINFO = ""
TMSNAME = "TMS_ORA"

 


CORBA Factory-based Routing in the Bankapp Sample Application

Listing 3-8 shows how the INTERFACES section extends the Bankapp sample application to use factory-based routing. The sample included with the BEA Tuxedo software does not contain these parameter settings.

Listing 3-8 Bankapp Sample INTERFACES Section

*INTERFACES
"IDL:BankApp/Teller:1.0"
FACTORYROUTING=atmID
*ROUTING
atmID
TYPE = FACTORY
FIELD = "atmID"
FIELDTYPE = LONG
RANGES = "1-5:BANK_GROUP1,
6-10: BANK_GROUP2,
*:BANK_GROUP1
*GROUPS
SYS_GRP
LMID = SITE1
GRPNO = 1
BANK_GROUP1
LMID = SITE1
GRPNO = 2
BANK_GROUP2
LMID = SITE1
GRPNO = 3

In this example, the IDL:Bankapp/Teller interface employs a factory-based routing scheme called atmID, as defined in the ROUTING section. The example indicates that the processing will be distributed across the following two server groups:

 


How to Configure the BEA Tuxedo System to Take Advantage of Threads

To configure a multicontexted application, edit your UBBCONFIG file as usual and add those parameters, listed in the following table, that are needed for your application. Use a text editor or the BEA Tuxedo Administration Console.

Table 3-3 Setting Parameters in the Configuration File to Use Threads 

In This Section

Set These Parameters

With These Considerations.

RESOURCES

MAXACCESSERS

Optional parameter, but you must assign a value to it you want more than 50 accessers (the default number).

Each context of a multicontexted client is counted separately for licensing purposes.

NOTIFY

Optional parameter that defines the default method to be used for unsolicited notification. Valid values for multicontexted applications are:

  • DIPIN

  • THREAD

  • IGNORE

MACHINES

MAXACCESSERS

Optional parameter, but you must assign a value to it you want more than 50 accessers (the default number).

Each context of a multicontexted client is counted separately for licensing purposes.

MAXWSCLIENTS

Optional parameter.

Each context of a multicontexted Workstation client is counted separately for licensing purposes. Because the default is 0, this parameter must be set if any Workstation clients are to access the system via the machine being defined.

SERVERS

MINDISPATCHTHREADS

Optional parameter.

MAXDISPATCHTHREADS

Required parameter in multithreaded servers.

When making an existing server multithreaded, an experienced programmer must verify that the source code for the server has been written in a thread-safe manner. In other words, it is not possible to convert a single-threaded server, written with static variables, to a multithreaded server simply by increasing the value of MAXDISPATCHTHREADS in the configuration file. This server must also be built for multithreading.

THREADSTACKSIZE

Optional parameter.

You may need to set it if your server dispatch threads require an especially large stack.

The default, 0, should be sufficient for most applications. (Keep in mind that when 0 is passed to the operating system, the operating system invokes its own default.)


 

 


How to Compile a Configuration File

Compiling a configuration file means generating a binary version of the file (TUXCONFIG) from the text version (UBBCONFIG). To compile a configuration file, run the tmloadcf command. tmloadcf parses a UBBCONFIG file and loads the binary file.

tmloadcf reads a file (or standard input written in UBBCONFIG syntax), checks the syntax, and optionally loads a binary configuration file called TUXCONFIG. The TUXCONFIG and (optionally) TUXOFFSET environment variables point to the TUXCONFIG file and (optional) offset where the information should be stored. You can run tmloadcf only on the machine designated as MASTER in the RESOURCES section of the UBBCONFIG file, unless the -c or -n option is specified.

Notes: The user identifier (UID) of the person running tmloadcf must match the UID, if specified, in the RESOURCES section of the UBBCONFIG file.

The pathname specified for the TUXCONFIG environment variable must match exactly (including case) the pathname specified for TUXCONFIG parameter within the MACHINES section of the UBBCONFIG file. Otherwise, tmloadcf(1) cannot be run successfully.

 

Skip navigation bar  Back to Top Previous Next