Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs.bea.com   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
WebLogic Enterprise Doc Home   |   Administration Topics   |   Previous Topic   |   Next Topic   |   Contents   |   Index

This topic includes the following sections:

• About the Configuration File

• Administrative Requirements and Performance

• Configuring Resources

• Configuring Machines

• Configuring Groups

• Configuring Servers

• Configuring Modules

• Configuring Services (BEA Tuxedo System)

• Configuring Interfaces (BEA WebLogic Enterprise Servers)

• Configuring Routing

• Configuring Network Information

The configuration file is the primary way to define the configuration of BEA WebLogic Enterprise applications. It consists of parameters that the BEA WebLogic Enterprise software interprets to create an executable application.

This file is usually created by programmers who develop and build BEA WebLogic Enterprise applications. Administrators modify the configuration file as necessary to satisfy application and system requirements.

In addition to the configuration file, you need the following three basic components to build a BEA WebLogic Enterprise application:

• A server application that performs the operations requested by the client.

• A client application that issues the operation requests to the server application.

• The development commands that you use to build the client and server executables.

Forms of the Configuration File

The configuration file exists in two forms:

UBBCONFIG

The UBBCONFIG file is an ASCII version of the configuration file. You can create and edit this version with any editor. Sample configuration files are provided with each of the BEA WebLogic Enterprise sample applications, including the simple sample-Simpapp. You must create a UBBCONFIG file for each new application. You can use any of the sample UBBCONFIG files as a starting point and edit it to meet the requirements of your particular application. The syntax used for entries in the file is described in detail in the ubbconfig(5) reference pages in the BEA Tuxedo Reference Manual.

TUXCONFIG

The TUXCONFIG file is a binary version of the configuration file that you generate from the ASCII version using the tmloadcf(1) command. You cannot create this file directly; a UBBCONFIG file must be created first. You can, however, use the tmconfig(1) command to edit many of the parameters in this file while the application is running.

The TUXCONFIG file contains information used by tmboot(1) to start the servers and initialize the Bulletin Board of a BEA Tuxedo system Bulletin Board instantiation in an orderly sequence. The tmadmin(1) command line utility uses the configuration file (or a copy of it) to carry out monitoring activities. The tmshutdown(1) command references the configuration file for information needed to shut the application down.

Note: When tmloadcf(1) is executed, the TUXCONFIG environment variable must be set to the full pathname of the device or system file where TUXCONFIG is to be loaded.

The configuration file can contain up to ten specification sections and many different parameters. Lines beginning with an asterisk (*) indicate the beginning of a specification section and the name of the section immediately follows the asterisk.

Supported section names and their functions are as follows:

• RESOURCES-specifies system-wide resources, such as the number of machines, servers, server groups, services, and network groups that can exist within a service area. (Required)

• MACHINES-specifies the logical names for physical machines for the configuration and parameters specific to a given machine. (Required)

• GROUPS-defines all application server groups by group name, logical machine, and group number. (Required)

• SERVERS-specifies server processes to be booted in the application. (Optional)

  Note: While the SERVERS section is not required, an application without this section has no application servers and so little functionality that it is not practical to leave this section out. The following warning is issued if this section is not supplied: Missing Servers Section.

• SERVICES-defines parameters for BEA Tuxedo services used by the application. (Required)

• INTERFACES-defines application-wide, default parameters for CORBA interfaces used by the application. (Optional)

• ROUTING-defines the routing criteria named in the INTERFACES section for BEA WebLogic Enterprise factory-based routing, or in the SERVICES section for BEA Tuxedo data-dependant routing. (Optional)

• NETGROUPS-specifies the network groups available to an application in a LAN environment. (Optional)

• NETWORK-describes the network configuration for a LAN environment. (Optional)

• JDBCCONNPOOLS-describes the pooling of JDBC connections for Java servers. (Optional)

Each of these topics and the associated parameters are discussed in the following sections of this document. Also, the syntax used for entries in this file is described in detail in the ubbconfig(5) reference pages in the BEA Tuxedo Reference Manual.

These sections must be arranged in the file as follows:

• The RESOURCES and MACHINES sections must appear as the first two sections, in that order.

• The GROUPS section must precede the SERVERS, SERVICES, INTERFACES, and ROUTING sections.

• The NETGROUPS section must precede the NETWORK section.

• The SERVERS section must be precede the JDBCCONNPOOLS section

For all sections except the RESOURCES section you can:

• Specify multiple entries, each with its own selection of parameters.

• Make use of a DEFAULT parameter to specify parameters that repeat from one entry to the next. For example, in the SERVERS section in Listing 3-1, the default specified for all servers is that if a server crashes, it will be restarted up to 5 times in 24 hours.

Sample UBBCONFIG File

Listing 3-1 shows a basic UBBCONFIG file. This is the UBBCONFIG file used for the University Basic sample application that is provided with the BEA WebLogic Enterprise software.

