HOME | SITE MAP | SEARCH | CONTACT | GLOSSARY | PDF FILES | WHAT'S NEW
Administration | TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC | INDEX
|
|
|
BEA WebLogic Enterprise 4.2 Developer Center |
|
HOME | SITE MAP | SEARCH | CONTACT | GLOSSARY | PDF FILES | WHAT'S NEW |
||
|
Administration | TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC | INDEX |
||
This chapter discusses the following topics:
The configuration file is the primary means of defining the configuration of WLE applications. It consists of parameters that the WLE software interprets to create an executable application.
This file is usually created by programmers who develop and build WLE applications. Administrators modify the configuration file as necessary to satisfy application and system requirements.
In addition to the configuration file, building a WLE application requires three other basic components:
About the Configuration File
Build Environment
The configuration file exists in two formats:
Forms of the Configuration File
UBBCONFIG
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 WLE 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
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.
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) in its monitoring activity. 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 path name of the device or system file where UXCONFIG is to be loaded.
The configuration file can contain up to 9 specification sections and 80 different parameters. Lines beginning with an asterisk (*) indicate the beginning of a specification section. Each such line contains the name of the section immediately following the asterisk.
Allowable 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. (This section is required.)
SERVERS-specifies server processes to be booted in the application. (This section is 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. (This section is required.)
NETWORK-describes the network configuration for a LAN environment. (This section is optional.)
Each of these sections 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 The sections must be arranged in the file as follows:
ubbconfig(5) reference pages in the BEA TUXEDO Reference Manual.
Formatting Requirements and Guidelines
RESOURCES and MACHINES sections must be the first two sections, in that order.
GROUPS section must be ahead of the SERVERS, SERVICES, INTERFACES, and ROUTING sections.
Additionally, the following guidelines apply to all sections except the RESOURCES section:
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.
Listing 3-1 shows a basic Notice that this file contains configuration information in four sections: Sample UBBCONFIG File
UBBCONFIG file. This is the UBBCONFIG file used for the University Basic sample application that is provided with the WLE software. Examine the content of this sample file.
RESOURCES, MACHINES, GROUPS, and SERVERS. Each of these sections and the associated parameters are discussed in the following sections of this document. Notice that the UBBCONFIG file also contains the required SERVICES section, but that section contains no information. Also, the syntax used for entries in the file is described in detail in the ubbconfig(5) reference pages in the BEA TUXEDO Reference Manual.
Listing 3-1
University Basic Sample Application UBBCONFIG File (
ubb_b.nt)
*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 WLE 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:
Adhering to the following requirements will improve system reliability:
Implementing the following hint may improve system performance of the administrative servers:
This section explains how to set Table 3-1 lists some of the parameters in the
The following sections describe how to set the You set the address of shared memory using the The IPCKEY parameter has the following characteristics:
Configuring RESOURCES
RESOURCES parameters that control the application as a whole. This is a required section and must appear as the first section in the configuration file. Some of the parameters in this section serve as system-wide defaults (UID, GID, PERM, MAXACCESSERS, MAXCONV, and MAXOBJECTS) and can be overridden on a per-machine basis.
RESOURCES section and gives sample values for a WLE 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
RESOURCES section parameters.
Setting the Address of Shared Memory
IPCKEY parameter. This parameter is used by the WLE 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 a single processor mode, this key names the Bulletin Board; in a multiprocessor mode, this key names the message queue of the DBBL.
IPCKEY.
You must specify a master machine for all configurations ( Two The MASTER parameter has the following characteristics:
Identifying the Master Machine
MASTER). The master machine controls the booting and administration of the entire application. This machine is specified as a Logical Machine Identifier (LMID). This is an alphanumeric name chosen by the administrator. (LMIDs are discussed further in the section "Configuring Machines" on page 3-24.)
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.
LMIDs are required for migration to back up the master machine.
Among the architectural decisions needed for a WLE or a BEA TUXEDO application are the following:
Setting the Application Type
The The Table 3-2 lists the characteristics for the MODEL and OPTIONS parameters.
Note:
No The WLE system provides security features, but does not support access control lists (ACLs) at this time. This section is specific to BEA TUXEDO servers.
You can provide basic access to a BEA TUXEDO application using the following three parameters:
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.
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).
Table 3-2
Model and Options Parameter Characteristics
Parameter
Characteristics
MODEL
OPTIONS
OPTIONS are specified for the SHM model.
Defining Access Control (BEA TUXEDO Servers)
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.
Note:
If the
Note:
You can overwrite values on remote machines.
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.
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 Defining IPC Limits
RESOURCES section:
MAXACCESSERS-the maximum number of overall processes allowed to be attached to the WLE or BEA TUXEDO system at one site. It 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.)
For multithreaded WLE 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 WLE Java software, as opposed to threads started and managed by an application program. Internally, WLE 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 done, the worker thread is returned to the pool of available threads.
The A single threaded server counts as one accessor.
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 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:
MAXACCESSERS parameter sets the maximum number of concurrent accessors of a WLE system. Accessors include native and remote clients, servers, and administration processes.
MAXACCESSERS value for a WLE 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.
[(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.
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 WLE 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 32,766. If not specified, and if the WLE 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 WLE system is not licensed, any nonzero value is replaced with a value of zero.
The cost incurred by increasing
Note:
Two additional parameters, Table 3-3 lists the characteristics for the MAXACCESSERS, MAXSERVERS, MAXINTERFACES, MAXOBJECTS, and MAXSERVICES parameters.
Load balancing is always enabled on WLE systems. On BEA TUXEDO systems, use
Note:
For more information about load balancing, see the section "Enabling Load Balancing" on page 3-60.
You can control the number of buffer types and subtypes allowed in the application with the The MAXBUFTYPE and MAXBUFSTYPES parameters have the following characteristics:
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 You use the A 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 more important to scrutinize MAXACCESSERS.
MAXGTT and MAXCONV, affect shared memory. For details, see the UBBCONFIG(5) reference page in the BEA TUXEDO Reference Manual.
Table 3-3 IPC Sizing Parameters Characteristics
Enabling Load Balancing
LDBAL=Y to enable load balancing.
Setting Buffer Type and Subtype Limits
MAXBUFTYPE and MAXBUFSTYPE parameters, respectively. The current 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.
Setting the Number of Sanity Checks and Timeouts
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.
SANITYSCAN parameter to specify how many SCANUNITs elapse between sanity checks of the servers. It must not be set so that SANITYSCAN * SCANUNIT exceeds 300; its current default is set so that SANITYSCAN * SCANUNIT is approximately 120 seconds.
Example: Setting Sanity Checks and Timeouts
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:
The SCANUNIT, SANITYSCAN, and BLOCKTIME parameters have the following characteristics:
You can specify the maximum number of conversations on a machine with the
Note:
The The MAXCONV parameter has the following characteristics:
Characteristics of the SCANUNIT, SANITYSCAN, and BLOCKTIME Parameters
Setting Conversation Limits (BEA TUXEDO Servers)
MAXCONV parameter.
MAXCONV parameter is specific to the BEA TUXEDO servers.
You can set the following three levels of security:
Setting the Security Level
PERM parameter - sets the first or lowest-level permission to write to the application queues.
Note:
The WLE CORBA API does not support access control lists (ACLs) at this time. The SECURITY MANDATORY_ACL parameter is ignored in WLE systems. For details about the supported security parameters, see Chapter 14, "Securing Applications."
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.
The SECURITY and AUTHSVC parameters have the following characteristics:
This section is specific to BEA TUXEDO servers.
You can set the default method for clients to receive unsolicited messages using the Following are three possible methods:
Setting Parameters of Unsolicited Notification (BEA TUXEDO Servers)
NOTIFY parameter. The client, however, can override this choice in the TPINIT structure when tpinit() is called.
IGNORE-clients should ignore unsolicited messages.
Two types of signals can be generated: The NOTIFY and USIGNAL parameters have the following characteristics:
You can shield system tables kept in shared memory from application clients and/or servers using the 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.
Characteristics of the NOTIFY and USIGNAL Parameters
Protecting Shared Memory
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. Following are the options for this parameter:
PROTECTED-WLE or BEA TUXEDO libraries compiled with application code will not attach to shared memory while executing system code.
FASTPATH-WLE or BEA TUXEDO libraries will attach to shared memory at all times.
The PROTECTED, FASTPATH, and NO_OVERRIDE parameters have the following characteristics:
Note:
An example: 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 SYSTEM_ACCESS PROTECTED, NO_OVERRIDE
Configuring Machines
Identifying Machines in the MACHINES Section
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:
LMID).
TUXCONFIG).
APPDIR).
ULOGPFX).
The only required parameters for the
Note:
For a particular machine, you can override the The following example provides a sample MACHINES section of a configuration file:
*MACHINES The following table provides a sample of parameters and their values in the
You initially define the address in the address portion, which is the basis for a The The address and machine ID and the LMID parameter have the following characteristics:
MACHINES section are LMID, TUXCONFIG, TUXDIR and APPDIR.
UID, GID, PERM, MAXACCESSERS, MAXCONV, and MAXOBJECTS values that were specified in the RESOURCES section.
Example: MACHINES Section
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
Description of Parameters in a Sample MACHINES Section
MACHINES section of the configuration file.
Reserving the Physical Address and Machine ID
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.
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.
<address> LMID=<logical_machine_name>
LMID parameter is LMID=<logical_machine_name>.
LMID is the logical machine name for a physical processor.
LMID is alphanumeric and must be unique within the MACHINES section.
You identify the configuration file location and file name for the machine with The TUXCONFIG parameter has the following characteristics:
Identifying the Location of the Configuration File
TUXCONFIG, a required parameter. The TUXCONFIG parameter is enclosed in double quotes and represents the full path name 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.
TUXCONFIG parameter is TUXCONFIG="<tuxconfig>".
TUXCONFIG can be up to 64 characters.
TUXCONFIG must match the TUXCONFIG environment variable.
Each machine in an application must have a copy of the WLE or BEA TUXEDO system software and application software. You identify the location of system software with the The TUXDIR and APPDIR parameters have the following characteristics:
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 You can override the default directory and prefix by specifying the The ULOGPFX parameter has the following characteristics:
Identifying the Locations of the System Software and Application Server Machines
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 WLE or BEA TUXEDO software looks in the TUXDIR/bin and APPDIR for executables.
Identifying the Location of the User Log File
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 2-digit year. By default, the file is written into the APPDIR.
ULOGPFX parameter that is the absolute path name of the application log file, without the date. For example, it 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.
ULOGPFX parameter is a string enclosed in double quotes: ULOGPFX="<ULOGPFX>".
TPESYSTEM and TPEOS errors.
ULOGPFX defaults to <APPDIR>/ULOG.
ULOGPFX="/usr/appdir/logs/ULOG"
ULOGPFX="/mnt/usr/appdir/logs/BANKLOG"
With the Specifying Environment Variable Settings for Processes
ENVFILE parameter, you can specify a file that contains environment variable settings for all processes to be booted by the WLE 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 because they affect an application's operation. Most of these settings are specific to BEA TUXEDO servers, as noted.
FIELDTBLS, FLDTBLDIR (BEA TUXEDO servers)
VIEWFILES, VIEWDIR (BEA TUXEDO servers)
The ENVFILE parameter has the following characteristics:
ENVFILE parameter is a string enclosed in double quotes: ENVFILE=``<envfile>''
FIELDTBLS, FLDTBLDIR, and so on, but do not set TUXDIR and APPDIR.
Table 3-4 lists the system-wide parameters you can override for a specific machine.
Note:
You can override values on remote machines.
You can use 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. Additional flexibility is available to support distributed transactional systems.
The group name is the basis for a The example The Production sample specifies four groups: Overriding System-wide Parameters
Table 3-4 System-wide Parameters That Can Be Overridden
Configuring Groups
GROUPS to group servers together logically, which 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 application servers 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.
Specifying a Group Name, Number, and LMID
GROUPS section entry and is an alphanumeric name by which the group is identified. It is given a mandatory, unique group number (GRPNO). Each group must reside wholly on one logical machine (LMID). The LMID is also mandatory.
Sample GROUPS Section
GROUPS section in Listing 3-2 is from the UBBCONFIG file in the WLE 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.
ORA_GRP1, ORA_GRP2, APP_GRP1, and APP_GRP2. These groups need to be configured, and the machines on which they run on need to be identified.
Listing 3-2
Example Groups Section
*GROUPS
APP_GRP1
LMID = SITE1
GRPNO = 2
TMSNAME = TMS
APP_GRP2
LMID = SITE1
GRPNO = 3
TMSNAME = TMS
ORA_GRP1
LMID = SITE1
GRPNO = 4OPENINFO = "ORACLE_XA:Oracle_XA+Acc=P/scott/tiger+SesTm=100+LogDir=.+MaxCur=5"
CLOSEINFO = ""
TMSNAME = "TMS_ORA"
ORA_GRP2
LMID = SITE1
GRPNO = 5OPENINFO = "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 in the University Production Sample Application (WLE Servers)" on page 3-63 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 WLE 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.
This section explains 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 especially the section "Starting the Java Server" on page 3-38.
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:
SRVGRP, SRVID)
SEQUENCE, MIN, MAX)
ENVFILE)
RQADDR, RQPERM, REPLYQ, RPPERM) (BEA TUXEDO servers)
RESTART, RCMD, MAXGEN, GRACE)
CONV) (BEA TUXEDO servers)
SYSTEM_ACCESS)
Command-line options supported by the BEA TUXEDO system are described on the Table 3-5 provides a sample of parameters and their values in the
You initially define the server name entry in the servopts(5) reference page in the BEA TUXEDO Reference Manual.
SERVERS section of the configuration file.
Table 3-5 SERVERS Section Parameters
Defining Server Name, Group, and ID
SERVERS section entry, which is the name of an executable file built with:
buildserver(1), on BEA TUXEDO systems
You must provide each server with a group identifier ( The
The server may need to obtain information from the command line. The
Note:
On BEA TUXEDO systems only, you alternatively can pass user-defined options to the
The following table provides a partial list of the available options.
Note:
You can find other standard 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.
Server Name, SRVGRP, and SRVID parameters have the following characteristics:
Using Server Command-Line Options
CLOPT parameter allows you to specify command-line options that can change some defaults in the server.
tpsvrinit() function. The standard main() of a server parses one set of options ending with the argument --, and passes the remaining options to tpsvrinit().
main() of a server parses the set of options ending with the argument --; it passes the remaining user-defined options to tpsvrinit() on BEA TUXEDO servers, the Server::initialize operation on WLE C++ servers, or the Server.initialize method on WLE Java servers.main() options in the servopts(5) reference page in the BEA TUXEDO Reference Manual.
Server Command-Line Options
CLOPT="servopts -- application_opts".
main() and tpsvrinit() use server command-line options (BEA TUXEDO servers only).
servopts(5) options are passed to main() (BEA TUXEDO servers only).
tpsvrinit() (BEA TUXEDO servers only).
In the WLE Java system, a server application is represented by a Java Archive (JAR). The JAR must be loaded in the Java Virtual Machine (JVM) to be executed. This JVM must execute in a WLE server to be integrated in a WLE application. By default, the server that loads the JVM is called You include the options to start See the section "Required Order in Which to Boot Servers (WLE Servers)" on page 3-45 for important information about starting the WLE servers in the correct order.
The WLE Java system supports the ability to configure multithreaded WLE applications written in Java. A multithreaded WLE Java server can service multiple object requests simultaneously, while a single-threaded WLE Java server runs only one request at a time.
You can establish the number of threads for a Java server application by using the For related information about the Running the WLE Java server in multithreaded mode or in single-threaded mode is transparent to the application programmer. In the current version of WLE Java, you should not establish multiple threads in your object implementation code.
Programs written to WLE Java run without modification in both modes.
The potential for a performance gain from a multithreaded JavaServer depends on:
Starting the Java Server
JavaServer.
JavaServer in the SERVERS section of the application's UBBCONFIG file.
Threading Options
-M option to the JavaServer parameter in the SERVERS section. The -M options are described in the section "WLE System Options" on page 3-41.
MAXACCESSERS parameter, see the section "Defining IPC Limits" on page 3-15.
If the application is running on a single-processor machine and the application is CPU-intensive only, without any I/O or delays, in most cases the multithreaded JavaServer will not perform better. In fact, due to the overhead of switching between threads, the multithreaded JavaServer in this configuration may perform worse than a single-threaded JavaServer.
A performance gain is more likely with a multithreaded JavaServer when the application has some delays or is running on a multi-processor machine.
Note:
If your application uses JNI code to access ATMI,
When you start The JavaServer must be configured as single-threaded.
SYSTEM_ACCESS=FASTPATH is set for the JavaServer. Do not use SYSTEM_ACCESS=PROTECTED with JavaServer. (If SYSTEM_ACCESS is not specified in the SERVERS section, the default mode is determined by the setting of the SYSTEM_ACCESS keyword in the RESOURCES section.)buildXAJS, the server supports only the single-threaded mode; in this case, the WLE system ignores the -M number command line argument for multithreading. ULOG, it is not helpful to use the process ID to distinguish among the different threads. Instead, you can include in each message the object ID, the thread name, and (if your object is transactional) the transaction ID. JavaServer Command Line Options
JavaServer, the options are:
JavaServer
SRVGRP=group
SRVID=number
CLOPT="-A [java_options] archive-file [options]"JavaServer options are as follows:
group is the name of the WLE group in the GROUPS section of the UBBCONFIG file.
number is a numeric identifier of the server in the group.
java_options are Java Virtual Machine (JVM) options, similar to the options that are passed to the java interpreter command. These options are described in the sections "Standard Java Options," "WLE System Options," and "Nonstandard Java Options."
[options] after the archive file name are passed to the application via the com.beasys.Tobj.Server.initialize operation. These options are described in the sections "Standard Java Options," "WLE System Options," and "Nonstandard Java Options."
For example:
In this example, the JavaServer for Bankapp's TellerFactory interface is started. The A worker thread is a thread that is started and managed by the WLE Java software, as opposed to threads started and managed by an application program. Internally, WLE 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 done, the worker thread is returned to the pool of available threads.
The standard Java options are shown in the following list.
JavaServer
SRVGRP=BANK_GROUP1
SRVID=8
CLOPT="-A -- -M 10 Bankapp.jar TellerFactory_1"
SYSTEM_ACCESS=FASTPATH-M 10 option enables multithreading for the JavaServer and specifies 10 as the maximum number of worker threads that a particular instance of JavaServer can support.
Standard Java Options
-cp, -classpath path
JavaServer uses to look up classes. Overrides the default or the CLASSPATH environment variable if it is set.
-verbose, -verbose:class
JavaServer to print a message to the user log each time a class file is loaded.
-verbose:gc
-verbose:jni
-DpropertyName=newValue
propertyName is the name of the property whose value you want to change and newValue is the value to change it to.
The following options are provided by the WLE system:
-M number
JavaServer and specifies the maximum number of worker threads that a particular instance of JavaServer can support. The largest number that you can specify is 500.
-M 0 (zero) means that there are no worker threads and that all application code is executed in the single infrastructure thread.
-M 1 is not useful because there is only one worker thread, which does not provide significant processing parallelism.
-M is a negative decimal, the server will revert to single-threaded mode. If the number after -M is larger than 500, the server will use a maximum of 500 worker threads. In all cases, if the number specified is invalid, the WLE software logs a warning message to the application's ULOG file.
-noredirect
System.out and System.err streams to be redirected to the $APPDIR/stdout and $APPDIR/stderr files, respectively. If -noredirect is not specified, the System.out and System.err streams are redirected to the user log (ULOG).
The Java Virtual Machine (JVM) in JDK 1.2 supports the nonstandard options in the following list. To display the nonstandard Java options, use the java -x command at a system prompt.
-Xdebug
CLOPT = "-A -- -Xbootclasspath:d:\jdk1.2\lib\tools.jar;d:\jdk1.2\jre\lib\rt.jar -Djava.compiler=NONE -Xdebug BankApp.jar TellerFactory_1"
Note:
When -Xdebug is specified in the command line options, JavaServer prints a password in the user log, which must be used when starting the debugging session.
-Xmxx
x. The default is 16 megabytes of memory. x must be greater than or equal to 1000 bytes. The maximum memory size must be greater than or equal to the startup memory size (specified with the -Xms option, default 16 megabytes). By default, x is measured in bytes. You can specify x in kilobytes or megabytes by appending the letter "k" for kilobytes or the letter "m" for megabytes.
-Xmsx
x. The default is 1 megabyte of memory. x must be greater than 1000 bytes. The startup memory size must be less than or equal to the maximum memory size (specified with the -Xmx option, default 16 megabytes). By default, x is measured in bytes. You can specify x in kilobytes or megabytes by appending the letter "k" for kilobytes or the letter "m" for megabytes.
-Xnoclassgc
-Xbootclasspath:bootclasspath
-Xrs
-Xcheck:jni
-Xrunhprof[:help]|[:suboption=value,...]
java -Xrunhprof:help to obtain a list of suboptions and their default values.
You can specify the sequence of servers to be booted with the SEQUENCE parameter, which is a number in the range of 1 to 10,000. A server given a smaller SEQUENCE value is booted before a server with a larger value. If two servers have the same SEQUENCE value, they are booted simultaneously (that is, the second server can be started before the first server is finished booting).
If no servers specify SEQUENCE, servers are booted in the order of their appearance within the SERVERS section. If there is a mixture of sequenced and unsequenced servers, the sequenced servers are booted first. Servers are shut down in reverse order of the way they were booted.
This is an optional parameter. The SEQUENCE parameter may be helpful in a large application where control over the order is important. Also, the parallel booting may speed the boot process.
Warning: On a WLE system, there is a strict order in which the WLE system Event Broker, the WLE FactoryFinder object, and the application factories must be booted. A WLE application program will not boot if the order is changed. See the section "Required Order in Which to Boot Servers (WLE Servers)" on page 3-45 for details.
You can boot multiple servers using the MIN parameter, which is a shorthand method of booting. The servers all share the same server options. On a BEA TUXEDO system, if you specify RQADDR, the servers will form an MSSQ set (not supported on a WLE system). The default for MIN is 1.
You specify the maximum number of servers that can be booted with the MAX parameter. The tmboot(1) command boots up to 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 large applications to keep the size of the configuration file manageable. Allowances for MAX values must be made in the IPC resources.
The SEQUENCE, MIN, and MAX parameters have the following characteristics:
The following is the correct order in which to boot the servers on a WLE system. A WLE application program will not boot if the order is changed.
TMSYSEVT.
TMFFNAME server with the -F option, to start the FactoryFinder object.
Listing 3-3 shows the order in which servers are booted for the WLE University Basic application, which is one of the sample applications included with the WLE software. This SERVERS section is from an edited version of the ubb_b.nt configuration file.
Listing 3-3 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 Event Broker. This event broker
# must be started before any servers providing the
# NameManager Service
#
TMSYSEVT
SRVGRP = SYS_GRP
SRVID = 1
# TMFFNAME is a BEA WLE provided server that
# runs the NameManager and FactoryFinder services.
# The NameManager service is a BEA WLE-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:
CLOPT parameter), see Chapter 8, "Managing Interface Repositories (WLE System)."
CLOPT parameter, see Chapter 12, "Managing Remote Client Applications (WLE Systems)."
You use the The server environment file has the following characteristics:
Identifying the Location of the Server Environment File
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.
ENVFILE parameter in the MACHINES section, but for one server only.
Server Queue information controls the creation and access of server message queues. On a BEA TUXEDO system, you can create multiple server single queue (
Note:
MSSQ sets are not supported on a WLE system.
The The If the service routines within an The RQADDR, RQPERM, REPLYQ, and RPPERM parameters have the following characteristics:
A properly debugged server should not terminate on its own. By default, servers that do terminate while the application is booted will not be restarted by the BEA TUXEDO system. You can set the The The
Note:
A fully debugged server should not need to be restarted. The The RESTART, RCMD, MAXGEN, and GRACE parameters have the following characteristics:
If a server is a conversational server (that is, it establishes a connection with a client), the This feature is specific to BEA TUXEDO servers.
The CONV parameter has the following characteristics:
Identifying Server Queue Information
MSSQ) sets using the RQADDR parameter. For any given server, you can set this parameter to an alphanumeric value. Those servers that offer the same set of services can consolidate their services under one message queue, providing automatic load balancing. You can do this by specifying the same value for all members of the MSSQ set.
MSSQ Example (BEA TUXEDO Servers)
MSSQ set is similar to a situation at a bank. If you have four tellers, one line may be formed and everyone is assured of the most equitable wait in line. Understandably, the loan teller is not included because some people do not want loans on a given day. Similarly, MSSQ sets are not allowed if the participant servers offer different services from one another.
RQPERM parameter allows you to specify the permissions of server request queues, along the lines of the UNIX system convention (for example, 0666). This allows services to control access to the request queue.
MSSQ server perform service requests, they must receive replies to their requests on a reply queue. This is done 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
Defining Server Restart Information
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.
RCMD parameter specifies a command to be performed in parallel with restarting a server. This command must be an executable file. The option allows you to take some action when a server is being restarted. For example, mail could be sent to the developer of the server or to someone who is auditing such activity.
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).
RESTART and associated parameters should have different settings during the testing phase than they do during production.
Characteristics of the RESTART, RCMD, MAXGEN, and GRACE Parameters
Specifying a Server as Conversational (BEA TUXEDO Servers)
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.
Y value indicates a server is conversational; an N value indicates a server is not conversational.
Y value is required if the server is to receive conversational requests.
The This parameter overrides the value specified in the The SYSTEM_ACCESS parameter has the following characteristics:
Defining Server Access to Shared Memory
SYSTEM_ACCESS parameter determines if the server process may attach to shared memory and thus have access to internal tables outside of system code. During application development, we recommend that such access be denied (PROTECTED). When the application is fully tested, you can change it to FASTPATH to yield better performance.
RESOURCES section unless the NO_OVERRIDE value was specified. In this case, the parameter is ignored.
PROTECTED indicates that the server may not attach to shared memory outside of the system code.
FASTPATH indicates that the server will attach to shared memory at all times.
NO_OVERRIDE is specified in the RESOURCES section, this parameter is ignored.
This section is specific to BEA TUXEO systems. For information relevant to WLE systems, see the section "Configuring Interfaces (WLE Servers)" on page 3-55.
Note:
Although each WLE interface is mapped to a BEA TUXEDO service, you do not have to configure these services in the You indicate specific information about BEA TUXEDO services in your application in the Configuring Services (BEA TUXEDO System)
SERVICES section of the application's UBBCONFIG file. As the administrator, you only need to account for the generated services in the MAXSERVICES parameter in the RESOURCES section. For more information, see the section "Defining IPC Limits."
Identifying BEA TUXEDO Services in the SERVICES Section
SERVICES section of the configuration file. Such information, for nontransactional, nondistributed applications, is relatively simple. The SERVICES section includes the following types of information:
SRVGRP)
The following example provides a sample SERVICES section of a configuration file:
In this example, the default load and priority of a service are If you set the Load information is stored only on the site originating the service request. It would be inefficient for the BEA TUXEDO system to attempt to constantly 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 across sites.
When load balancing is not activated, and multiple servers offer the same service, the first available queue receives the request.
The LDBAL parameter has the following characteristics:
Sample SERVICES Section
*SERVICES
#
DEFAULT: LOAD=50 PRIO=50
RINGUP BUFTYPE="VIEW:ringup"50; the one service declared is a RINGUP service that accepts a ringup VIEW as its required buffer type.
Enabling Load Balancing
RESOURCES section parameter LDBAL to Y, server load balancing occurs. A LOAD factor is assigned to each service performed, which 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.
RESOURCES LDBAL parameter is set to Y.
You can exert significant control over the flow of data in an application by assigning service priorities using the
Note:
A priority can also be changed dynamically with the The PRIO parameter has the following characteristics:
Controlling the Flow of Data by Service Priority
PRIO parameter. 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. The system dequeues every tenth request in FIFO order to prevent a message from waiting indefinitely on the queue.
tpsprio()call.
You can specify different load, priority, or other service-specific parameters for different server groups. To do this, you should repeat the service's entry for each group with different values for the The following example provides a sample SERVICES section of a configuration file:
This example assigns different service-specific parameters to two different server groups. Service A assigns a priority of 50, and a load of 60 in server group With the A service can have The BUFTYPE parameter has the following characteristics:
This section is specific to the WLE system.
The WLE software has an In addition to defining the You indicate specific information about CORBA interfaces used by your application in the Specifying Different Service Parameters for Different Server Groups
SRVGRP parameter.
Sample SERVICES Section
*SERVICES
A SRVGRP=GRP1 PRIO=50 LOAD=60
A SRVGRP=GRP2 PRIO=70 LOAD=30GRP1; and a priority of 70, and a load of 30 in server group GRP2.
Specifying a List of Allowable Buffer Types for a Service
BUFTYPE parameter, you can tune a service to check buffer types independently of the actual service code. If you set this parameter, it specifies a list of allowable buffer types for a service. Its syntax is a semicolon-separated list of types in the format type[:subtype[,subtype]]. The subtype may be set to * to allow all subtypes.
BUFTYPE set to ALL, which means that this service accepts all buffer types. If this parameter is not specified, the default is ALL.
Examples of the BUFTYPE Parameter
Configuring Interfaces (WLE Servers)
INTERFACES section in the UBBCONFIG file. 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 WLE system should apply to each interface. Factory-based routing is a feature that allows you to distribute processing to specific server groups.
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 "Configuring Routing" in this chapter.
Specifying CORBA Interfaces in the INTERFACES Section
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:
AUTOTRAN)
FACTORYROUTING)
LOAD)
PRIO)
SRVGRP)
TRANTIME)
TIMEOUT)
The AUTOTRAN, FACTORYROUTING, LOAD, PRIO, SRVGRP, TRANTIME, and TIMEOUT parameters have the following characteristics:
For each CORBA interface, the The University Production sample application demonstrates how to code factory-based routing (see Listing 3-4). You can find the Specifying a FACTORYROUTING Criteria
INTERFACES section specifies what kinds of criteria the interface routes on. The INTERFACES section specifies the routing criteria via an identifier, FACTORYROUTING.
University Sample
UBBCONFIG files (ubb_p.nt or ubb_p.mk) for this sample in the directory where the WLE software is installed. Look in the \samples\corba\university\production subdirectory.
Listing 3-4
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 "Example: Factory-based Routing in the University Production Sample Application (WLE Servers)" on page 3-63.
Listing 3-5 shows how factory-based routing is specified in the Bankapp sample application.
Listing 3-5 Bankapp Sample Factory-base 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.
In WLE systems, 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.
You can control the flow of data in a WLE 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:
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 The For more information about using these parameters to implement factory-based routing or data-dependent routing, see Chapter 5, "Distributing Applications."
The following table identifies the information required for an entry in the
The where
Note:
Overlapping ranges are allowed, but will map to the first group. For example: The University Production sample application demonstrates how to implement factory-based routing. You can find the The following INTERFACES, The 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 The Specifying Different Interface Parameters for Different Server Groups
SRVGRP parameter.
Configuring Routing
ROUTING section of UBBCONFIG allows the full definition of the routing criteria named in the INTERFACES section (for WLE factory-based routing) or in the SERVICES section (for BEA TUXEDO data-dependent routing).
Defining Routing Criteria in the ROUTING Section
ROUTING section.
Specifying Range Criteria in the ROUTING Section
RANGES parameter provides the actual mapping between field value and group name. Its syntax is as follows:
RANGES="[val1[-val2]:group1] [,val3[-val4]:group2]...[,*:groupn]"
val1, and so on, are values of that field and group<n> 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, what to do if the data does not fall into any range yet specified. val1 would be a numeric literal for numeric fields, and would be enclosed in single quotes (`) for STRING or CARRAY fields. The field values MIN and MAX (not enclosed in quotes) are provided to allow machine minimum and maximum data values to be expressed. There is no limit to the number of ranges that may be specified, but all routing information is stored in shared memory and incurs a cost there.
RANGES="0-5:Group1,3-5:Group2", a range value of 4 would route to Group1.
Example: Factory-based Routing in the University Production Sample Application (WLE Servers)
ubb_p.nt or ubb_p.mk UBBCONFIG files for this sample in the directory where the WLE software is installed. Look in the \samples\corba\university\production subdirectory.
ROUTING, and GROUPS sections from the ubb_b.nt configuration file show how you can implement factory-based routing in a WLE application.
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 following example:
*INTERFACES
"IDL:beasys.com/UniversityP/Registrar:1.0"
FACTORYROUTING = STU_ID
"IDL:beasys.com/BillingP/Teller:1.0"
FACTORYROUTING = ACT_NUMFACTORYROUTING identifier specifies the names of the routing values, which are STU_ID and ACT_NUM, respectively.
ROUTING section specifies the following data for each routing value:
TYPE parameter, which specifies the type of routing. In the Production sample, the type of routing is factory-based routing. Therefore, this parameter is defined to FACTORY.
The following example shows the 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 The following example shows the CLOSEINFO = "" The following example extends the Bankapp sample application to use factory-based routing. The sample included with the WLE software does not contain these parameter settings.
In this example, the ROUTING section of the UBBCONFIG file used in the Production sample application:
*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"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 on which they run need to be identified.
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 WLE software is configured to run entirely on one machine. However, you can easily configure this application to run on multiple machines.)
*GROUPS
APP_GRP1
LMID = SITE1
GRPNO = 2
TMSNAME = TMS
APP_GRP2
LMID = SITE1
GRPNO = 3
TMSNAME = TMS
ORA_GRP1
LMID = SITE1
GRPNO = 4OPENINFO = "ORACLE_XA:Oracle_XA+Acc=P/scott/tiger+SesTm=100+LogDir=.+MaxCur=5"
CLOSEINFO = ""
TMSNAME = "TMS_ORA"
ORA_GRP2
LMID = SITE1
GRPNO = 5OPENINFO = "ORACLE_XA:Oracle_XA+Acc=P/scott/tiger+SesTm=100+LogDir=.+MaxCur=5"
TMSNAME = "TMS_ORA"
Example: Factory-based Routing in the Bankapp Sample Application (WLE Servers)
*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 = 3IDL:Bankapp/Teller interface employs a factory-based routing scheme called atmID, as defined in the ROUTING section. In the ROUTING section, the example indicates that the processing will be distributed across the following two server groups:
BANK_GROUP1 processes interfaces used by the application when the atmID field is between 1 and 5 (inclusive), or greater than 10.
You can configure network groups in the
Note:
For specific information about the tasks involved, see Chapter 6, "Building Networked Applications."
The Every The
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 Configuring Network Information
NETGROUPS and NETWORK sections of an application's UBBCONFIG file.
Specifying Information in the NETGROUPS Section
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 a pair of machines may be assigned. The method of communication to be used by members of different networks in a network group is determined by the priority mechanism (NETPRIO).
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 releases of the BEA TUXEDO system prior to Release 6.4 are assigned to the DEFAULTNET network group.
NETGRPNO, NETPRIO, NETGROUP, MAXNETGROUPS, and MAXPENDINGBYTES parameters have the following characteristics:
Sample NETGROUPS Configuration
NETGROUPS that you have defined in the following way:
DEFAULTNET (the default network, which is the corporate WAN)
Every machine belongs to
The following table shows you which machines have addressees for which groups.
Note:
Because the local area networks are not routed among the locations, machine D (in the To set up the configuration just described, the First State Bank system administrator defines each group in the 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. Figure 3-1 shows machines A through E in the networks for which they have network addresses.
Figure 3-1 Example of a Network Grouping
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 the UBBCONFIG File with Netgroups
NETGROUPS section of the UBBCONFIG file, as shown in Listing 3-6.
Listing 3-6
Sample NETGROUPS and NETWORK Sections
*NETGROUPS
DEFAULTNET NETGRPNO = 0 NETPRIO = 100 #default
BLUE_GROUP NETGRPNO = 9 NETPRIO = 100
MAGENTA_GROUP NETGRPNO = 125 NETPRIO = 200
GREEN_GROUP NETGRPNO = 13 NETPRIO = 200
*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"
