|
•
|
UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
|
Figure 3‑1 shows the configuration tasks for a sample multiple-domain application.
Figure 3‑2 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.
|
•
|
“About Domains” in Using the Oracle Tuxedo Domains Component
|
|
•
|
“Planning and Configuring ATMI Domains” in Using the Oracle Tuxedo Domains Component
|
|
•
|
DMCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
|
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.
|
|
|
|
|
|
|
|
|
|
UID, GID, and PERM (Optional)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
MODEL, SHM or MP, and LAN or MIGRATE options (Required)
|
|
|
|
SECURITY, AUTHSVC (Optional)
|
|
|
|
SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, and SEC_PRINCIPAL_PASSVAR
|
|
|
|
NOTIFY, USIGNAL (Optional)
|
|
|
|
|
|
|
|
|
|
|
|
MAXBUFTYPE, MAXBUFSTYPES (Optional)
|
|
|
|
|
|
|
|
|
|
|
|
SCANUNIT, SANITYSCAN, BLOCKTIME (Optional)
|
|
|
•
|
UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
|
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).
Table 3‑2 shows the characteristics of the model and OPTIONS parameters.
The MAXCONV parameter has the following characteristics:
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.
|
|
|
|
|
The value of MAXACCESSERS must be greater than 0 and less than 32,768. If not specified, the default is 50. You can overwrite MAXACCESSERS, on a per-machine basis, in the MACHINES section.
|
|
|
The value of MAXSERVERS must be greater than 0 and less than 8,192. If not specified, the default is 50.
|
|
|
|
|
|
|
|
|
|
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.
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 LDBAL parameter has the following characteristics:
|
•
|
If LDBAL is set to Y, then load balancing is used.
|
|
•
|
If LDBAL is set to Y and the application is networked, you can use TMNETLOAD for local preference.
|
|
•
|
If LDBAL is set to N, the server assigned is the first available server.
|
|
•
|
Because LDBAL incurs overhead, use it only when necessary.
|
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:
|
•
|
Two LMIDs are required for migration to back up the master machine.
|
|
•
|
In the sample RESOURCES section, the master site is SITE1; the backup site is SITE2.
|
Site1 is the
MASTER machine;
SITE2 is the backup machine.
Use the SANITYSCAN parameter to specify how many
SCANUNITs elapse between sanity checks of the servers. Its current default is set so that
SANITYSCAN *
SCANUNIT is approximately 120 seconds.
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.
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.
|
•
|
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.
|
|
•
|
“Introducing ATMI Security” in Using Security in ATMI Applications
|
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_PASSVAR—specifies the environment variable that contains the password used to open the private key of the principal user.
|
|
•
|
“Administering Security” in Using Security in CORBA Applications
|
|
•
|
PROTECTED—Oracle Tuxedo libraries compiled with application code do not attach to shared memory while executing system code.
|
|
•
|
FASTPATH—Oracle Tuxedo libraries attach to shared memory at all times.
|
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:
|
•
|
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().
|
|
•
|
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.
|
|
|
|
|
Value of IGNORE means clients should ignore unsolicited messages.
Value of DIPIN means clients should receive unsolicited messages only when they call tpchkunsol() or when they make an ATMI call.
Value of SIGNAL means clients should receive unsolicited messages by signals.
|
|
|
Value of SIGUSR1 and SIGUSR2 means notify clients with this type of signal.
|
|
•
|
UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
|
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:
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.
|
•
|
“What Is Load Balancing?” in Introducing Oracle Tuxedo ATMI
|
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 LMID is specified as follows:
|
LMID=logical_machine_name
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.
Though the value of the SPINCOUNT parameter is application- and system-dependent, it may be helpful to keep the following basic guidelines in mind:
|
•
|
A SPINCOUNT value of 1 is appropriate for uniprocessors.
|
|
•
|
Set the 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 can be given any string value. It is used simply for comparisons.
|
|
•
|
The TYPE parameter should be used when the application involves a heterogeneous network of machines or when different compilers are used on the machines in the network.
|
The TUXCONFIG parameter has the following characteristics:
|
•
|
The value of TUXCONFIG must match the value of the TUXCONFIG environment variable.
|
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.
ENVFILE is an optional parameter with the following characteristics:
|
•
|
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.)
|
|
•
|
Set FIELDTBLS, FLDTBLDIR, and so on, but do not set TUXDIR and APPDIR.
|
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.
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.
|
•
|
When the BRIDGE requests an asynchronous connection
|
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.
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.)
|
•
|
The value of TUXOFFSET, if non-zero, is placed in the environment of all servers booted on a machine.
|
|
|
|
|
|
APPDIR identifies the location of application software.
APPDIR is a required parameter.
APPDIR becomes the current working directory of server processes.
|
|
|
TUXDIR identifies the location of the Oracle Tuxedo software.
TUXDIR is a required parameter.
|
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.
|
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.
|
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:
|
•
|
The ULOGPFX defaults to APPDIR/ULOG.
|
|
•
|
For the sample filename 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.
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 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.
|
|
|
|
|
|
|
|
|
LMID=string_value1 [ ,string_value2]
|
Each LMID value must be an alphanumeric string containing 30 or fewer characters.
|
|
•
|
UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
|
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.
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 (:).
|
•
|
On UNIX
OPENINFO = "TUXEDO/QM:qmconfig:qspace"
|
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.
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() 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:
When tmloadcf() encounters an encrypted password in a
UBBCONFIG file generated by
tmunloadcf(), it does not prompt the user to create a password.
|
•
|
UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
|
The listening address for a BRIDGE is the location at which it is contacted by other
BRIDGE processes participating in the application.
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.
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.
|
•
|
DEFAULTNET (the default network, which is the corporate WAN)
|
|
•
|
GREEN_GROUP (a private LAN that provides high-speed, fiber, point-to-point links between member machines)
|
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.
Figure 3‑3 shows machines A through E in the networks for which they have addresses.
Table 3‑7 shows which machines have addresses for which groups.
|
•
|
UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
|
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.
The SERVERS section of the configuration file contains information specific to a server process. While this section is not required, an application without this section has no application servers and little functionality. Each entry in this section represents a server process to be booted in the application and includes the following information:
|
Note:
|
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.
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
Specify -A on the command line of each server.
|
|
|
|
|
|
|
|
|
|
|
|
Three instances of the sample server will be booted in group GROUP1 with server IDs of 1, 2, and 3, respectively. The three servers will form an MSSQ set and will read requests from queue ring1.
|
Note:
|
RQADDR assigns a symbolic name to the request queue of this server. MSSQ sets are established by using the same symbolic queue name for more than one server, as well as same executable name for all the servers (and by specifying a value greater than 1 for MIN).
|
|
|
|
|
|
•
|
UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
|
The CONV parameter has the following characteristics:
|
•
|
A Y value indicates a server is conversational; an N value indicates a server is not conversational.
|
|
•
|
A Y value is required if the server is to receive conversational requests.
|
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.
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.
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.
|
2.
|
The TMFFNAME server with the -N option and the -M option, which starts the NameManager service (as a Master). This service maintains a mapping of application-supplied names to object references.
|
|
3.
|
The TMFFNAME server with the -N option only, to start a Slave NameManager service.
|
|
4.
|
The TMFFNAME server with the -F option, to start the FactoryFinder object.
|
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.
|
•
|
The univb_server, for the University Basic sample application. For details about the sample applications, see the Guide to the CORBA University Sample 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.
|
|
|
|
|
|
|
|
|
If RQADDR is specified and MIN>1, an MSSQ set is created.
|
|
|
The range of values for MAX is 0 to 1000. If MAX is not specified, the default is the value of MIN.
|
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).
Table 3‑9 provides a partial list of the available options.
|
•
|
Both main() and tpsvrinit() use server command-line options.
|
In the BANKAPP sample application, command-line options are specified as follows:
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.
|
•
|
servopts(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
|
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:
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.
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.
|
|
|
|
|
|
|
|
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 REPLYQs even if this parameter is not set.
|
|
|
Assigns permissions to the reply queue. This parameter is useful only when REPLYQ=Y. If requests and replies are read from the same queue, only RQPERM is needed; RPPERM is ignored.
|
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 (2
31 - 1).
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.
The SYSTEM_ACCESS parameter has the following characteristics:
|
•
|
A value of PROTECTED indicates that the server may not attach to shared memory outside of system code.
|
|
•
|
A value of FASTPATH indicates that the server will attach to shared memory at all times.
|
|
•
|
If NO_OVERRIDE is specified in the RESOURCES section, this parameter is ignored.
|
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.
|
•
|
UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
|
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.
|
|
•
|
For more information about MAXTRANTIME, see MAXTRANTIME in the RESOURCES section in UBBCONFIG(5) or TA_MAXTRANTIME in the T_DOMAIN class in TM_MIB(5).
|
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:
If the value of the BUFTYPE parameter for a service is
ALL, this service accepts all buffer types. The default is
ALL.
|
|
|
|
|
FML and VIEW buffer types with subtypes aud and aud2 are allowed.
|
|
|
All FML and VIEW buffer types are allowed.
|
|
|
|
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.
|
•
|
TPED_SVCTIMEOUT—timeout error detail that provides more information than tpstrerror(3c)
|
|
•
|
ULOG information about .SysServiceTimeout
|
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:
|
•
|
In addition to monitoring the ULOG file for service timeout activity, application operators can subscribe to the .SysServiceTimeout event, which alerts them when a service timeout occurs.
|
|
•
|
Application programmers can use the 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.
|
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.
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.
The LDBAL parameter has the following characteristics:
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.
The PRIO parameter has the following characteristics:
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.
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.
|
|
|
|
|
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.
|
|
|
Specify the dequeuing priority number for all methods of the CORBA interface. The value must be greater than 0 and less than or equal to 100. 100 is the highest priority. The default is 50.
|
|
|
Use SRVGRP to indicate that any parameter defined in this portion of the INTERFACES section applies to the interface within the specified server group. For a given CORBA interface, this feature lets you define different parameter values in different server groups.
|
|
|
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.)
|
|
|
|
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.
Listing 3‑4 shows how factory-based routing is specified in the Bankapp sample application.
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.
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.
The PRIO parameter has the following characteristics:
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).
|
|
|
|
|
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.
TP::create_object_reference (C++) or com.beasys.Tobj.TP::create_object_reference (Java) for the interface.
|
|
|
where type is one of the following: string, char, s hort, long, float, or double.
|
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:
|
•
|
A STRING or CARRAY buffer (enclosed in single quotation marks)
|
|
•
|
MIN or MAX, to show a machine minimum or maximum data value
|
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 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.
The ROUTING section specifies the following data for each routing value:
|
•
|
The TYPE parameter, which specifies the type of routing. In the Production sample, the type of routing is factory-based routing. Therefore, this parameter is defined to FACTORY.
|
|
•
|
The 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.
|
|
•
|
The 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.
|
|
•
|
The 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.
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.)
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.
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:
|
•
|
BANK_GROUP1 processes interfaces used by the application when the atmID field is between 1 and 5 (inclusive), or greater than 10.
|
|
•
|
BANK_GROUP2 processes interfaces used by the application when the atmID is between 6 and 10, inclusive.
|
|
|
|
|
|
|
|
Optional parameter, but you must assign a value to it you want more than 50 accessers (the default number).
|
|
|
Optional parameter that defines the default method to be used for unsolicited notification. Valid values for multicontexted applications are:
|
|
|
|
Optional parameter, but you must assign a value to it you want more than 50 accessers (the default number).
|
|
|
|
|
|
|
|
|
|
Required parameter in multithreaded servers.
|
|
|
|
tmloadcf reads a file (or standard input written in
UBBCONFIG syntax), checks the syntax, and optionally loads a binary configuration file called
TUXCONFIG. The
TUXCONFIG and (optionally)
TUXOFFSET environment variables point to the
TUXCONFIG file and (optional) offset where the information should be stored. You can run
tmloadcf only on the machine designated as
MASTER in the
RESOURCES section of the
UBBCONFIG file, unless the -
c or -
n option is specified.
|
Notes:
|
The user identifier (UID) of the person running tmloadcf must match the UID, if specified, in the RESOURCES section of the UBBCONFIG file.
|
The pathname specified for the TUXCONFIG environment variable must match exactly (including case) the pathname specified for
TUXCONFIG parameter within the
MACHINES section of the
UBBCONFIG file. Otherwise,
tmloadcf(1) cannot be run successfully.