This file contains configuration information in four sections: RESOURCES, MACHINES, GROUPS, and SERVERS. Each of these sections and the associated parameters are discussed in the following sections of this document. This UBBCONFIG file also contains the required SERVICES section, but this section contains no information. For more information about the syntax used for entries in the file, see the ubbconfig(5) reference pages in the BEA Tuxedo Reference Manual.

*RESOURCES
    IPCKEY    55432
    DOMAINID  university
    MASTER    SITE1
    MODEL     SHM
    LDBAL     N
#----------------------------------------------------------------
*MACHINES

#   Specify the name of your server machine
#
    PCWIZ
        LMID = SITE1

#   Pathname of your copy of this sample application.
#   Must match "APPDIR" in "setenv.cmd"
#
    APPDIR = "C:\MY_APP_DIR\basic"

#   Pathname of the tuxconfig file.
#   Must match "TUXCONFIG" in "setenv.cmd"
# 

    TUXCONFIG="C:\MY_APP_DIR\basic\tuxconfig"

#   Pathname of the BEA WebLogic Enterprise installation.
#   Must match "TUXDIR" in "setenv.cmd"
#

    TUXDIR="C:\wledir"

    MAXWSCLIENTS=10
#----------------------------------------------------------------
*GROUPS

    SYS_GRP
        LMID    = SITE1
        GRPNO   = 1

    ORA_GRP
        LMID    = SITE1
        GRPNO   = 2
#----------------------------------------------------------------
*SERVERS

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

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

# 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   = 1
        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   = 6
        CLOPT   = "-A -- -n //PCWIZ:2500"

#----------------------------------------------------------------
*SERVICES

This section provides information to assist you in administering your system.

Adhering to the following requirements is fundamental to successful system administration.

• NameManagers should coordinate their activities with each other using the BEA Tuxedo Event Broker without administrative or operations intervention. The Event Broker must be started before any servers providing the NameManager service. If the Event Broker is not configured into the application and is not running when the NameManager service is booted, the NameManager aborts its startup and writes an error message to the user log.

• At least two servers must be configured to run the NameManager service as part of any application. This requirement is to ensure that a working copy of the "name-to-IOR" mapping is always available. If the servers are on different machines, and one machine crashes, when the machine and application are restarted, the new NameManager obtains the mapping from the other NameManager. If an application is solely contained on one machine and the machine crashes, the NameManagers are rebooted as part of the application startup because the application must be rebooted. If two NameManagers are not configured in the application when a NameManager service is booted, the NameManager aborts its startup and writes an error message to the user log.

• NameManagers can be designated as either Master or Slave, the default being Slave. If a Master NameManager server is not configured in the application and is not running when a slave NameManager server starts, the server terminates itself during boot and writes an error message to the user log.

• If a NameManager service is not configured in the application when a FactoryFinder service is booted, the FactoryFinder aborts its startup and writes an error message to the user log. It is not necessary for the NameManager service to start before a FactoryFinder service because the FactoryFinder only communicates with a NameManager when a "find" request is received from an application. NameManagers, on the other hand, attempt to communicate with each other when they boot. FactoryFinders do not communicate with each other except when a request is received to find a factory that is in a remote domain.

• BEA Tuxedo Event Broker, NameManager, and FactoryFinder services must be started before any of the application-specific servers. However, if more than one Event Broker is to be configured in the application, all secondary Event Brokers must be started after all application servers are started. There is no system protocol to enforce this in an application server; therefore, you accomplish this by positioning all secondary Event Brokers after the application servers.

• The Master NameManager must be started and must be running before any application server can register a reference to a factory object. The existence of an executing Slave NameManager is not sufficient.

Reliability Requirements

This section contains information that will improve system reliability.

When application servers "die," they often fail to unregister their factories with the NameManager. In some cases, the FactoryFinder may give out object references for factories that are no longer active. This occurs because the servers containing those factories have become unavailable, have failed to unregister their factories with the NameManager, and there is no other server capable of servicing the interface for that factory.

In general, an application factory can restart shortly thereafter, and then offer the factories. However, to ensure that factory entries are not kept indefinitely, the NameManager is notified when application servers die. Upon receipt of this notification, the NameManager may remove those factory entries that are not supported in any currently active server.

At a minimum, two NameManagers, a Master and a Slave, must be configured in an application, preferably on different machines, to provide querying capabilities for a FactoryFinder. Multiple FactoryFinders should also be configured in an application.

A Master NameManager must be designated in the UBBCONFIG file. All registration activities are sent to the Master NameManager. The Master NameManager then notifies the Slave NameManagers about the updates. If the Master NameManager is down, registration/unregistration of factories is disabled until the Master restarts.

Implementing the following hint may improve system performance of the administrative servers:

• You can optimize FactoryFinder and NameManager performance by running these services on separate servers within the same machine rather than running these services on different machines. This provides a quicker response because it eliminates the need for machine-to-machine communication.

The following paragraphs explain how to set RESOURCES parameters that control the application as a whole.

RESOURCES is a required section and must appear as the first section in the configuration file. Some of the parameters in the RESOURCES section serve as system-wide defaults (UID, GID, PERM, MAXACCESSERS, MAXCONV, and MAXOBJECTS) and can be overridden on a per-machine basis.

