This topic includes the following sections:
Configuration file requirements are determined by the needs of your application. Following are instructions for several types of configurations:
For a single-machine configuration, you need to create the following sections of the configuration file. Click on each task for instructions on completing that task.
You can also click on any area of the following diagram to learn how to create the section named in that area.
For a distributed ATMI application, you need to create the following sections of the configuration file. Click any of the following tasks for instructions on completing that task.
Note: | For detailed information about creating a configuration file for a distributed CORBA application in the Oracle Tuxedo system, refer to the Scaling, Distributing, and Tuning CORBA Applications guide. |
You can also click on any area of the following diagram to learn how to create the section named in that area.
For a multiple-domain configuration, you need to create two configuration files for each participating domain:
For an application that consists of two domains (for example, lapp
and rapp
for local and remote domains, respectively), the following tasks are required.
Click on each task for instructions on completing that task.
The following diagram shows which sections of the UBBCONFIG
and DMCONFIG
files you need to configure for a two-domain application. One domain represents the local domain; the other, the remote domain.
Click on any area of the following diagram for instructions on creating that section of the configuration file.
The first section of every configuration file must be the RESOURCES
section. The parameters defined in this section control the application as a whole and serve as system-wide defaults. The values of RESOURCES
parameters can be overridden, however, on a per-machine basis by assigning other values in the MACHINES
section.
For each parameter in the RESOURCES
section, the following table provides a description and links to reference pages and additional information.
The following is a sample RESOURCES
section of a configuration file.
*RESOURCES
IPCKEY 39211
UID 0
GID 1
PERM 0660
MAXACCESSERS 75
MAXSERVERS 40
MAXSERVICES 55
MASTER SITE1, SITE2
MODEL MP
OPTIONS LAN, MIGRATE
SECURITY APP_PW
AUTHSVC "AUTHSVC"
NOTIFY DIPIN
SYSTEM_ACCESS PROTECTED, NO_OVERRIDE
LDBAL Y
Among the architectural decisions needed for an Oracle Tuxedo application are the following:
Use the MODEL
and OPTIONS
parameters to define the application type.
The MODEL
parameter specifies whether an application runs on a single processor. It is set to SHM
for uniprocessors and also for multiprocessors with global shared memory. A MODEL
value of MP
is used for multiprocessors that do not have global shared memory, as well as for networked applications. This is a required parameter.
The OPTIONS
parameter is a comma-separated list of application configuration options. Two available options are LAN
(indicating a networked configuration) and MIGRATE
(indicating that application server migration is allowed).
The following is a sample setting in the RESOURCES
section of a configuration file.
*RESOURCES
MODEL MP
OPTIONS LAN, MIGRATE
You can control the number of buffer types and subtypes allowed in the application with the MAXBUFTYPE
and MAXBUFSTYPE
parameters, respectively. Unless you are creating many user-defined buffer types, you can omit MAXBUFTYPE
. If you intend to use many different VIEW
types, you may want to set MAXBUFSTYPE
to a value higher than its current default.
In this example, the maximum number of buffer types is 20; the maximum number of subtypes is 40.
*RESOURCES
MAXBUFTYPE 20
MAXBUFSTYPE 40
You can specify the maximum number of simultaneous conversations on a machine with the MAXCONV
parameter. The value of MAXCONV
must be greater than 0 and less than 32,768.
The MAXCONV parameter has the following characteristics:
SERVERS
section is 10; otherwise, the default is 1.MACHINES
section.In this example, the maximum number of simultaneous conversations allowed on each machine is 15.
Because most interprocess communication (IPC) and shared memory bulletin board tables are statically allocated for speedy processing, it is important to tune them correctly. If they are sized too generously, memory and IPC resources are wasted; if too small, processes fail when the limits are exceeded. You can use the tmloadcf -c
command to find out the maximum IPC resources required by a specific application. (See tmloadcf(1) in the Oracle Tuxedo Command Reference.)
MAXACCESSERS, MAXSERVERS, MAXSERVICES, MAXINTERFACES, and MAXOBJECTS are the tunable parameters that control IPC sizing. The amount of shared memory allocated in an application is controlled by the MAXGTT
and MAXCONV
parameters.
Note: | Examples of system-supplied servers are AUTHSVR , TMQUEUE , TMQFORWARD , TMUSREVT , TMSYSEVT , TMS , TMS_QM , GWTDOMAIN , and WSL . |
The cost incurred by increasing MAXACCESSERS
is one additional semaphore per site per client or server process (accesser—see note that follows). There is a small fixed semaphore overhead for system processes in addition to that added by the MAXACCESSERS
value. The cost of increasing MAXSERVERS
and MAXSERVICES
is a small amount of shared memory that is kept for each server, service, and client entry, respectively. The general idea for these parameters is to allow for future growth of the application. It is more important to scrutinize MAXACCESSERS
.
Note: | The system allocates one semaphore for each access slot to the bulletin board. A semaphore is a latch circuit that prevents more than one process from accessing the same shared memory in the bulletin board at the same time. |
For Oracle Tuxedo releases prior to release 7.1, both the MAXACCESSERS
and MAXSERVERS
parameters for an application play a part in the user license checking scheme. Specifically, a machine is not allowed to boot if the number of MAXACCESSERS
for that machine + the number of MAXACCESSERS
for the machine (or machines) already running in the application is greater than the number of MAXSERVERS
+ user licenses for the application. Thus, the total number of MAXACCESSERS
for an application must be less than or equal to the number of MAXSERVERS
+ user licenses for the application.
The user license checking scheme in Oracle Tuxedo release 7.1 or later considers only the following two factors when performing its checks: the number of user licenses for an application and the number of licenses currently in use for the application. When all user licenses are in use, no new clients are allowed to join the application.
In this example, at most 75 processes (clients and servers) can access the system at any one time. There is room for 40 servers advertising 55 services in the bulletin board.
*RESOURCES
MAXACCESSERS 75
MAXSERVERS 40
MAXSERVICES 55
You can control whether a load balancing algorithm is used on the Oracle Tuxedo application as a whole. When load balancing is used, a load factor is applied to each service within the system, allowing you to track the total load on every server. Every service request is sent to the qualified server that is least loaded.
To specify whether load balancing should be used, set the LDBAL
parameter to Y
(Yes) or N
(No). By default, it is set to N
.
You should use load balancing only if necessary; that is, whenever a service is offered by servers that use more than one queue. Load balancing is not appropriate for services offered by only one server, or by servers in an MSSQ (Multiple Server, Single Queue) set. If you have only these types of services in your configuration, set the LDBAL
parameter to N
. If LDBAL
is set to N
and multiple queues offer the same service, the first available queue is selected.
The LDBAL parameter has the following characteristics:
LDBAL
is set to Y
, then load balancing is used.LDBAL
is set to Y
and the application is networked, you can use TMNETLOAD
for local preference.LDBAL
is set to N
, the server assigned is the first available server.N
.LDBAL
incurs overhead, use it only when necessary.MSSQ
server set. In this example, load balancing is enabled for the application.
The MASTER
machine controls the booting and administration of the entire application. You must specify a MASTER
machine for every application by setting the MASTER
parameter. The value of MASTER
is the Logical Machine Identifier (LMID
) for the appropriate computer. The LMID
, in turn, is defined as an alphanumeric string, chosen by the administrator, that is assigned to the LMID
parameter in the MACHINES
section. Therefore, for example, if the value of the LMID
parameter is SITE1
, then the value of MASTER
must also be SITE1
.
If you want to be able to bring down the MASTER
machine without shutting down the application, you must be able to migrate the MASTER
. To enable migration, you must specify two values for LMID
: the primary MASTER
and the backup MASTER
.
The MASTER parameter has the following characteristics:
Site1
is the MASTER
machine; SITE2
is the backup machine.
*RESOURCES
MASTER SITE1, SITE2
To specify the maximum number of configured network groups, set the MAXNETGROUPS
parameter. The value must be greater than or equal to 1 and less than 8192. The default is 8. This parameter is optional.
Periodically (every 120 seconds, by default) the Bulletin Board Liaison (BBL) checks the sanity of the servers on its machine. You can change the frequency of these checks, however, by setting the SCANUNIT
and SANITYSCAN
parameters.
Use the SANITYSCAN
parameter to specify how many SCANUNIT
s elapse between sanity checks of the servers. Its current default is set so that SANITYSCAN
* SCANUNIT
is approximately 120 seconds.
In addition, you can specify the number of timeout periods for blocking messages, transactions, and other system activities by setting the BLOCKTIME
parameter.
Note: | Nontransactional blocking time values can be set on a per service, per ATMI call, and per context basis. These blocktime values override the system-wide default BLOCKTIME values set in the RESOURCES section of the UBBCONFIG file. For further information see Specifying Nontransactional Service-Level Blocktime. |
The term timeout is used to refer, collectively, to the amount of time that elapses while a client:
The term blocking timeout refers to the amount of time spent by a client request waiting for a blocking condition to clear up. Block timeouts for asynchronous service requests and conversations apply to individual send and receive operations. When a process sends a message using tpacall
(3c), tpconnect
(3c), or tpsend
(3c), the timeout applies only to the period during which the request waits to get on the queue if the queue is full. When a client process issues a tpgetrply
(3c) or tprecv
(3c) call to receive a message, the timeout specifies how long the client may wait for the incoming message if its queue is empty.
In this example, sanity scans are performed every 30 seconds and requests block for no more than 10 seconds. A SCANUNIT
of 10 and a SANITYSCAN
of 3 allow 3 blocks of 10 seconds or 30 seconds to elapse before the BBL scans.
*RESOURCES
SCANUNIT 10
SANITYSCAN 3
BLOCKTIME 1
You can restrict access to Oracle Tuxedo administrative functions to authorized administrators only, by setting three parameters: UID
, GID
, and PERM
.
The defaults of UID
and GID
are the user ID and group ID, respectively, of the person who runs the tmloadcf(1)
command on the configuration, unless overriding values have been specified in the MACHINES
section.
The user ID of the administrator. The value is a numeric string corresponding to the UNIX system user ID of the person who boots and shuts down the system.
|
|||
|
|||
The value is an octal number that specifies permissions for the IPC resources created when the application is booted. This parameter provides the first level of defense of the Oracle Tuxedo system IPC structures against unauthorized access. These values should be specified for production applications.
|
Note: | You can overwrite the values assigned to these parameters for remote machines. The user and group IDs on a remote machine are not required to be the same as the user and group IDs on the MASTER machine. You can override the defaults by specifying different user and group IDs in the MACHINES section of the configuration file. If not specified, values specified in the RESOURCES section are used. |
You can set the following three levels of security:
PERM
parameter—provides minimal security by restricting, through permissions, the ability to write to the application queues.SECURITY
parameter—provides greater security. When this parameter is set, a client must supply a password when joining the application. This password is checked against the password supplied by the administrator when the TUXCONFIG
file is generated from the UBBCONFIG
file. AUTHSVC
parameter—sets the maximum level of security. When this parameter is set, any client request to join the application is sent to an authentication service. The authentication service may be the default service supplied by the Oracle Tuxedo system or a third-party vendor service, such as a Kerberos service. This level of security cannot be used unless the SECURITY
parameter is set.
Security level that requires a password to join an application. Accepted values are:
NONE (default), APP_PW , USER_AUTH ACL , and MANDATORY_ACL .
|
|
You can use the SEC_PRINCIPAL_NAME
, SEC_PRINCIPAL_LOCATION
, and SEC_PRINCIPAL_PASSVAR
parameters to identify the security attributes of any servers used for authentication.
SEC_PRINCIPAL_NAME
—defines the principal name used by the server for various security operations. SEC_PRINCIPAL_LOCATION
—specifies the location of the private key of the principal user.SEC_PRINCIPAL_PASSVAR
—specifies the environment variable that contains the password used to open the private key of the principal user.Note: | These policies apply to the Workstation handler, Domains gateway processes, and interoperating application servers. |
You can shield system tables kept in shared memory from application clients and/or servers using the SYSTEM_ACCESS
parameter. This parameter is useful when applications are being developed because faulty application code can inadvertently corrupt shared memory with a bad pointer. Once an application is fully debugged and tested, the value of this parameter can be changed to allow for faster responses. Following are valid values for this parameter:
Once you select a value, you can specify NO_OVERRIDE
, which means that the selected option cannot be changed either by the client, in the TPINIT
structure of the tpinit
() call, or by the administrator, in the SERVERS
section for servers.
SYSTEM_ACCESS PROTECTED, NO_OVERRIDE
To set the address of shared memory, set the IPCKEY
parameter. This parameter is used by the Oracle Tuxedo system to allocate application IPC resources such that they may be located easily by new processes joining the application. This key and its variations are used internally to allocate the bulletin board, message queues, and semaphores that must be available to new application processes. In single processor mode, this key names the bulletin board; in multiprocessor mode, this key names the message queue of the DBBL.
The IPCKEY parameter has the following characteristics:
You can select the default method by which clients receive unsolicited messages by setting the NOTIFY
parameter. The client, however, can override this choice when calling tpinit
().
Following are four possible methods:
IGNORE
—clients ignore unsolicited messages.DIPIN
—clients receive unsolicited messages only when they call tpchkunsol
() or when they make an ATMI call.SIGNAL
—clients receive unsolicited messages by having the system generate a signal that has the signal handler call the function, that is, set with tpsetunsol
().Note: | This method is not allowed for multithreaded or multicontexted applications. |
THREAD
—unsolicited messages are handled by a separate thread managed by the Oracle Tuxedo system for this purpose.
The USIGNAL
parameter specifies the signal to be used if SIGNAL
-based notification is used. Two types of signals can be generated: SIGUSR1
and SIGUSR2
. The default is SIGUSR2
. This method has the advantage of immediate notification, but is limited when you are running a native client. In that case, you must have the same user ID as the sending process. Workstation clients do not have this limitation.
Note: | This method is not available on all platforms. |
The second section of every configuration file must be the MACHINES
section. The MACHINES
section defines parameters for each machine in an application. These parameters provide the following information:
LMID
)TUXCONFIG
)TUXDIR
) APPDIR
)ULOGPFX
)ENVFILE
)Note: | For a particular machine, you can override the following system-wide parameters: UID , GID , PERM , MAXACCESSERS , MAXOBJECTS , MAXCONV , and MAXGTT . Each parameter, except MAXGTT , is described in the RESOURCES section. |
For each parameter in the MACHINES
section, the following table provides a description and links to reference pages and additional information.
The absolute pathname of the file or device where the binary
TUXCONFIG file is found on this machine.
|
||||
Numeric offset containing the TUXCONFIG
|
||||
The numeric permissions associated with the IPC structures that implement the bulletin board. This parameter is used to specify the read/write permissions for processes in the usual UNIX system fashion (that is, with an octal number such as 0600). The value can be between 0001 and 0777, inclusive. If not specified, the default is the value specified in the
RESOURCES section.
|
||||
ULOG pathname
|
Following is a sample MACHINES section of a configuration file in an ATMI environment.
*MACHINES
gumby LMID=SITE1
TUXDIR=”/tuxdir”
APPDIR=”/home/apps/mortgage”
TUXCONFIG=”/home/apps/mortgage/tuxconfig”
ENVFILE=”/home/apps/mortgage/ENVFILE”
ULOGPFX=”/home/apps/mortgage/logs/ULOG”
MAXACCESSERS=100
MAXCONV=15
Following is a sample MACHINES section of a configuration file in a CORBA environment.
*MACHINES
gumby LMID=SITE1
TUXDIR=”/tuxdir”
APPDIR=”/home/apps/mortgage”
TUXCONFIG=”/home/apps/mortgage/tuxconfig”
ENVFILE=”/home/apps/mortgage/ENVFILE”
MAXOBJECTS=700
ULOGPFX=”/home/apps/mortgage/logs/ULOG”
MAXACCESSERS=100
In the preceding sample MACHINES
section, the following parameters and values are specified.
|
|||
You can customize the MACHINES section by indicating the following:
Note: | On a Windows system, the machine name must be specified in UPPERCASE. |
You can use the MAXACLCACHE parameter to specify the number of ACL entries in the cache when SECURITY
is set to ACL
or MANDATORY_ACL
. By setting of this parameter to an appropriate value, you can:
The value must be a number greater than or equal to 10, and less than or equal to 30,000. The default is 100.
You can use the NETLOAD
parameter to specify a load to be added when computing the cost of sending a service request from one machine to another. The value must be a number greater than or equal to 0, and less than 32,768. The default is 0.
You initially define the address of your MASTER
machine in the address portion, which is the basis for a MACHINES
section entry. All other parameters in the entry describe the machine specified by this address. You must set the address to the value printed by calling uname -n
on UNIX systems. On Windows systems, see the Computer Name value in the Network Identification dialog from the Network Control Panel.
The LMID
parameter is mandatory. It specifies a logical name used to designate the computer for which an address has just been provided. It may be any alphanumeric value, but it must be unique among other machines in the application.
The address and machine ID have the following characteristics:
address
LMID=
logical_machine_name
The address identifies the physical processor name.
LMID
is specified as follows:
The LMID
is the logical machine name for a physical processor. It may be any alphanumeric string, but it must be unique within the MACHINES
section.
For some Oracle Tuxedo system operations (such as service name lookups and transactions), the bulletin board must be locked for exclusive access: that is, it must be accessible by only one process. If a process or thread finds that the bulletin board is locked by another process or thread, it retries, or spins on the lock for SPINCOUNT
number of times before giving up and going to sleep on a waiting queue. Because sleeping is a costly operation, it is efficient to do some amount of spinning before sleeping.
Though the value of the SPINCOUNT
parameter is application- and system-dependent, it may be helpful to keep the following basic guidelines in mind:
SPINCOUNT
value of 1 is appropriate for uniprocessors. SPINCOUNT
value as high as 100,000. SPINCOUNT
value and observe your application throughput. Because you can tune the SPINCOUNT
value using the TMIB
, you can adjust it while the system is running.
You can use the TYPE
parameter to group machines into classes. You can set TYPE
to any string that contains 15 or fewer characters.
TYPE
value, data encoding/decoding is not performed when data is sent between the machines.TYPE
can be given any string value. It is used simply for comparisons. TYPE
parameter should be used when the application involves a heterogeneous network of machines or when different compilers are used on the machines in the network.
To identify the configuration file location and filename for an entry that identifies a machine, set TUXCONFIG
, a required parameter. The value of the TUXCONFIG
parameter is enclosed in double quotes and represents a full pathname, which may contain up to 64 characters.
Note: | The pathname specified for this parameter must match exactly (including case) the pathname specified for the TUXCONFIG environment variable. Otherwise, tmloadcf(1) cannot be run successfully. |
The TUXCONFIG
parameter has the following characteristics:
Use the TLOGSIZE
parameter to indicate the size, in pages, of the DTP transaction log for this machine. The value must be a number greater than 0, and less than or equal to 2048, subject to the amount of space available on the operating system filesystem. The default is 100 pages.
Use the TLOGNAME
parameter to define the name of the DTP transaction log for this machine. The default is TLOG
. If more than one TLOG
exists on the same TLOGDEVICE
, each must have a unique name. The value of TLOGNAME
must be different from the name of any other table in the VTOC
(Volume Table of Contents) on the TLOGDEVICE
where the TLOG
table is created. The value of TLOGNAME
must be an alphanumeric string containing 30 or fewer characters.
With the ENVFILE
parameter, you can specify a file that contains environment variable settings for all processes to be booted by the Oracle Tuxedo system. The system sets TUXDIR
and APPDIR
for each process, so these parameters should not be specified in this file.
You can, however, specify settings for the following parameters because they affect an application’s operation:
ENVFILE
is an optional parameter with the following characteristics:
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 Oracle Tuxedo system. (The UBBCONFIG
file issues warnings in a similar way, that is, using fully qualified pathnames.)FIELDTBLS
, FLDTBLDIR
, and so on, but do not set TUXDIR
and APPDIR
.FLDTBLDIR=$APPDIR
are allowed. VARIABLE
=
string.For more information about setting environment variables, refer to tuxenv(5) in File Formats, Data Descriptions, MIBs, and System Processes Reference.
Use the TLOGDEVICE
parameter to specify the Oracle Tuxedo filesystem that contains the DTP transaction log (TLOG
) for this machine. The TLOG
is stored as an Oracle Tuxedo system VTOC table on the specified device. The value of TLOGDEVICE
must be a string containing a maximum of 64 characters.
If this parameter is not specified, then it is assumed that the machine does not have a TLOG
.
Use the MAXGTT
parameter to indicate the maximum number of simultaneous global transactions in which a particular machine can be involved. The value must be a number greater than or equal to 0, and less than 32,768. You can override the value specified in the RESOURCES
section with a value specified in the MACHINES
section for an individual machine.
Use the MAXWSCLIENTS
parameter to define the number of entries on a machine to be reserved for Workstation clients. Set the number of accesser slots reserved for MAXWSCLIENTS
cautiously, since this number takes a portion of the total accesser slots specified with MAXACCESSERS
for this machine; the accesser slots reserved for MAXWSCLIENTS
are unavailable for use by other clients and servers on this machine. By setting this parameter to an appropriate value, you can help conserve IPC resources because Workstation client access to the system is multiplexed through an Oracle Tuxedo system-supplied surrogate, the Oracle Tuxedo Workstation Handler (WSH).
The value of MAXWSCLIENTS
must be greater than or equal to 0 and less than 32,768. If not specified, the default is 0. It is an error to set this parameter to a number greater than MAXACCESSERS
.
Note: | The value of MAXWSCLIENTS is constrained by the number of your licensed users. |
Use the MAXPENDINGBYTES
parameter to define a limit for the amount of space that can be allocated for messages waiting to be transmitted by the BRIDGE
process. This number must be between 100,000 and MAXLONG
.
There are two situations when MAXPENDINGBYTES
is significant:
You can configure larger computers that have more memory and disk space, with larger MAXPENDINGBYTES
, and smaller computers with smaller MAXPENDINGBYTES
.
Every Oracle Tuxedo filesystem has a Volume Table of Contents (VTOC): a list of the files on the devices named in the Universal Device List (UDL). The UDL specifies the location of the physical storage space for Oracle Tuxedo system tables. In an Oracle Tuxedo system application, all system files might be stored together on the same raw disk slice or operating system filesystem file.
Use the TLOGOFFSET
parameter to indicate the offset in pages (from the beginning of the device) to the start of the Oracle Tuxedo filesystem that contains the DTP transaction log for this machine. The offset must be a number greater than or equal to 0, and less than the number of pages on the device. The default is 0.
Every Oracle Tuxedo filesystem has a Volume Table of Contents (VTOC): a list of the files on the devices named in the Universal Device List (UDL). The UDL specifies the location of the physical storage space for Oracle Tuxedo system tables. In an Oracle Tuxedo system application, all system files might be stored together on the same raw disk slice or operating system filesystem file.
Use the TUXOFFSET
parameter to define the offset in pages (from the beginning of the device) to the start of the Oracle Tuxedo filesystem that contains the TUXCONFIG
for this machine. (For information on how this value is used in the environment, see the ENVFILE
parameter in the MACHINES
section.)
Each machine in an application that supports servers must have a copy of the Oracle Tuxedo system software and application software. You identify the location of system software with the TUXDIR
parameter. You identify the location of the application software with the APPDIR
parameter. Both parameters are mandatory. The APPDIR
parameter becomes the current working directory of all server processes. The Oracle Tuxedo software looks in TUXDIR/bin
and APPDIR
for executables.
Use the CMPLIMIT
parameter to define the threshold message sizes at which automatic data compression is performed for messages bound to remote processes (string_value1
) and local processes (string_value2
), respectively.
Both values must be either a non-negative numeric value or the string MAXLONG
. If not specified, the default is MAXLONG
,MAXLONG
.
Note: | Set the CMPLIMIT value and observe your application throughput. Because you can tune the CMPLIMIT value using the TMIB , you can adjust it while the system is running. |
CMPLIMIT
=string_value1
,string_value2
Set the ULOGPFX
parameter to specify the full pathname to be used as the prefix of the name of the userlog
(3c) message file on this machine. The value of ULOGPFX
for a given machine is used to create the userlog
(3c) message file for all servers, clients, and administrative processes executed on that machine. If this parameter is not specified, the path specified by the APPDIR
environment variable is used. mmddyy
(month, day, year) is appended to the prefix to form the full name of the log file.
The ULOGPFX parameter has the following characteristics:
ULOGPFX
parameter is a string enclosed in double quotes: ULOGPFX=
“ULOGPFX
”.TPESYSTEM
and TPEOS
errors.ULOGPFX
defaults to APPDIR
/ULOG
.BANKLOG.022667
, the prefix of the name of the userlog
is specified as follows.ULOGPFX=
“/mnt/usr/appdir/logs/BANKLOG
”
Use the GROUPS
section to designate logically grouped sets of servers, which can later be used to access resource managers, and facilitate server group migration. The GROUPS
section of the configuration file contains definitions of server groups. You must define at least one server group for a machine to have application servers running on it. If no group is defined for a machine, the group can still be part of the application and you can run the administrative command tmadmin(1)
from that site.
For nontransactional, nondistributed systems, groups are relatively simple. You only need to map the group name to the number and logical machine ID for each group. Additional flexibility is available to support distributed transactional systems.
For each parameter in the GROUPS
section, the following table provides a description and links to reference pages and additional information.
Following is a sample GROUPS section of a configuration file in an ATMI environment.
##EVBGRP1 LMID=SITE1 GRPNO=104
DEFAULT:TMSNAME=TMS_SQL TMSCOUNT=2 LMID=SITE1
BANKB1GRPNO=1 OPENINFO="TUXEDO/SQL:APPDIR1
/bankdl1:bankdb:readwrite"
BANKB2GRPNO=2 OPENINFO="TUXEDO/SQL:APPDIR1
/bankdl2:bankdb:readwrite"
BANKB3GRPNO=3 OPENINFO="TUXEDO/SQL:APPDIR1
/bankdl3:bankdb:readwrite"
The followiing sample GROUPS
section is from the UBBCONFIG
file in the Tuxedo CORBA University sample Production application. In this sample, the groups specified by the RANGES
identifier in the ROUTING
section of the UBBCONFIG
file need to be identified and configured.
The Production sample specifies four groups: ORA_GRP1, ORA_GRP2, APP_GRP1,
and APP_GRP2
. These groups mst be configured, and the machines on which they run on must be identified.
*GROUPS
APP_GRP1
LMID = SITE1
GRPNO = 2
TMSNAME = TMS
APP_GRP2
LMID = SITE1
GRPNO = 3
TMSNAME = TMS
ORA_GRP1
LMID = SITE1
GRPNO = 4
OPENINFO = "ORACLE_XA:Oracle_XA+Acc=P/scott/tiger+SesTm=100+LogDir=.+MaxCur=5"
CLOSEINFO = ""
TMSNAME = "TMS_ORA"
ORA_GRP2
LMID = SITE1
GRPNO = 5
OPENINFO = "ORACLE_XA:Oracle_XA+Acc=P/scott/tiger+SesTm=100+LogDir=.+MaxCur=5"
CLOSEINFO = ""
TMSNAME = "TMS_ORA"
The preceding example shows how the ORA_GRP1, ORA_GRP2, APP_GRP1,
and APP_GRP2
groups are configured. See the section
CORBA Factory-based Routing in the University Production Sample Application on page 3-89 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 Oracle Tuxedo software is configured to run entirely on one machine. However, you can easily configure this application to run on multiple machines by specifying the other machines in the LMID parameter. This step assumes that you specify the MODEL MP parameter in the RESOURCES section. |
The group name, which is the basis for a GROUPS
section entry, is an alphanumeric name by which the group is identified; it specifies the logical name (string_value
) of the group. It is given a mandatory, unique group number (GRPNO
). Each group must reside wholly on one logical machine (LMID
).
The LMID
specifies that this group of servers resides on the machine symbolically named by string_value1
in the MACHINES
section.
The name of the transaction manager server (TMS) must be specified in the entry for any group with servers that will participate in distributed transactions (transactions across multiple resource managers—and possibly machines). To specify a TMS, set the TMSNAME
parameter. This parameter specifies the file (string_value
) to be executed by tmboot(1)
when booting the server group.
The value TMS is reserved to indicate use of the null XA interface. This interface can be used for server groups that do not have resource managers. If you do not have a resource manager, you may not need a TMS. This server group may be infected with transactional messages. If a non-empty value other than TMS is specified, then a TLOGDEVICE
must be specified for the machine(s) associated with the LMID
value(s) for this entry. A unique server identifier is selected automatically for each TM server. Servers are restartable an unlimited number of times.
If TMSNAME
is specified, TMSCOUNT=
number
must also be specified to indicate the number of transaction manager servers to start for the associated group. The default for TMSCOUNT
is 3. If specified and the value is non-zero, the minimum value is 2 and the maximum value is 256. The servers are set up in an MSSQ set automatically.
If the value of the ENVFILE
environment variable (ENVFILE=
string_value
) is an invalid filename, no values are added to the environment. Lines must be of the form ident
=
value
where ident
contains only underscores or alphanumeric characters.
Within value
, strings of the form $
{env
} are expanded when the file is processed using variables already defined for the environment. (Forward referencing is not supported. If a value is not set, the variable is replaced with an empty string.) You can use a back slash (\) to escape dollar signs and other back slashes. All other shell quoting and escape mechanisms are ignored and the expanded value is placed in the environment.
Environment files are provided in at least two sections of the configuration file. The Oracle Tuxedo system reads them in the following order:
Values in the SERVERS
section override values in the GROUPS
section. Values in the GROUPS
section override values in the MACHINES
section.
The values of both the OPENINFO
and CLOSEINFO
parameters must be alphanumeric strings that contain a maximum of 256 characters, and are enclosed in double quotation marks. These settings specify the resource manager dependent information needed when opening and closing the resource manager for this group (that is, for this group name).
This value is ignored if the TMSNAME
parameter for this group is not set or is set to TMS
. If the TMSNAME
parameter is set to a value other than TMS
but the OPENINFO
string is set to the null string (""
) or is not specified, a resource manager exists for the group but does not require any information for executing an open
operation. If the TMSNAME
parameter is set to a value other than TMS
but the CLOSEINFO
string is set to the null string (""
) or is not specified, a resource manager exists for the group but does not require any information for executing a close operation.
The format of the OPENINFO
string is dependent on the requirements of the vendor providing the underlying resource manager. The information required by the vendor must be prefixed with the published name of the vendor’s transaction (XA) interface, followed immediately by a colon (:).
For Oracle Tuxedo /Q databases, the format of OPENINFO
is as follows:
In all these settings, TUXEDO/QM
is the published name of the Oracle Tuxedo /Q XA interface, qmconfig
is replaced with the name of the QMCONFIG
(see qmadmin(1) in the Oracle Tuxedo Command Reference) on which the queue space resides, and qspace
is replaced with the name of the queue space. For Windows, the separator after qmconfig
must be a semicolon (;
).
Note: | The CLOSEINFO string is not used for Oracle Tuxedo /Q databases. |
For other vendors’ databases, the format of the OPENINFO
string is specific to the particular vendor providing the underlying resource manager. As an example, the following OPENINFO
string demonstrates the type of information needed when opening the Oracle resource manager.
OPENINFO="Oracle_XA: Oracle_XA+Acc=P/Scott/*****+SesTm=30+LogDit=/tmp"
Oracle_XA
is the published name of the Oracle XA interface. The series of five asterisks (*) in the OPENINFO
string pertains to the encrypting of a password, which is described in the paragraphs that follow.
Passwords passed to a resource manager in the OPENINFO
string can be stored in either clear text or encrypted form. To encrypt a password, first enter a series of five or more continuous asterisks in the OPENINFO
string at the place where you want the password to go. Then load the UBBCONFIG
file by running tmloadcf(1)
. When tmloadcf()
encounters the string of asterisks, it prompts you to create a password. For example:
tmloadcf -y /usr5/apps/bankapp/myubbconfig
Password for OPENINFO (SRVGRP=BANKB3):password
tmloadcf()
stores the password in the TUXCONFIG
file in encrypted form. If you then regenerate the UBBCONFIG
file from the TUXCONFIG
file using tmunloadcf(1)
, the password is printed in the regenerated UBBCONFIG
file in encrypted form with @@
as delimiters. For example:
OPENINFO="Oracle_XA: Oracle_XA+Acc=P/Scott/@@A0986F7733D4@@+SesTm=30+LogDit=/tmp"
When tmloadcf()
encounters an encrypted password in a UBBCONFIG
file generated by tmunloadcf()
, it does not prompt the user to create a password.
If you have more than one machine in your distributed application, you need to create a NETWORK
section in your configuration file. This section sets up communications among your machines. You can configure network groups in both the NETGROUPS
and NETWORK
sections of an application’s UBBCONFIG
file.
For each parameter in the NETWORK
section, the following table provides a description and links to reference pages and additional information.
The following configuration file excerpt shows a NETWORK
section for a two-site configuration.
*NETWORK
SITE1 NADDR="//mach1:80952"
NLSADDR="//mach1:serve"
# SITE2 NADDR="//mach386:80952"
NLSADDR="//mach386:serve"
To specify the device name to be used by the BRIDGE
process placed on the LMID
to access the network, set the BRIDGE
parameter as follows:
BRIDGE=
string_value
If you are using TCP/IP, you do not need to specify the device name for the BRIDGE
.
The pathname for the network transport endpoint file has the following form:
/dev/
provider_name
To specify the complete network address to be used by the BRIDGE
process placed on the LMID
as its listening address, set the NADDR
parameter as follows:
The listening address for a BRIDGE
is the location at which it is contacted by other BRIDGE
processes participating in the application.
The listening address for a BRIDGE
may also be specified in one of the following three forms:
In the first of these formats, host.name
is resolved to the address of the TCP/IP host address at the time the address is bound. This format is based on locally configured name resolution facilities accessed via an operating system command. The value of port_number
can be a symbolic name or a decimal number.
In the second format, the string #.#.#.#
represents four decimal numbers (each of which is between 0 and 255), separated by periods. The value of port_number
is a decimal number in the range 0 to 65,535 (the hexadecimal representations of the string specified). The value of port_number
can be a symbolic name or a decimal number.
In the third format, the string 0xhex-digits
or \\
xhex-digits
must contain an even number of valid hex digits. A string in either of these forms is translated internally into a character array containing TCP/IP addresses.
Note: | On some platforms lower numbers may be reserved for the system. |
To set up the minimum level of encryption required when establishing a network link to the machine, set the MINENCRYPTBITS
parameter. Valid values are 0, 56, and 128. 0 means no encryption, while 56, and 128 specify the encryption key length (in bits). If this minimum level of encryption cannot be met, link establishment fails. The default is 0.
To set up a maximum level of encryption when establishing a network link, set the MAXENCRYPTBITS
parameter. Valid values are 0, 56, and 128. 0 means no encryption, while 56, and 128 specify the encryption key length (in bits). The default is 128.
MAXENCRYPTBITS=128
MINENCRYPTBITS=0
To specify the network address used by the tlisten(1)
process servicing the network on the machine identified by the LMID
, set the NLSADDR
parameter as follows:
The value of string
is a network address in the same format as that specified for the NADDR
parameter.
The tlisten
address for NLSADDR
may be specified in one of the following three forms:
In the first of these formats, host.name
is resolved to the address of the TCP/IP host address at the time the address is bound. This format is based on locally configured name resolution facilities accessed via an operating system command. The value of port_number
can be a symbolic name or a decimal number.
In the second format, the string #.#.#.#
represents four decimal numbers (each of which is between 0 and 255), separated by periods. The value of port_number
is a decimal number in the range 0 to 65,535 (the hexadecimal representations of the string specified). The value of port_number
can be a symbolic name or a decimal number.
In the third format, the string 0xhex-digits
or \\
xhex-digits
must contain an even number of valid hex digits. A string in either of these forms is translated internally into a character array containing TCP/IP addresses.
tmloadcf(1)
prints an error if NLSADDR
is missing from an entry for any machine besides the MASTER
LMID
, for which it prints a warning. If NLSADDR
is missing from the MASTER
LMID
, tmadmin(1)
cannot run in administrator mode on remote machines; it is limited to read-only operations. In addition, the backup site cannot reboot the MASTER
site after failure.
The NETGROUPS
section of the UBBCONFIG
file describes the network groups available to an application in a LAN environment. There is no limit to the number of network groups to which you can assign a pair of machines. The method of communication to be used by members of different networks in a network group is determined by the priority mechanism (NETPRIO
).
Every LMID
must be a member of the default network group (DEFAULTNET
). The network group number for this group (that is, the value of NETGRPNO
) must be zero. However, you can modify the default priority of DEFAULTNET
. Networks defined in the Oracle Tuxedo system prior to release 6.4 are assigned to the DEFAULTNET
network group.
For each parameter in the NETGROUPS
section, the following table provides a description and links to reference pages and additional information.
You can associate network addresses with a network group. The following example illustrates how this capability may be useful.
First State Bank has a network of five machines (A-E). Each machine belongs to two or three of four netgroups that you have defined in the following way:
Every machine belongs to DEFAULTNET
(the corporate WAN). In addition, each machine is associated with either the MAGENTA_GROUP
or the BLUE_GROUP
. Finally, some machines in the MAGENTA_GROUP
LAN also belong to the private GREEN_GROUP
. The following illustration shows machines A through E in the networks for which they have addresses.
The following table shows which machines have addresses for which groups.
Note: | Because the local area networks are not routed among locations, machine D (in the BLUE_GROUP LAN) may contact machine A (in the GREEN_GROUP LAN) only by using the single address they have in common: the corporate WAN network address. |
To set up the configuration just described, the First State Bank system administrator defines each group in the NETGROUPS
section of the UBBCONFIG
file, as shown in the following configuration file sample.
*NETGROUPS
DEFAULTNET NETGRPNO = 0 NETPRIO = 100 #default
BLUE_GROUP NETGRPNO = 9 NETPRIO = 200
MAGENTA_GROUP NETGRPNO = 125 NETPRIO = 200
GREEN_GROUP NETGRPNO = 13 NETPRIO = 300
*NETWORK
A NETGROUP=DEFAULTNET NADDR="//A_CORPORATE:5723”
A NETGROUP=MAGENTA_GROUP NADDR="//A_MAGENTA:5724"
A NETGROUP=GREEN_GROUP NADDR="//A_GREEN:5725"
B NETGROUP=DEFAULTNET NADDR="//B_CORPORATE:5723"
B NETGROUP=MAGENTA_GROUP NADDR="//B_MAGENTA:5724"
B NETGROUP=GREEN_GROUP NADDR="//B_GREEN:5725"
C NETGROUP=DEFAULTNET NADDR="//C_CORPORATE:5723"
C NETGROUP=MAGENTA_GROUP NADDR="//C_MAGENTA:5724"
D NETGROUP=DEFAULTNET NADDR="//D_CORPORATE:5723"
D NETGROUP=BLUE_GROUP NADDR="//D_BLUE:5726"
E NETGROUP=DEFAULTNET NADDR="//E_CORPORATE:5723"
E NETGROUP=BLUE_GROUP NADDR="//E_BLUE:5726"
To assign a name to a network group, set the NETGROUP
parameter as follows:
NETGROUP
required_parameters
[
optional_parameters
]
If you set NETGROUP
to DEFAULTNET
, then the entry describes the default network group. All network entries with a NETGROUP
parameter of DEFAULTNET
are represented in the T_MACHINE
class of the TM_MIB
, while NETWORK
entries associated with any other NETGROUP
are represented in the T_NETMAP
class of the TM_MIB
, so they can interoperate with previous releases.
To accommodate circumstances in which you may need to use failover and failback, you must set the NETGRPNO
parameter as follows:
NETGRPNO=
numeric_value
If this entry describes DEFAULTNET
, the value of NETGRPNO
must be zero.
A pair of machines in multiple network groups of the same priority can communicate simultaneously over the circuits with the highest priority. To assign network group priorities, use the NETPRIO
parameter. If all network circuits of a certain priority are torn down by an administrator or by network conditions, the next lower priority circuit is used. Retries of the higher priority circuits are attempted. The value of the NETPRIO
parameter must be a number greater than zero and less than 8,192. The default is 100.
The SERVERS
section of the configuration file contains information specific to a server process. While this section is not required, an application without this section has no application servers and little functionality. Each entry in this section represents a server process to be booted in the application and includes the following information:
SRVGRP
, SRVID
)servopts
(CLOPT
)SEQUENCE
, MIN
, MAX
)ENVFILE
)RQADDR
, RQPERM
, REPLYQ
, RPPERM
) RESTART
, RCMD
, MAXGEN
, GRACE
)CONV
)SYSTEM_ACCESS
)Note: | Command-line options supported by the Oracle Tuxedo system are described in servopts(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference. |
For each parameter in the SERVERS
section, the following table provides a description and links to reference pages and additional information.
The minimum number of server dispatch threads started on initial server boot. The separate dispatched thread that is used when
MAXDISPATCHTHREADS >1 is not counted as part of the MAXDISPATCHTHREADS value. It is required that MINDISPATCHTHREADS <=MAXDISPATCHTHREADS . The default for this parameter is 0.
|
||
The WebLogic Server embedded LDAP-based authentication server. It is a System /T provided server that offers the authentication service while the user security information is located in WebLogic Server. This server may be used in a secure application to provide per-user authentication when clients join the application.
|
Following is a sample SERVERS section of a configuration file.
*SERVERS
DEFAULT: RESTART=Y MAXGEN=5 GRACE=3600
REPLYQ=N CLOPT=”-A”
ENVFILE=”/usr/home/envfile”
SYSTEM_ACCESS=PROTECTED
RINGUP1 SRVGRP=GROUP1 SRVID=1 MIN=3
RQADDR=”ring1"
RINGUP2 SRVGRP=GROUP1 SRVID=4 MIN =3
RQADDR=”ring2"
Note: | Omitted from this sample are SEQUENCE (the order of booting is 1 to 6), REPLYQ and RPPERM (the server does not receive replies), RCMD (no special commands are desired on restart), and CONV (servers are not conversational). Defaults are applied to all servers unless a different setting is specified for a specific server. |
In the preceding sample SERVERS
section, the following parameters and values are specified.
The
MAXGEN parameter specifies a number greater than 0 and less than 256 that controls the number of times a server can be started within the period specified by the GRACE parameter. The default is 1. If the server is to be restartable, MAXGEN must be >= 2. The number of restarts is at most number - 1 times. RESTART must be Y or MAXGEN is ignored.
|
|||
If
RESTART is Y , the GRACE parameter specifies the time period (in seconds) during which this server can be restarted as MAXGEN - 1 times. The number assigned must be equal to or greater than 0. The maximum is 2,147,483,648 seconds (or a little more than 68 years). If GRACE is not specified, the default is 86,400 seconds (24 hours). As soon as one GRACE period is over, the next grace period begins. Setting the grace period to 0 removes all limitations; the server can be restarted an unlimited number of times.
|
|||
|
Three instances of the sample server will be booted in group
GROUP1 with server IDs of 1 , 2 , and 3 , respectively. The three servers will form an MSSQ set and will read requests from queue ring1 .
|
||
If a server is conversational (that is, if it establishes a two-way connection between a client and a dedicated server), the CONV
parameter is required and must be set to Y
. The default is N
, indicating that the server will not be part of a conversation.
The CONV parameter has the following characteristics:
To specify the sequence of servers to be booted, set the SEQUENCE
parameter for each server. The value of SEQUENCE
can be any number between 1 and 10,000. A server with a smaller SEQUENCE
value is booted before a server with a larger value. If the SEQUENCE
parameter is not set for any servers, the servers are booted in the order in which they are listed in the SERVERS
section. If some, but not all servers are sequenced, the sequenced servers are booted first. The order in which servers are shut down is the reverse of the order in which they were booted.
The SEQUENCE
parameter is optional. It may be helpful in a large application in which control over boot order is important.
WARNING: | In CORBA environments, there is a strict order in which the system EventBroker, the FactoryFinder object, and the application factories must be booted. A CORBA application program will not boot if the order is changed. See the section Required Order in Which to Boot CORBA C++ Servers on page 3-61 for details. |
To boot multiple servers, set the MIN
parameter, which provides a shortcut to booting. All servers share the same options. If you specify RQADDR
, the servers form an MSSQ set. The default for MIN
is 1.
To specify the maximum number of servers that can be booted, set the MAX
parameter. The tmboot(1)
command boots MIN
servers at run time. Additional servers can be booted up to MAX
. The default is MIN
.
The MIN
and MAX
parameters are helpful in keeping the size of the configuration files for large applications manageable. Allowances for MAX
values must be made in the IPC resources. The MIN
and MAX
parameters are also used for conversational services and automatic server spawning.
The following is the correct order in which to boot the servers In an Oracle Tuxedo CORBA environment. A CORBA application program will not boot if the order is changed.
TMSYSEVT
.TMFFNAME
server with the -F
option, to start the FactoryFinder object.
Listing 3-2 shows the order in which servers are booted for the Oracle Tuxedo CORBA University Basic application, which is one of the sample applications included with the Oracle Tuxedo software. This SERVERS
section is excerpted from an edited version of the ubb_b.nt
configuration file.
*SERVERS
# By default, restart a server if it crashes, up to 5 times
# in 24 hours.
#
DEFAULT:
RESTART = Y
MAXGEN = 5
# Start the Oracle Tuxedo System EventBroker. This event broker
# must be started before any servers providing the
# NameManager Service
#
TMSYSEVT
SRVGRP = SYS_GRP
SRVID = 1
# TMFFNAME is a Oracle Tuxedo CORBA provided server that
# runs the NameManager and FactoryFinder services.
# The NameManager service is a Oracle Tuxedo CORBA-specific
# service that maintains a mapping of application-supplied names
# to object references.
# Start the NameManager Service (-N option). This name
# manager is being started as a Master (-M option).
#
TMFFNAME
SRVGRP = SYS_GRP
SRVID = 2
CLOPT = "-A -- -N -M"
# Start a slave NameManager Service
#
TMFFNAME
SRVGRP = SYS_GRP
SRVID = 3
CLOPT = "-A -- -N"
# Start the FactoryFinder (-F) service
#
TMFFNAME
SRVGRP = SYS_GRP
SRVID = 4
CLOPT = "-A -- -F"
# Start the interface repository server
#
TMIFRSVR
SRVGRP = SYS_GRP
SRVID = 5
# Start the university server
#
univb_server
SRVGRP = ORA_GRP
SRVID = 6
RESTART = N
# Start the listener for IIOP clients
#
# Specify the host name of your server machine as
# well as the port. A typical port number is 2500
#
ISL
SRVGRP = SYS_GRP
SRVID = 7
CLOPT = "-A -- -n //TRIXIE:2500"
In the example, after the TMSYSEVT
and TMFFNAME
servers are started, servers are started for:
CLOPT
parameter), see Managing CORBA Interface Repositories.univb_server
, for the University Basic sample application. For details about the sample applications, see the Guide to the CORBA University Sample Applications.CLOPT
parameter, refer to Managing Remote Oracle Tuxedo CORBA Client Applications.Note: | When migrating or shutting down and restarting groups or machines for any reason, if there are active slave NameManagers in other groups, be sure to organize your UBBCONFIG file so that a FactoryFinder or a slave NameManager is never restarted before the master NameManager is active. For example, if you have a FactoryFinder in the same group as the master NameManager, arrange the order of these servers in the UBBCONFIG file so the master NameManager is started first. |
The Oracle Tuxedo system allows you to specify options that are used when a server processes a request. These options are defined in servopts
, which lists the run-time options for server processes. The server may need to obtain information from the command line. The CLOPT
parameter allows you to specify command-line options that can change some defaults in the server, or pass user-defined options to the tpsvrinit()
function.
The standard main()
of a server parses one set of options ending with the argument --, and passes the remaining options to tpsvrinit()
. The default for CLOPT
is -A, which tells the server to advertise all the services built into it with buildserver(1)
or buildobjserver(1)
. The following table provides a partial list of the available options.
Note: | You can find other standard main() options listed on servopts(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference. |
In the BANKAPP
sample application, command-line options are specified as follows:
CLOPT=”-A -- -T 10"
The server is given the option of advertising all services (-A) and teller ID of 10 so it can update a specific teller record with each operation. The use of this option, especially the options passed to tpsvrinit()
, require communication between the system administrator and the application programmer.
Use the ENVFILE
parameter in the MACHINES
section to specify environment settings. You can also specify the same parameter for a specific server process; the semantics are the same. If both the MACHINES
section ENVFILE
and the SERVERS
section ENVFILE
are specified, both go into effect. For any overlapping variable defined in both the MACHINES
and SERVERS
sections, the setting in the SERVERS
section prevails.
ENVFILE
, the parameter that defines the server environment file, has the following characteristics:
For more information about setting environment variables, refer to tuxenv(5) in File Formats, Data Descriptions, MIBs, and System Processes Reference.
You initially assign a name to a server in the SERVERS
section. The name you specify must be the name of an executable file built with one of the following commands:
You must also specify a group identifier (SRVGRP
) for each server. The value of SRVGRP
must be the name specified in the beginning of a GROUPS
section entry. Finally, you must also provide each server process in a given group with a unique numeric identifier (SRVID
). Every server entry must include the SRVGRP
and SRVID
parameters. Because the entries describe machines to be booted and not just applications, it is possible that in some cases the same server name will be displayed in many entries.
Server queue information controls the creation and access of server message queues. On an Oracle Tuxedo system, you can create Multiple Server, Single Queue (MSSQ) sets by using the RQADDR
parameter. For any given server, you can set this parameter to an alphanumeric value. By specifying the same value for RQADDR
on all servers that offer the same services, you can consolidate those services under one message queue, thus creating an MSSQ set and establishing load balancing.
An MSSQ set is similar to a bank staff. Four tellers may be available to handle the business requests of many customers who wait in a single line. All customers are assured of an equitable wait in line. Understandably, a loan officer is not included in the group of tellers handling requests from customers in that line. The loan officer cannot handle requests for deposits and withdrawals (as the tellers can), and not all customers want loans. Similarly, a server cannot join an MSSQ set if the services it offers are not the same as the services offered by the servers in an MSSQ set.
The RQPERM
parameter allows you to specify the permissions for server request queues, along the lines of the UNIX system convention (for example, 0666). This setting allows services to control access to the request queue.
If the service routines within an MSSQ server perform service requests, they must receive replies to their requests on a reply queue. You can set up such a reply queue by specifying REPLYQ=Y
. By default, REPLYQ
is set to N
. If REPLYQ
is set to Y
, you can also assign permissions to it with the RPPERM
parameter.
It is an alphanumeric value that allows MSSQ sets to be created. The value is the same for all members of an MSSQ set. All members of an MSSQ set must offer the same set of services and the servers in an MSSQ set should have the same executable name. In order to boot multiple servers, set the value greater than 1 for
Min parameter.
|
|
Represents the permissions on a request queue. If no parameter is specified, the permissions of the bulletin board, as specified by
PERM in the RESOURCES section, are used. If no value is specified there, the default of 0666 is used. When the default is used, your application is available to anyone with a login on the system.
|
|
Specifies whether a reply queue, separate from the request queue, is to be set up for this server. If only one server is using the request queue, replies can be picked up from the request queue without causing problems. On an Oracle Tuxedo system, if the server is a member of an MSSQ set and contains services programmed to receive reply messages,
REPLYQ should be set to Y so that an individual reply queue is created for this server. If not, the reply is sent to the request queue shared by all servers of the MSSQ set, and there is no way of assuring that it will be picked up by the server that is waiting for it. Multithreaded servers automatically create REPLYQ s even if this parameter is not set.
|
|
A properly debugged server should not terminate on its own. By default, servers that do terminate while the application is running are not restarted by the Oracle Tuxedo system. You can set the RESTART
parameter to Y
if you want the server to restart. The RCMD
, MAXGEN
, and GRACE
parameters are relevant to a server if RESTART=Y
.
The RCMD
parameter lets you specify a command to be performed in parallel with restarting a server. For example, you may want to have e-mail sent to the developer of the server or to someone who is auditing such activity.
The MAXGEN
parameter represents the total number of lives to which a server is entitled within the period specified by GRACE
. The server can then be restarted MAXGEN-1
times during GRACE
seconds. If GRACE
is set to zero, there is no limit on server restarts. MAXGEN
defaults to 1 and may not exceed 256. GRACE
must be greater than or equal to zero and must not exceed 2,147,483,647 (231 - 1).
Note: | A fully debugged server should not need to be restarted. RESTART and associated parameters should have two settings: one for the testing phase, and another for production. |
The SYSTEM_ACCESS
parameter determines whether a server process may attach to shared memory and thus have access to internal tables outside system code. During application development, we recommend that such access be denied (PROTECTED
). When the application is fully tested, you can change the value of SYSTEM_ACCESS
to FASTPATH
to yield better performance.
This parameter setting overrides the value specified in the RESOURCES
section unless the NO_OVERRIDE
value has been specified. In this case, the parameter is ignored. The NO_OVERRIDE
value may not be used in this section.
The SYSTEM_ACCESS
parameter has the following characteristics:
PROTECTED
indicates that the server may not attach to shared memory outside of 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.SYSTEM_ACCESS
parameter in the RESOURCES
section.PROTECTED
is set.
MAXDISPATCHTHREADS
is the maximum number of concurrently dispatched threads that each server process may spawn. If MAXDISPATCHTHREADS>1
, then a separate dispatcher thread is used and does not count against this limit. It is required that MINDISPATCHTHREADS<=MAXDISPATCHTHREADS
. If not specified, the default for this parameter is 1.
MINDISPATCHTHREADS
is the minimum number of server dispatch threads started on initial server boot. The separate dispatched thread that is used when MAXDISPATCHTHREADS>1
is not counted as part of the MAXDISPATCHTHREADS
value. It is required that MINDISPATCHTHREADS<=MAXDISPATCHTHREADS
. The default for this parameter is 0.
You must specify the stack size in bytes for each server thread after the initial thread. If not specified or specified as 0, the operating system default is used. This option has an affect on the server only when a value greater than 1 is specified for MAXDISPATCHTHREADS
.
In CORBA environments the IIOP Listener (ISL) process listens for remote clients requesting a connection. The ISL process is specified in one entry as a server supplied by the Oracle Tuxedo system.
The Secure Socket Layer (SSL) protocol defines how processes can communicate in a secure manner over IIOP. Use the -s
option on the ISL command to set the required parameters. You only need to set these parameters if you are using the SSL protocol, which is installed in the Oracle Tuxedo Security Pack.
Table 3-1 lists the SSL parameters characteristics.
For more information about setting these parameters, see Using Security in CORBA Applications.
Detailed information about the services in your application can be entered in the SERVICES
section of the configuration file. For nontransactional, nondistributed applications, such information is relatively simple. The SERVICES
section includes the following types of information:
There are no required parameters for services. You need to list services only if you are setting optional parameters.
For each parameter in the SERVICES
section, the following table provides a description and links to reference pages and additional information.
Following is a sample of the SERVICES section of a configuration file.
*SERVICES
#
DEFAULT: LOAD=50 PRIO=50
RINGUP BUFTYPE=”VIEW:ringup”
In this example, the default load and priority of a service are 50
; the one service declared is a RINGUP
service that accepts a RINGUP
VIEW
as its required buffer type.
You can determine whether a transaction should be started automatically if a request message is already in transaction mode by coding the AUTOTRAN ={Y|N}
parameter. The default is N
.
You can specify a timeout interval between the time at which a transaction for a service begins and the time at which it is rolled back if not completed. To specify a timeout interval that will be used automatically, set the TRANTIME
parameter as follows:
The default is 30 seconds. A value of 0, the maximum timeout value for the computer, means a transaction will never time out.
An additional transaction timeout property named MAXTRANTIME
is available from the RESOURCES
section of the UBBCONFIG
file. If the MAXTRANTIME
timeout value is less than the TRANTIME
timeout value or the timeout value passed in a tpbegin(3c)
call to start a transaction, the timeout for a transaction is reduced to the MAXTRANTIME
value.
Note: | MAXTRANTIME has no effect on a transaction started on a machine running Oracle Tuxedo 8.0 or earlier, except that when a machine running Oracle Tuxedo 8.1 or later is infected by the transaction, the transaction timeout value is capped—reduced if necessary—to the MAXTRANTIME value configured for that node. |
With the BUFTYPE
parameter, you can tune a service to check buffer types independently of the service code. Set this parameter with a list of allowable buffer types for a service in the following format:
To allow all subtypes, set the value of subtype
to *
.
If the value of the BUFTYPE
parameter for a service is ALL
, this service accepts all buffer types. The default is ALL
.
Sometimes an unexpected system error occurs, freezing a service or causing it to run out of control while it is processing a request. Obviously, it is a good idea to remove these processes, but it is difficult to detect them or determine how they developed errors. The Oracle Tuxedo system provides a mechanism for terminating such processes even when you cannot identify them. To use this mechanism, set the SVCTIMEOUT
parameter.
The SVCTIMEOUT
parameter allows you to designate an amount of time (in seconds) in which a service should be able to process a request. If the interval defined by this parameter elapses and a service has not finished processing a request, the process for that request is killed. In essence, the service timeout mechanism acts like a scavenger for frozen or out of control application servers. By default, the Oracle Tuxedo system does not terminate any service process; you must set the SVCTIMEOUT
parameter to activate this feature.
You can assign a value to the SVCTIMEOUT
parameter in the UBBCONFIG
file or by dynamically changing the TA_SVCTIMEOUT
attribute in TM_MIB
. We recommend that you set the value of SVCTIMEOUT
or TA_SVCTIMEOUT
to at least two to three times the number of seconds it takes for your longest running service to process a request. Setting the service timeout in this way guarantees that the Oracle Tuxedo system removes only frozen processes.
This section describes the causes and results of service timeout errors, and explains how the Oracle Tuxedo system reports such errors. Advice about how to handle errors is also provided.
When a timeout occurs, the Oracle Tuxedo system terminates the server process running the frozen service (but not its child processes, if any). It then returns a TPESVCERR
error, indicating that an unknown problem occurred during processing. In a conversational service, the conversation event TPEV_SVCERR
is returned.
The Oracle Tuxedo system reports a service timeout through the following three mechanisms:
Because the SVCTIMEOUT
value is configurable, it is important for clients to be able to easily distinguish between a TPESVCERR
caused by exceeding the value set for SVCTIMEOUT
, and a TPESVCERR
caused by other situations. Although the ULOG
contains this information, it is difficult for client programs to extract it. To differentiate a service timeout TPESVCERR
from others, a program can include a call to the tperrordetail
(3c) routine (after a TPESVCERR
has been detected), which yields TPED_SVCTIMEOUT
when a service timeout occurs.
In addition, a system event, .SysServiceTimeout
, is generated when a service timeout occurs. When a .SysServiceTimeout
event occurs, it is reflected in the ULOG
in the following way:
ERROR: .SysServiceTimeout: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID server killed due to a service timeout
SVCTIMEOUT
parameter in the SERVICES
section of the UBBCONFIG
file, or by modifying the TA_SVCTIMEOUT
attribute of the T_SERVER
or T_SERVICE
class of the TM_MIB
. They may also monitor the ULOG
file for service timeout activity. ULOG
file for service timeout activity, application operators can subscribe to the .SysServiceTimeout
event, which alerts them when a service timeout occurs. tperrordetail
(3c) and tpstrerrordetail
(3c) functions, and the TPED_SVCTIMEOUT
error detail code.
They may want to add one or more subscriptions to the.SysServiceTimeout
system event, which is generated when a service timeout occurs.
Different services take different amounts of time and need individual BLOCKTIME
values. Sometimes, an application needs or desires to override the default blocktime value for an individual client or for an individual service call.
The UBBCONFIG
file SERVICES
section BLOCKTIME
parameter allows you to designate the blocking time value, per second, for individual nontransactional services. It overrides the default RESOURCES
section BLOCKTIME
parameter value for the designated service. Per service BLOCKTIME
parameter values can also be set for remote services using the DMCONFIG
file. For more information, see UBBCONFIG(5), SERVICES
section and DMCONFIG(5), DM_IMPORT
section.
Unlike the SVCTIMEOUT
parameter, the BLOCKTIME
parameter does not terminate a service application. Instead, it lets the client know that (after a specified time in seconds), no reply has been received by the server while the service request is still processing.
Note: | Application programmers can also set nontransactional blocktime requests and retrieve blocktime values by using the tpsblktime(3c) and tpgblktime(3c)functions. |
To activate load balancing, set the RESOURCES
section parameter LDBAL
to Y
. A load factor is assigned to each service performed (via the LOAD
parameter) and the Oracle Tuxedo system keeps track of the total load of services that each server has performed. Each service request is routed to the server with the smallest total load. The routing of that request causes the server’s total to be increased by the LOAD
factor of the service requested.
Load information is stored only on the site originating the service request. It would be inefficient for the Oracle Tuxedo system to make continuous attempts to propagate load information to all sites in a distributed application. When performing load balancing in such an environment, each site knows only about the load it originated and performs load balancing accordingly. This means that each site has different load statistics for a given server (or queue). The server perceived as being the least busy differs from site to site.
When load balancing is not activated, and multiple servers offer the same service, the first available queue receives the request.
The LDBAL parameter has the following characteristics:
When using data-dependent routing, you need to specify the routing criteria to be used for a service. To specify such criteria, set the ROUTING
parameter as follows:
If this parameter is not set, the service does not perform data-dependent routing.
The maximum value of string
is 15 characters. No more than one value may be assigned to the ROUTING
parameter for a given service. Even if you have multiple entries for one service and those entries contain different SRVGRP
parameters, the value of ROUTING
must be the same in all entries.
You can assign the same service to multiple groups and assign different values to the various service-specific parameters you set for the service entries for the different groups. To do this, create a separate entry for the service for each group, specifying a group-specific value for the SRVGRP
parameter.
You can exert significant control over the flow of data in an application by assigning service priorities using the PRIO
parameter. The value of PRIO must be a number between 0 and 100. The higher the number, the higher the priority of the service to which it is assigned. Higher priority services are dequeued before lower priority services, but the system dequeues every tenth request in FIFO order to prevent a message from waiting indefinitely on the queue.
For instance, Server 1 offers Services A, B, and C. Services A and B have a priority of 50
and Service C has a priority of 70. A service requested for C will always be dequeued before a request for A or B. Requests for A and B are dequeued equally with respect to one another.
Note: | A priority can also be changed dynamically with the tpsprio() call. |
The PRIO parameter has the following characteristics:
The following sample from the SERVICES section of a configuration file shows how priorities are assigned to services:
*SERVICES
A SRVGRP=GRP1 PRIO=50 LOAD=60
A SRVGRP=GRP2 PRIO=70 LOAD=30
In this example, different service-specific parameters are assigned to two server groups. Service A is assigned a priority of 50 and a load of 60 in server group GRP1
, and a priority of 70 and a load of 30 in server group GRP2
.
To indicate the maximum amount of time, in seconds, allowed for processing a service, set the SVCTIMEOUT
parameter as follows:
The value must be greater than or equal to 0
. A value other than 0
indicates that the service will be timed out: the server processing the server request will be terminated with a SIGKILL
signal. The default for this parameter is 0.
Note: | This section applies only to the CORBA environments.in Oracle Tuxedo. |
The INTERFACES
section in the configuration file is used to define parameters for CORBA environments in the Oracle Tuxedo system. In this section, you define application-wide default parameters for CORBA interfaces used by the application. For a CORBA interface participating in factory-based routing, you define the interface names and specify the name of the routing criteria that the Tuxedo CORBA environment should apply to each interface. Factory-based routing is a feature that lets you distribute processing to specific server groups.
In addition to defining the INTERFACES
section, you must specify routing criteria in the ROUTING
section and the names of groups in the GROUPS
section when you implement factory-based routing. For details about the parameters and more information about factory-based routing, see the section How to Create the ROUTING Section of the Configuration File in this chapter.
You indicate specific information about CORBA interfaces used by your application in the INTERFACES
section of the configuration file. There are no required parameters. CORBA interfaces need not be listed if no optional parameters are desired. The INTERFACES
section includes the following types of information:
AUTOTRAN
) (CORBA only)FACTORYROUTING
) (CORBA only)LOAD
)PRIO
)SRVGRP
)TRANTIME
)TIMEOUT
)Table 3-2 lists the AUTOTRAN, FACTORYROUTING, LOAD, PRIO, SRVGRP, TRANTIME, and TIMEOUT parameters characteristics.
For each CORBA interface, set
AUTOTRAN to Y if you want a transaction to start automatically when an operation invocation is received. AUTOTRAN=Y has no effect if the interface is already in transaction mode. The default is N .
The effect of specifying a value for
AUTOTRAN is dependent on the transactional policy specified by the system designer in the implementation configuration file (ICF) or Server Description File (XML) for the interface. This transactional policy will become the transactional policy attribute of the associated T_IFQUEUE MIB object at run time. The only time this value actually affects the behavior of the application is if the system designer specified a transaction policy of optional.
|
|||
This is an arbitrary number between 1 and 100 that represents the relative load that the CORBA interface is expected to impose on the system. The numbering scheme is relative to the
LOAD numbers assigned to other CORBA interfaces used by this application. The default is 50. The number is used by the Oracle Tuxedo system to select the best server to route the request.
|
|||
If
AUTOTRAN is set to Y , you must set the TRANTIME parameter, which is the transaction timeout in seconds, for the transactions to be computed. The value must be greater than or equal to zero and must not exceed 2,147,483,647 (231 - 1), or about 70 years. A value of 0 (zero) implies there is no timeout for the transaction. (The default is 30 seconds.)
|
|||
The amount of time, in seconds, to allow for processing of a method for this CORBA interface. The values must be greater than or equal to 0. A value of 0 indicates that the interface cannot time out. A timed-out method causes the server processing the method for the interface to terminate with a
SIGKILL event. You should consider specifying a timeout value for the longest-running method for the interface.
|
For each CORBA interface, the INTERFACES
section specifies what kinds of criteria the interface routes on. The INTERFACES
section specifies the routing criteria via an identifier, FACTORYROUTING.
The University Production sample application demonstrates how to code factory-based routing (see Listing 3-3). You can find the UBBCONFIG
files (ubb_p.nt
or ubb_p.mk
) for this sample in the directory where the Oracle Tuxedo software is installed. Look in the \samples\corba\university\production
subdirectory.
*INTERFACES
"IDL:beasys.com/UniversityP/Registrar:1.0"
FACTORYROUTING = STU_ID
"IDL:beasys.com/BillingP/Teller:1.0"
FACTORYROUTING = ACT_NUM
The preceding example shows the fully qualified interface names for the two interfaces in the University Production sample. The FACTORYROUTING
identifier specifies the names of the routing values, which are STU_ID
and ACT_NUM
, respectively.
To understand the connection between the INTERFACES
FACTORYROUTING
parameter and the ROUTING
section, see the section
CORBA Factory-based Routing in the University Production Sample Application on page 3-89.
Listing 3-4 shows how factory-based routing is specified in the Bankapp sample application.
*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 Oracle Tuxedo CORBA envirionments, load balancing is always enabled.
A LOAD
factor is assigned to each CORBA interface invoked, which keeps track of the total load of CORBA interfaces that each server process has performed. Each interface request is routed to the server with the smallest total load. The routing of that request causes the server’s total to be increased by the LOAD
factor of the CORBA interface requested. When load balancing is not activated, and multiple servers offer the same CORBA interface, the first available queue receives the request.
For more information about load balancing in Oracle Tuxedo CORBA environments, refer to “ Enabling System-controlled Load Balancing,” in the Scaling, Distributing, and Tuning CORBA Applications manual.
Support for parallel objects in CORBA environments has been added for release 8.0 of Oracle Tuxedo, which introduces load balancing across mulitple servers in a local domain. For more information about parallel objects in Oracle Tuxedo CORBA environments, refer to the “ Using Parallel Objects” section in Scaling, Distributing, and Tuning CORBA Applications.
You can control the flow of data in a Oracle Tuxedo client or server application by assigning interface priorities using the PRIO
parameter. For instance, Server 1 offers Interfaces A, B, and C. Interfaces A and B have a priority of 50
and Interface C has a priority of 70. An interface requested for C will always be dequeued before a request for A or B. Requests for A and B are dequeued equally with respect to one another. The system dequeues every tenth request in FIFO
order to prevent a message from waiting indefinitely on the queue.
The PRIO parameter has the following characteristics:
You can specify different load, priority, or other interface-specific parameters for different server groups. To do this, you should repeat the interface’s entry for each group with different values for the SRVGRP
parameter.
The ROUTING
section of UBBCONFIG
allows you to provide a full definition of the routing criteria named in the SERVICES
section (for ATMI data-dependent routing) or in the INTERFACES
section (for CORBA factory-based routing).
Note: | For more information about configuring factory-based routing for CORBA environments, refer to the Scaling, Distributing, and Tuning CORBA Applications guide. |
For each parameter in the ROUTING
section, the following table provides a description and links to reference pages and additional information.
Name of the routing field, which is assumed to be an
FML buffer, XML element or element attribute, view field name identified in an FML field table (using FLDTBLDIR and FIELDTBLS environment variables), or an FML view table (using the VIEWDIR and VIEWFILES environment variables), respectively. This information is used to obtain the associated field value for data-dependent routing when sending a message.
In CORBA factory-based routing, this value specifies the name of the routing field. The maximum length is 30 characters. It must correspond to a field name specified for factory-based routing in a factory’s call to:
TP::create_object_reference (C++) or com.beasys.Tobj.TP::create_object_ (Java) for the interface.
|
||
The following is a sample ROUTING
section from a configuration file:
BRNCH FIELD=B_FLD
RANGES="0-2:DBG1,3-5:DBG2,6-9:DBG3"
BUFTYPE="FML"
The following table describes the routing buffer field and field type.
In Oracle Tuxedo data-dependent routing, the value of this parameter is one of the following: the name of an
FML field (for FML buffers); an XML element or attribute; a VIEW field name identified in an FML field table (using the FLDTBLDIR and FIELDTBLS environment variables); or an FML view table (using the VIEWDIR and VIEWFILES environment variables). This information is used to obtain the associated field value for data-dependent routing during message processing. If a field in an FML32 buffer is used for routing, it must have a field number less than or equal to 8191.
In routing
XML documents, the FIELD syntax contains either a routing element type (or name) or a routing element attribute name. You must define the FIELD parameter with the following syntax:
The element is assumed to be an element type (or name) or an element attribute name of an XML document or datagram. This information is used to obtain the associated element content or element attribute value for data-dependent routing when a document or datagram is being sent. Because indexing is not supported, the Oracle Tuxedo system recognizes only the first occurrence of a given element type when processing an XML buffer for data-dependent routing.
|
|
The RANGES
parameter allows you to map field values to a group name as follows:
RANGES=”[
val1
[-
val2
]:
group1
] [,
val3
[-
val4
]:
group2
]...[,*:
groupn
]”
where val1
, val2
, and so on, are values of a field and groupn
may be either a group name or the wildcard character (*) denoting that any group may be selected. The * character occupying the place of val
at the end is a catch-all choice, that is, it specifies if the data does not fall into any range that has been specified then it goes to the default group on the other hand if the data fall into the range but there is no viable server in the group associated with the range entry, then the service request is forwarded to the default group specified on the wildcard “*
” range entry. The value of val1
may be:
There is no limit to the number of ranges that may be specified, but routing information incurs a cost because it is stored in shared memory.
Note: | Overlapping ranges are allowed, but values that belong to both ranges map to the first group. For example, if RANGES is specified as RANGES=”0-5:Group1,3-5:Group2" , then a range value of 4 routes to Group1 . |
For Oracle Tuxedo data-dependent routing, the BUFTYPE
parameter determines the buffer type allowed. This parameter is similar to its SERVICES
section counterpart in that it restricts the routing criteria to a specific set of buffer types and subtypes. Only FML
, XML
and VIEW
types can be used for routing. The syntax is the same as the syntax in the SERVICES
section, a semicolon-separated list of
type:subtype[,subtype]
. You can specify only one type for routing criteria. This restriction limits the number of buffer types allowed in routing services.
The CORBA University Production sample application demonstrates how to implement factory-based routing in Oracle Tuxedo. You can find the ubb_p.nt
or ubb_p.mk
UBBCONFIG
files for this sample in the directory where the Oracle Tuxedo software is installed. Look in the \samples\corba\university\production
subdirectory.
The following INTERFACES, ROUTING,
and GROUPS
sections from the ubb_b.nt
configuration file show how you can implement factory-based routing in a CORBA application in Oracle Tuxedo.
The INTERFACES
section lists the names of the interfaces for which you want to enable factory-based routing. For each interface, this section specifies what kinds of criteria the interface routes on. This section specifies the routing criteria via an identifier, FACTORYROUTING
, as in the example in Listing 3-5.
*INTERFACES
"IDL:beasys.com/UniversityP/Registrar:1.0"
FACTORYROUTING = STU_ID
"IDL:beasys.com/BillingP/Teller:1.0"
FACTORYROUTING = ACT_NUM
The preceding example shows the fully qualified interface names for the two interfaces in the Production sample in which factory-based routing is used. The FACTORYROUTING
identifier specifies the names of the routing values, which are STU_ID
and ACT_NUM
, respectively.
The ROUTING
section specifies the following data for each routing value:
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.
FIELD
parameter, which specifies the variable name that the factory inserts as the routing value. In the Production sample, the field parameters are student_id
and account_number
, respectively. FIELDTYPE
parameter, which specifies the data type of the routing value. In the Production sample, the field types for student_id
and account_number
are long. RANGES
parameter, which associates a server group with a subset of the valid ranges for each routing value.
Listing 3-6 shows 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"
The preceding example shows that Registrar objects for students with IDs in one range are instantiated to one server group, and Registrar objects for students with IDs in another range are instantiated in another group. Likewise, Teller objects for accounts in one range are instantiated to one server group, and Teller objects for accounts in another range are instantiated in another group.
The groups specified by the RANGES
identifier in the ROUTING
section of the UBBCONFIG
file need to be identified and configured. For example, the Production sample specifies four groups: ORA_GRP1
, ORA_GRP2
, APP_GRP1
, and APP_GRP2
. These groups need to be configured, and the machines where they run need to be identified.
Listing 3-7 shows the GROUPS
section of the Production sample UBBCONFIG
file. Notice how the names in the GROUPS
section match the group names specified in the ROUTING
section; this is critical for factory-based routing to work correctly. Furthermore, any change in the way groups are configured in an application must be reflected in the ROUTING
section. (Note that the Production sample packaged with the Oracle Tuxedo 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 = 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"
Listing 3-8 shows how the INTERFACES
section extends the Bankapp sample application to use factory-based routing. The sample included with the Oracle Tuxedo software does not contain these parameter settings.
*INTERFACES
"IDL:BankApp/Teller:1.0"
FACTORYROUTING=atmID
*ROUTING
atmID
TYPE = FACTORY
FIELD = "atmID"
FIELDTYPE = LONG
RANGES = "1-5:BANK_GROUP1,
6-10: BANK_GROUP2,
*:BANK_GROUP1
*GROUPS
SYS_GRP
LMID = SITE1
GRPNO = 1
BANK_GROUP1
LMID = SITE1
GRPNO = 2
BANK_GROUP2
LMID = SITE1
GRPNO = 3
In this example, the IDL:Bankapp/Teller
interface employs a factory-based routing scheme called atmID
, as defined in the ROUTING
section. The example indicates that the processing will be distributed across the following two server groups:
To configure a multicontexted application, edit your UBBCONFIG
file as usual and add those parameters, listed in the following table, that are needed for your application. Use a text editor or the Oracle Tuxedo Administration Console.
When making an existing server multithreaded, an experienced programmer must verify that the source code for the server has been written in a thread-safe manner. In other words, it is not possible to convert a single-threaded server, written with static variables, to a multithreaded server simply by increasing the value of
MAXDISPATCHTHREADS in the configuration file. This server must also be built for multithreading.
|
||
Compiling a configuration file means generating a binary version of the file (TUXCONFIG
) from the text version (UBBCONFIG
). To compile a configuration file, run the tmloadcf
command. tmloadcf
parses a UBBCONFIG
file and loads the binary file.
tmloadcf
reads a file (or standard input written in UBBCONFIG
syntax), checks the syntax, and optionally loads a binary configuration file called TUXCONFIG
. The TUXCONFIG
and (optionally) TUXOFFSET
environment variables point to the TUXCONFIG
file and (optional) offset where the information should be stored. You can run tmloadcf
only on the machine designated as MASTER
in the RESOURCES
section of the UBBCONFIG
file, unless the -c
or -n
option is specified.
Notes: | The user identifier (UID ) of the person running tmloadcf must match the UID , if specified, in the RESOURCES section of the UBBCONFIG file. |
Note: | The pathname specified for the TUXCONFIG environment variable must match exactly (including case) the pathname specified for TUXCONFIG parameter within the MACHINES section of the UBBCONFIG file. Otherwise, tmloadcf(1) cannot be run successfully. |