Table 3-1 lists some of the parameters in the RESOURCES section and gives sample values for a BEA WebLogic Enterprise server application. For more detailed information about these parameters, see the ubbconfig(5) reference page in the BEA Tuxedo Reference Manual.

Table 3-1 RESOURCES Section Parameters

Parameter	Description	Sample Value	Meaning of Sample Value
IPCKEY	The address of shared memory.	39210	Indicates a number unique to this application on this system.
MAXSERVERS	IPC limit for the number of server processes.	20	Allows up to 20 active server processes for this application.
MAXINTERFACES	The IPC limit for the number of interfaces.	25	Allows up to 25 CORBA interfaces in the Bulletin Board interface tables. The MAXINTERFACES parameter is specific to the BEA WebLogic Enterprise system.
MAXSERVICES	The IPC limit for the number of services offered.	25	Allows up to 25 services to be advertised. On BEA WebLogic Enterprise systems, each CORBA interface is mapped to a BEA Tuxedo service. If you are using JavaServers, each JavaServer instance advertises two additional services.
MAXOBJECTS	The IPC limit for the number of CORBA objects.	800	Allows up to 800 BEA WebLogic Enterprise active CORBA objects in the Active Object Map tables in the Bulletin Board. The MAXOBJECTS parameter is specific to the BEA WebLogic Enterprise system.
MASTER	The administration site (MASTER) for boot and shutdown.	SITE1, SITE2	Specifying LMID SITE1 means the machine is the master. If LMID SITE2 is specified, the machine is the backup.
MODEL	Application architecture, which indicates a single machine or multiple machines application.	MP	Indicates that this application has more than one machine in the configuration.
OPTIONS	The options used.	LAN, MIGRATE	Indicates a networked application, and that the machine and servers can be migrated to alternate processors.
SECURITY	The level of security.	APP_PW	Indicates that this is a secure application; clients are required to supply a password to join.
AUTHSVC	The name of an application authentication service invoked by the system for each client joining the system.	"AUTHSVC"	Indicates that in addition to the password, clients must pass authentication from a service called "AUTHSVC".
SYSTEM_ACCESS	The default mode used by BEA Tuxedo system libraries within application processes to gain access to a BEA Tuxedo system's internal tables.	PROTECTED, FASTPATH, NO_OVERRIDE	Specifying PROTECTED means the application code does not attach to shared memory.
LDBAL	Server load balancing enabled.	Y	Indicates that load balancing is on. This value is always Y in BEA WebLogic Enterprise systems; that is, setting LDBAL to N is ignored in the BEA WebLogic Enterprise system.

The following sections describe how to set the RESOURCES section parameters.

You set the address of shared memory using the IPCKEY parameter. The BEA WebLogic Enterprise system uses this parameter to allocate application IPC resources so 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 a single processor mode, this key names the Bulletin Board; in a multiprocessor mode, this key names the message queue of the DBBL.

The IPCKEY parameter is:

• Required and must appear in the configuration file.

• Used to access the Bulletin Board and other IPC resources.

• An integer in the range 32,769 to 262,143.

• Unique. No other application on the system may use this specific value for its IPCKEY.

Specifying the Master Machine

You must specify a master machine for all configurations (MASTER). The master machine controls the booting and administration of the entire application. This machine is specified using a Logical Machine Identifier (LMID). This is an alphanumeric name chosen by the administrator. (LMIDs are discussed further in the section "Configuring Machines" .)

Two LMIDs are specified if migration of the master site is to be allowed. If it is necessary to bring down the master site without shutting down the application, it is necessary to specify the backup master site.

The MASTER parameter:

• Is required and controls booting and administration.

• Requires two LMIDs for migration to back up the MASTER machine.

Setting the Application Type

Among the architectural decisions you need to make for a BEA WebLogic Enterprise or a BEA Tuxedo application are the following:

• Should this application run on a single processor with global shared memory?

• Will the application be networked?

• Will the application support server migration?

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

Table 3-2 lists the characteristics for the MODEL and OPTIONS parameters.

Table 3-2 Model and Options Parameter Characteristics

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 multiple machines or a nonglobal shared memory multiprocessor.
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.

Note: No OPTIONS are specified for the SHM model.

The BEA WebLogic Enterprise system provides security features, but does not support access control lists (ACLs) at this time. This section applies only to BEA Tuxedo servers.

You can provide basic access to a BEA Tuxedo application using the following three parameters:

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

• GID-the numeric Group ID of the administrator.

• PERM-an octal number that specifies the permissions to assign to the IPC resources created when the application is booted. This provides the first level of security to protect the BEA Tuxedo system IPC structures against unauthorized access. The default is 0666, which gives read/write access to all. These values should be specified for production applications.

  Note: If the UID and GID parameters are not specified, they default to the IDs of the person who runs the tmloadcf(1) command on the configuration, unless they are overridden in the MACHINES section.

Table 3-3 lists the UID, GID, and PERM parameters characteristics.

Table 3-3 Access Control Parameters Characteristics

Parameter	Characteristics
UID	The user ID of the administrator. The default is the ID of the person who runs tmloadcf(1). Example: UID=3002 On Windows NT, this value is always 0.
GID	The group ID of the administrator. The default is the ID of the person who runs tmloadcf(1). Example: GID=100 On Windows NT, this value is always 0.
PERM	The permissions for access to IPC structures. The default is 0666. Example: PERM=0660 On Windows NT, this value is always 0.

Note: You can overwrite values on remote machines.

Because most 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 consumed to excess; if they are set too small, the process fails when the limits are eclipsed.

Currently, the following tunable parameters are related to IPC sizing in the RESOURCES section:

• MAXACCESSERS-the maximum number of overall processes allowed to be attached to the BEA WebLogic Enterprise or BEA Tuxedo system at one site. This number is not the sum of all processes, but is equal to the number at the site that has the most processes. The default is 50. (You can overwrite MAXACCESSERS on a per-machine basis in the MACHINES section.)

  The MAXACCESSERS parameter sets the maximum number of concurrent accessors of a BEA WebLogic Enterprise system. Accessors include native and remote clients, servers, and administration processes.

  A single-threaded server counts as one accessor.

  For multithreaded BEA WebLogic Enterprise JavaServers, you must account for the number of worker threads that each server is configured to run. A worker thread is a thread that is started and managed by the BEA WebLogic Enterprise Java software, as opposed to threads started and managed by an application program. Internally, BEA WebLogic Enterprise Java manages a pool of available worker threads. When a client request is received, an available worker thread from the thread pool is scheduled to execute the request. When the request is completed, the worker thread is returned to the pool of available threads.

  For a multithreaded JavaServer, the number of accessors can be up to twice the maximum number of worker threads that the server is configured to run, plus one for the server itself. However, to calculate a MAXACCESSERS value for a BEA WebLogic Enterprise system running multithreaded servers, do not simply double the existing MAXACCESSERS value of the whole system. Instead, you add up the accessors for each multithreaded server.

  For example, assume that you have three multithreaded JavaServers in your system. JavaServer A is configured to run three worker threads. JavaServer B is configured to run four worker threads. JavaServer C is configured to run five worker threads. The accessor requirement of these servers is calculated by using the following formula:

  [(3*2) + 1] + [(4*2) + 1] + [(5*2) + 1] = 27 accessors

• MAXSERVERS-the maximum number of server processes in the application, including all the administrative servers (for example, BBL and TMS). It is the sum of the server processes at all sites. The default is 50.

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

  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-on a BEA WebLogic Enterprise system, the maximum number of active CORBA objects to be accommodated in the Active Object Table for a particular machine at one time. Valid values are from 0 to 32766. If not specified, and if the BEA WebLogic Enterprise system is licensed for the domain, the default is 1000. The RESOURCES value for this parameter can be overridden in the MACHINES section on a per-machine basis. If the BEA WebLogic Enterprise system is not licensed, any nonzero value is replaced with a value of zero.

• MAXSERVICES-the maximum number of different services that can be advertised in the application. It is the sum of all services in the system. The default is 100.

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

  Note: On BEA WebLogic Enterprise systems, each JavaServer instance advertises five additional services. If you are running JavaServers, you may need to increase the value of MAXSERVICES to take account of these additional services.

The cost incurred by increasing MAXACCESSERS is one additional semaphore per site per accessor. 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 especially important to pay attention to the value of MAXACCESSERS.

Note: Two additional parameters, MAXGTT and MAXCONV, affect shared memory. For details, see the UBBCONFIG(5) reference page in the BEA Tuxedo Reference Manual.

Table 3-4 lists the characteristics for the MAXACCESSERS, MAXSERVERS, MAXINTERFACES, MAXOBJECTS, and MAXSERVICES parameters.

Table 3-4 IPC Sizing Parameters Characteristics

Parameter	Characteristics
MAXACCESSERS	Number of processes on the site that is running the most processes. You can overwrite the value on a per-machine basis in the MACHINES section. The cost is one additional semaphore per accesser.
MAXSERVERS	Maximum number of server processes in an application (sum of all sites). The cost is a small amount of shared memory.
MAXINTERFACES (BEA WebLogic Enterprise servers)	Maximum number of CORBA interfaces advertised in the application (sum of all active interfaces in the domain). The cost is a small amount of shared memory. Default is 100.
MAXOBJECTS (BEA WebLogic Enterprise system)	Maximum number of CORBA objects in an application (sum of all objects in the domain). The cost is a small amount of shared memory. Default is 1000. You can overwrite the value on a per-machine basis in the MACHINES section.
MAXSERVICES	Maximum number of BEA Tuxedo services advertised in the application (sum of all sites). The cost is a small amount of shared memory. Default is 100. On BEA WebLogic Enterprise systems, each CORBA interface is mapped to a BEA Tuxedo service. Make sure you account for the number of services generated.

Enabling Load Balancing

Load balancing is always enabled on BEA WebLogic Enterprise systems. On BEA Tuxedo systems, use LDBAL=Y to enable load balancing.

Note: For more information about load balancing, see the section "Enabling Load Balancing" .

You can control the number of buffer types and subtypes allowed in the application with the MAXBUFTYPE and MAXBUFSTYPE parameters, respectively. The default for MAXBUFTYPE is 16. Unless you are creating many user-defined buffer types, you can omit MAXBUFTYPE. However, if you intend to use many different VIEW subtypes, you may want to set MAXBUFSTYPE to exceed its current default of 32.

Table 3-5 lists the characteristics of the MAXBUFTYPE and MAXBUFSTYPE parameters.

Table 3-5 Buffer Type and Subtype Sizing Characteristics

Parameter	Characteristics
MAXBUFTYPE	Maximum number of buffer types allowed in the system. Default is 16. Example: MAXBUFTYPE 20
MAXBUFSTYPE	Maximum number of buffer subtypes allowed in the system. Default is 32. Example: MAXBUFSTYPE 40

Setting the Number of Sanity Checks and Timeouts

You can set the number of times the administrative server (BBL) will periodically check the sanity of servers local to its machine. In addition, you can set the number of timeout periods for blocking messages, transactions, and other system activities.

You use the SCANUNIT parameter to control the granularity of such checks and timeouts. Its value (in seconds) can be a positive multiple of 5. Its default is 10.

You use the SANITYSCAN parameter to specify how many SCANUNITs elapse between sanity checks of the servers. The value of SANITYSCAN * SCANUNIT cannot exceed 300. The default value of SANITYSCAN * SCANUNIT is approximately 120 seconds.

A SCANUNIT of 10 and a BLOCKTIME of 3 allows 30 seconds before the client application times out. The BLOCKTIME default is set so that BLOCKTIME * SCANUNIT is approximately 60 seconds. The time is a total of the following times:

• Time waiting to get on the queue

• Time waiting on the queue

• Time for service processing

• Time on the network

Characteristics of the SCANUNIT, SANITYSCAN, and BLOCKTIME Parameters

Table 3-6 lists the SCANUNIT, SANITYSCAN, and BLOCKTIME parameters characteristics.

Table 3-6 SCANUNIT, SANITYSCAN, and BLOCKTIME Characteristics

Parameter	Characteristics
SCANUNIT	Establishes granularity of check intervals and timeouts. Value must be in multiples of 5 seconds. The default is 10. Example: SCANUNIT 10
SANITYSCAN	Frequency at which the BBL checks the server (in SCANUNIT intervals). SCANUNIT * SANITYSCAN must not exceed 300. Default of SCANUNIT * SANITYSCAN is approximately 120 seconds. Example: SANITYSCAN 3
BLOCKTIME	Timeout for blocking messages. SCANUNIT * BLOCKTIME must not exceed 300. Default of SCANUNIT * BLOCKTIME is approximately 60 seconds. Example: BLOCKTIME 1

Setting Conversation Limits (BEA Tuxedo Servers)

You can specify the maximum number of conversations on a machine with the MAXCONV parameter.

Note: The MAXCONV parameter applies only to the BEA Tuxedo servers.

The MAXCONV parameter has the following characteristics:

• It is the maximum number of simultaneous conversations per machine.

• Its value must be greater than or equal to 0 and less than 32766.

• The default for an application that has conversational servers listed in the SERVERS section is 10; otherwise, the default is 1.

• You can overwrite this value in the MACHINES section.

Setting the Security Level

You can set three levels of security using the following parameters:

• PERM parameter-sets the first or lowest-level permission to write to the application queues.

• SECURITY parameter-sets the second-level permission. As a minimum, this level requires that the client supply a password when joining the application. This password is checked against the password supplied by the system administrator when the TUXCONFIG file is generated from the UBBCONFIG file. Optionally, this level can also require user authorization and access control list privileges.

  Note: For details about the supported security parameters, see Using Security in the BEA WebLogic Enterprise online documentation.

• AUTHSVC parameter-sets the third-level permission. This sends the client's request to join the application to an authentication service. This level requires the second level of SECURITY to be present. The authentication service may be the default supplied by the BEA Tuxedo system or it may be a service, such as a Kerberos service, supplied by another vendor.

Table 3-7 lists the SECURITY and AUTHSVC parameters characteristics.

Table 3-7 Security Level Parameters Characteristics

Parameter	Characteristics
Security	Accepted values are: NONE (default), APP_PW, USER_AUTH, ACL, and MANDATORY_ACL. The ACL and MANDATORY_ACL parameters are not supported and are ignored on machines using the BEA WebLogic Enterprise CORBA API. Default is NONE. Example: SECURITY APP_PW
AUTHSVC	The name of the authentication service. SECURITY APP_PW must be specified. Default is no authentication service. Client authentication with Kerberos is possible. Example: AUTHSVC ``AUTHSVC''

Setting Parameters of Unsolicited Notification (BEA Tuxedo Servers)

This section applies only to BEA Tuxedo servers.

You can set the default method for clients to receive unsolicited messages using the NOTIFY parameter. The client, however, can override this setting in the TPINIT structure when tpinit() is called.

The following three methods can be set for clients:

• IGNORE-ignore unsolicited messages.

• DIPIN-receive unsolicited messages only when the clients call tpchkunsol() or when they make an ATMI call.

• SIGNAL-receive unsolicited messages by having the system generate a signal that has the signal handler call the function; that is, set with tpsetunsol().

Two types of signals can be generated: SIGUSR1 and SIGUSR2. The USIGNAL parameter allows the administrator to choose the type of signal. The default is SIGUSR2. In applications that choose notification by signals, any MS-DOS client workstations are switched automatically to DIPIN.

Table 3-8 lists the NOTIFY and USIGNAL parameters characteristics.

Table 3-8 Unsolicited Notification Parameters Characteristics

Parameter	Characteristics
NOTIFY	Value of IGNORE means clients should ignore unsolicited messages. Value of DIPIN means clients should receive unsolicited messages by dip-In. Value of SIGNAL means clients should receive unsolicited messages by signals. Default is DIPIN. Example: NOTIFY SIGNAL
USIGNAL	Value of SIGUSR1 means notify clients with this type of signal. Value of SIGUSR2 means notify clients with this type of signal. Default is SIGUSR2. Example: USIGNAL SIGUSR1

Protecting Shared Memory

You can shield system tables kept in shared memory from application clients or servers using the SYSTEM_ACCESS parameter. This option is useful when applications are being developed because faulty application code can inadvertently corrupt shared memory with a bad pointer. When the application is fully debugged and tested, this option could then be changed to allow for faster responses. The following are the options for this parameter:

• PROTECTED-BEA WebLogic Enterprise or BEA Tuxedo libraries compiled with application code will not attach to shared memory while executing system code.

• FASTPATH-BEA WebLogic Enterprise or BEA Tuxedo libraries will attach to shared memory at all times.

• NO_OVERRIDE-the selected option cannot be changed either by the client in the TPINIT structure of the tpinit() call or in the SERVERS section for servers.

Table 3-9 lists the PROTECTED, FASTPATH, and NO_OVERRIDE parameters characteristics.

Table 3-9 Shared Memory Protection Parameters Characteristics

Parameter	Characteristics
PROTECTED	Internal structures in shared memory will not be corrupted inadvertently by application processes.
FASTPATH (default)	Application processes will join with access to shared memory at all times.

Example: SYSTEM_ACCESS PROTECTED, NO_OVERRIDE

This section explains how to define parameters for each processor, or machine, on which your application runs.

Every machine in an application must have a MACHINES section entry in the configuration file and it must be the second section in the file. The MACHINES section contains the following information specific to each machine in the application:

• The mapping of the machine address to a logical identifier (LMID). (Required)

• The location of the configuration file (TUXCONFIG). (Required)

• The location of the installed BEA WebLogic Enterprise or BEA Tuxedo software (TUXDIR). Note that the TUXDIR parameter is used on BEA WebLogic Enterprise systems. Use it to identify the top-level location where you installed the BEA WebLogic Enterprise system, such as c:\wledir. (Required)

• The location of the application servers (APPDIR). (Required)

• The location of the application log file (ULOGPFX). (Optional)

• The location of the environment file (ENVFILE). (Optional)

• The maximum number of active CORBA objects to be accommodated in the Active Object Table for this processor (MAXOBJECTS). (Optional)

  Note: For a particular machine, you can override the UID, GID, PERM, MAXACCESSERS, MAXCONV, and MAXOBJECTS values that were specified in the RESOURCES section.

Example: MACHINES Section

The following example provides a sample MACHINES section of a configuration file:

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

Table 3-10 lists the MACHINES section parameters characteristics.

Table 3-10 MACHINES Section Parameter Characteristics

Parameter	Description
gumby	The machine name obtained with the command uname -n on UNIX systems. On Windows NT systems, see the Computer Name value in the Network Control Panel.
LMID=SITE1	The logical machine identifier of the machine gumby.
TUXDIR	The double quoted string of the full path to the installed BEA WebLogic Enterprise or BEA Tuxedo software.
APPDIR	The string of the full path to the application directory, enclosed in double quotes.
TUXCONFIG	The string of the full pathname of the configuration file, enclosed in double quotes.
ENVFILE	The string of the full pathname of a file containing environment information, enclosed in double quotes.
MAXOBJECTS	Override the system wide value defined in RESOURCES with 700.
ULOGPFX	The string of the full pathname prefix of the log file, enclosed in double quotes.
MAXACCESSERS	Override the system-wide value with 100 for this machine.
MAXCONV	Override the system-wide value with 15 for this machine.

Reserving the Physical Address and Machine ID

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

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

The address and machine ID and the LMID parameter have the following characteristics:

• The address and machine ID are specified in the following way:

  hostname LMID=logical_machine_name

• hostname identifies the physical machine.

• The format of the LMID parameter is LMID=logical_machine_name.

• The LMID is the logical machine name for a physical processor.

• LMID is alphanumeric and must be unique within the MACHINES section.

Identifying the Location of the Configuration File

You identify the configuration file location and file name for the machine with TUXCONFIG, a required parameter. The TUXCONFIG parameter is enclosed in double quotes and represents the full pathname up to 64 characters. The path specified must be the same as the environment variable, TUXCONFIG; otherwise, the tmloadcf(1) will not compile the binary file.

The TUXCONFIG parameter has the following characteristics:

• The syntax of the TUXCONFIG parameter is TUXCONFIG="<tuxconfig>".

• This parameter identifies the location of the configuration file and filename (though it should remain TUXCONFIG for convention purposes) for the machine.

• The full pathname for TUXCONFIG can be up to 64 characters.

• The value of TUXCONFIG must match the TUXCONFIG environment variable.

Identifying the Locations of the System and Application Software

Each machine in an application must have a copy of the BEA WebLogic Enterprise or 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 servers with the APPDIR parameter. Both parameters are mandatory. The APPDIR parameter becomes the current working directory of all server processes. The BEA WebLogic Enterprise or BEA Tuxedo software looks in the TUXDIR/bin and APPDIR for executables.

Table 3-11 lists the TUXDIR and APPDIR parameters characteristics.

Table 3-11 System Software Location Parameters Characteristics

Parameter	Characteristics
TUXDIR	The syntax requires the full pathname in a string enclosed in double quotes: TUXDIR="<TUXDIR>". Identifies the location of the BEA WebLogic Enterprise or BEA Tuxedo software. Is a required parameter.
APPDIR	The syntax requires the full pathname in a string enclosed in double quotes: APPDIR="<APPDIR>". Identifies the location of application servers. Is a required parameter. Becomes the current working directory of server processes.

Identifying the User Log File Location

The user log file contains warning and informational messages, as well as error messages that describe the nature of any ATMI error with a return code of TPESYSTEM and TPEOS (that is, underlying system errors). The user can use this log to track application-related errors. By default, the file is named ULOG.mmddyy where mmddyy is the month, date, and two-digit year. By default, the file is written into the APPDIR.

You can override the default directory and prefix by specifying the ULOGPFX parameter which is the absolute pathname of the application log file, without the date. For example, this may be set to APPDIR/logs/ULOG so that logs collect in a particular directory. In a networked application, a central log can be maintained by specifying a remote directory that is mounted on all machines.

The ULOGPFX parameter has the following characteristics:

• The syntax of the ULOGPFX parameter is a string enclosed in double quotes: ULOGPFX="<ULOGPFX>".

• The ULOGPFX defaults to <APPDIR>/ULOG.

Examples: ULOGPFX="/usr/appdir/logs/ULOG"
ULOGPFX="/mnt/usr/appdir/logs/BANKLOG"

With the ENVFILE parameter, you can specify a file that contains environment variable settings for all processes to be booted by the BEA WebLogic Enterprise or BEA Tuxedo system. The system sets TUXDIR and APPDIR for each process, so these variables should not be specified in this file. You can specify settings for the following variables because they affect an application's operation. Most of these settings apply only to BEA Tuxedo servers, as noted.

• FIELDTBLS, FLDTBLDIR (BEA Tuxedo servers)

• VIEWFILES, VIEWDIR (BEA Tuxedo servers)

• TMCMPLIMIT (BEA Tuxedo servers)

• TMNETLOAD

The ENVFILE parameter has the following characteristics:

• The syntax of the ENVFILE parameter is a string enclosed in double quotes: ENVFILE="<envfile>".

• ENVFILE is the file containing environment variable settings for all processes booted by the BEA WebLogic Enterprise or BEA Tuxedo system.

• You can set the environment variables but do not set TUXDIR and APPDIR.

• The ENVFILE parameter is optional and all settings must be hard coded. No evaluations such as FLDTBLDIR=$APPDIR are allowed.

• The format is VARIABLE=string.

Overriding System-wide Parameters

Table 3-12 lists the system-wide parameters you can override for a specific machine.

Note: You can override values on remote as well as local machines.

Table 3-12 System-wide Parameters That Can Be Overridden

Parameter	Characteristics
UID	The user ID of the administrator. The default is the ID of the person who runs tmloadcf(1). Example: UID=3002 On Windows NT, UID value is always 0.
GID	The group ID of the administrator. The default is the ID of the person who runs tmloadcf(1). Example: GID=100 On Windows NT, this value is always 0.
PERM	The permissions for access to IPC structures. The default is 0666. Example: PERM=0660 On Windows NT, this value is always 0.
MAXACCESSERS	Number of processes on the site that is running the most processes. You can overwrite the value on a per-machine basis in the MACHINES section. The cost is one additional semaphore per accessor.
MAXOBJECTS (BEA WebLogic Enterprise system)	Maximum number of active CORBA objects in an application on any machine (sum of all active CORBA objects on the machine). The cost is a small amount of shared memory. Default is 1000. You can overwrite the value on a per-machine basis in the MACHINES section.
MAXGTT	Maximum number of simultaneous global transactions in which a particular machine can be involved.

You can use GROUPS to group servers together logically. These groupings can later be used to access resource managers, and for server group migration. The GROUPS section of the configuration file contains the definition of server groups. You must define at least one server group for a machine to have an application server running on it. If no group is defined for a machine, the machine 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 define the basic mapping of group name to group number and logical machine of each group.

The group name is an alphanumeric name by which the group is identified. It must have a unique group number (GRPNO). Each group must reside entirely on one logical machine (LMID). The LMID is also mandatory.

The example GROUPS section in Listing 3-2 is from the UBBCONFIG file in the BEA WebLogic Enterprise 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 "Example: Factory-based Routing (BEA WebLogic Enterprise Servers)" 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 WebLogic Enterprise 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.

Passwords for server groups can be stored in the UBBCONFIG file in encrypted form using the tmloadcf utility.

To secure a password in the UBBCONFIG file, you initially enter a string of five or more continuous asterisks at the place in the OPENINFO statement where a password is to go. The asterisks are a placeholder for the password. For example:

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

When tmloadcf encounters this string, it prompts the user to create a password. For example:

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

The password is stored in the TUXCONFIG in encrypted form. To place the encrypted password in the UBBCONFIG file, use tmunloadcf to generate a UBBCONFIG file. When tmunloadcf is run, the encrypted password is written into the OPENINFO string in the UBBCONFIG file 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. Instead, the tmloadcf command uploads the encrypted password back into the system.

Note: The UBBCONFIG file with the encrypted form of the password may be uploaded back into the system only once; subsequent attempts will fail.

Use of encrypted passwords is recommended for production environments.

This following paragraphs explain the SERVERS section parameters that you need to define to configure server processes.

Note: Administrators and programmers who are working in a Java environment should see the section "Starting JavaServer" .

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. Server-specific information includes the following:

• A server name, group, and numeric identifier (SRVGRP, SRVID)

• Command-line options (CLOPT)

• Parameters to determine the booting order and number of servers to boot (SEQUENCE, MIN, MAX)

• A server-specific environment file (ENVFILE)

• JavaServer information (JAR file and options)

• Server queue-related information (RQADDR, RQPERM, REPLYQ, RPPERM) (BEA Tuxedo servers)

• Restart information (RESTART, RCMD, MAXGEN, GRACE)

• Server designation as a conversational server (CONV) (BEA Tuxedo servers)

• Overriding of system-wide shared memory access (SYSTEM_ACCESS)

• Setting Security Parameters for ISL Servers

Command-line options supported by the BEA Tuxedo system are described on the servopts(5) reference page in the BEA Tuxedo Reference Manual.

Table 3-13 provides a sample of parameters and their values in the SERVERS section of the configuration file.

Table 3-13 SERVERS Section Parameters

Parameter Example	Meaning
RESTART=Y	Restart the servers.
MAXGEN=5	The MAXGEN parameter specifies a number greater than 0 and less than 256 that controls the number of times the 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 greater than or equal to 2. The number of restarts is at most number minus 1 times. RESTART must be Y or MAXGEN is ignored.
GRACE=3600	If RESTART is Y, the GRACE parameter specifies the time period (in seconds) during which this server can be restarted as MAXGEN minus 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	There is no reply queue.
CLOPT="-A"	Specify -A on the command line of each server.
ENVFILE="/usr/home/envfile"	Read environment settings from the file ENVFILE.
SYSTEM_ACCESS= FASTPATH	Specifies the default mode used by system libraries within application processes to gain access to the BEA WebLogic Enterprise or BEA Tuxedo system's internal tables. Valid access types are FASTPATH or PROTECTED. FASTPATH specifies that the internal tables should be accessible by the libraries via shared memory for fast access. Note: Always use FASTPATH when you start a JavaServer. PROTECTED specifies that while the internal tables are accessible by system libraries via shared memory, the shared memory for these tables is not accessible outside of the system libraries. NO_OVERRIDE can be specified (alone, or in conjunction with FASTPATH or PROTECTED) to indicate that the mode selected cannot be overridden by an application process. If SYSTEM_ACCESS is not specified, the default mode is determined by the setting of the SYSTEM_ACCESS keyword in the RESOURCES section.

Defining Server Name, Group, and ID

You initially define the server name entry in the SERVERS section entry. The server name is the name of an executable file built with:

• buildserver(1) (BEA Tuxedo systems)

• buildobjserver (BEA WebLogic Enterprise C++ server applications)

• buildjavaserver (BEA WebLogic Enterprise Java server application)

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

Table 3-14 lists the servername, SRVGRP, and SRVID parameters characteristics:

Table 3-14 Servername, SRVGRP, and SRVID Parameters Characteristics

Parameter	Characteristics
servername	Identifies the executable to be booted. Is built with buildserver(1) on BEA Tuxedo systems, or with buildobjserver (C++) or buildjavaserver (Java) on BEA WebLogic Enterprise systems. Is required, but may not be unique.
SRVGRP	Identifies the group affiliation. The group name from a GROUPS section entry.