11 Creating the Configuration File for a Distributed Oracle Tuxedo ATMI Application
This section includes the following topics:
Note:
For detailed information about creating a configuration file for a distributed Oracle Tuxedo CORBA application, refer to the Scaling, Distributing, and Tuning CORBA Applications guide.- Configuration File Requirements for a Distributed Oracle Tuxedo ATMI Application
- Creating the RESOURCES Section
- Creating the MACHINES Section
- Creating the GROUPS Section
- Creating the SERVICES Section
- Creating the ROUTING Section
- Example Configuration File for a Distributed Application
- Modifying the Domain Gateway Configuration File to Support Routing
11.1 Configuration File Requirements for a Distributed Oracle Tuxedo ATMI Application
A distributed Oracle Tuxedo ATMI application consists of one or more local or remote clients that communicate with one or more servers residing on several machines linked through a network, all of which are administered as a single entity in one Oracle Tuxedo configuration file. To set up a distributed configuration, you must create a configuration file that includes the following sections:
- RESOURCES section
- MACHINES section
- GROUPS section
- NETGROUPS section (optional)
- NETWORK section
- SERVICES section
- ROUTING section (if data-dependent routing is used)
If your configuration spans multiple domains and uses
data-dependent routing, you must also modify the domain gateway
configuration file (DMCONFIG
) to support routing
functionality.
11.2 Creating the RESOURCES Section
In the RESOURCES
section you define governing
parameters for system-wide resources, such as the maximum number of
servers allowed in the application. All parameter settings in this
section apply to the entire application.
Note:
The parameters described in the tables in this topic are used only for distributed applications. For a description of the basic parameters that are available for any kind of Oracle Tuxedo application, see UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.The following table shows the resources section parameters.
Table 11-1 RESOURCES Section Parameters
Parameter | Description |
---|---|
BBLQUERY (Optional)
|
BBLQUERY sets a multiplier of the basic SCANUNIT between status checks by the DBBL of all BBLs. The DBBL checks to ensure that all BBLs have reported in within the BBLQUERY cycle. If a BBL has not been heard from, the DBBL sends a message to that BBL asking for status. If no reply is received, the BBL is partitioned.
The value of |
BLOCKTIME (Optional)
|
BLOCKTIME sets a multiplier of the basic SCANUNIT after which a blocking call (for example, receiving a reply) times out.
The value of |
DBBLWAIT (Optional)
|
DBBLWAIT sets a multiplier of the basic SCANUNIT for the maximum amount of wall time a DBBL should wait for replies from all its BBLs before timing out. Every time the DBBL forwards a request to its BBLs, it waits for all of them to reply with a positive acknowledgment before replying to the requester. This option can be used for detecting dead or insane BBLs in a timely manner.
The value of |
IPCKEY (Required)
|
IPCKEY specifies the numeric key for the bulletin board. In a single-processor environment, this key names the bulletin board. In a multiprocessor environment, this key names the message queue of the DBBL. This key is also used as a basis for deriving the names of resources other than this well-known address, such as the names for bulletin boards throughout a multiprocessor.
The value of |
MASTER (Required)
|
MASTER (string_value1[,string_value2]) specifies the LMID of the machine on which the master copy of TUXCONFIG is located. Also, if the application is run in MP mode, MASTER indicates the machine on which the DBBL is run. string_value2 names an alternate LMID location used during process relocation and booting. If the primary location is not available, the DBBL is booted at the alternate location and the alternate TUXCONFIG file found there is used.
The value of both string_value1 and string_value2 must be LMIDs of machines defined in the |
MAXGROUPS (Optional)
|
MAXGROUPS specifies the maximum number of configured server groups to be accommodated in the group table of the bulletin board.
The value of |
MAXSERVERS (Optional)
|
MAXSERVERS specifies the maximum number of servers to be accommodated in the server table of the bulletin board.
The value of |
MAXSERVICES (Optional)
|
MAXSERVICES specifies the maximum number of services to be accommodated in the services table of the bulletin board.
The value of |
SANITYSCAN (Optional)
|
SANITYSCAN sets a multiplier of the basic SCANUNIT between sanity checks of the system.
The value of Sanity checks are performed on servers as well as on the bulletin board data structure itself. |
SCANUNIT (Optional)
|
SCANUNIT sets the time interval (in seconds) between scans by the bulletin board liaison for timed-out transactions and blocking calls within service requests. This value is used as the basic unit of scanning by the BBL. It affects the granularity with which transaction timeout values can be specified on tpbegin(3c) and the blocking timeout value specified with the BLOCKTIME parameter. The SANITYSCAN , BBLQUERY , DBBLWAIT , and BLOCKTIME parameters are multipliers of this unit for other timed operations within the system.
The value of |
11.3 Creating the MACHINES Section
In the MACHINES
section you assign logical names to
all the physical machines in your configuration (including all the
processing elements in multiprocessor machines) and define other
parameters for individual machines. The following table describes
the parameters available for defining machine names and other
machine-specific parameters for each machine that participates in a
distributed application.
Table 11-2 MACHINES Section Parameters
Parameter | Description |
---|---|
ENVFILE (Optional)
|
ENVFILE specifies a file that defines the environment with which all clients and servers on the machine are to be executed.
Lines must be in the form ident=value where ident contains only underscores and/or alphanumeric characters, and begins with an underscore or a letter of the alphabet. If the value of |
MAXACCESSERS (Optional)
|
MAXACCESSERS specifies the maximum number of processes that can access the bulletin board on this processor at any one time. When calculating the appropriate number, you are not required to count system administration processes, such as the BBL and tmadmin , but you must count all application servers and clients, and TMS servers.
The value of |
MAXCONV (Optional)
|
MAXCONV specifies the maximum number of simultaneous conversations allowed for processes on a particular machine.
The value of |
MAXWSCLIENTS (Optional)
|
MAXWSCLIENTS specifies the number of accesser entries on this processor to be reserved for Workstation clients only. This parameter is used only when the Oracle Tuxedo System Workstation component is used. This number takes a portion of the total accesser slots specified with MAXACCESSERS . The appropriate setting of this parameter helps conserve IPC resources because Workstation client access to the system is multiplexed through an Oracle Tuxedo system-supplied surrogate, the workstation handler.
The value of |
11.4 Creating the GROUPS Section
In the GROUPS
section you identify each server
group in your application so that the Oracle Tuxedo system can
route requests to the member servers of specific groups.
The GROUPS
section is populated with the number of
server groups required for the application. Server groups can all
reside on the same site (SHM
mode) or, in a
distributed application, they can reside on different sites
(MP
mode).
Parameters in the GROUPS
section implement two
important aspects of distributed transaction processing:
- They associate a group of servers with a particular
LMID
and a particular instance of a resource manager. - By allowing a second
LMID
to be associated with the server group, they name an alternate machine to which a group of servers can be migrated if theMIGRATE
option is specified.
The following table describes the parameters in the
GROUPS
section.
Table 11-3 GROUPS Section Parameters
Parameter | Description |
---|---|
ENVFILE
|
ENVFILE specifies a file that defines the environment with which all servers in the group are executed.
Lines must be in the form ident=value where ident contains only underscores and/or alphanumeric characters. If the value of |
GRPNO (Required)
|
GRPNO associates a number with a particular server group.
The number must be greater than 0 and less than 30,000. It must be unique among entries in the |
LMID (Required)
|
LMID identifies the machine on which the server group being defined runs. A second LMID value can be specified (separated from the first by a comma) for an alternate machine to which this server group can be migrated if the MIGRATE option has been specified. Servers in the group can be migrated if RESTART=Y to migrate is specified in the GROUPS section.
The values of |
11.5 Creating the SERVICES Section
The SERVICES
section contains parameters that
determine how application services are handled. Every line of every
entry in this section is associated with a service by its
identifier name.
You must identify the service provided by each server group in
the SERVICES
section. Because the same service can be
link edited with more than one server, the SRVGRP
parameter is provided to tie the parameters for an instance of a
service to a particular group of servers.
The following table describes the parameters in the
SERVICES
section that are available for defining
distributed applications.
Table 11-4 SERVICES Section Parameters
Parameter | Description |
---|---|
LOAD (Optional)
|
LOAD specifies the size of the load imposed by SVCNM on the system.
The value of |
PRIO (Optional)
|
PRIO specifies the dequeuing priority of SVCNM .
The value of |
ROUTING (Optional)
|
ROUTING specifies the name of the routing criteria used for this service when data-dependent routing is being performed. If this parameter is not specified, data-dependent routing is not performed for this service.
The value of |
SRVGRP (Optional)
|
SRVGRP specifies the host server group for the service that is specified by SVCNM and controlled by the parameters set in this section.
By setting SRVGRP, you can assign different parameter settings to the same service when it is offered by different server groups. For example, suppose your application provides two server groups, The value of SRVGRP may contain up to 30 characters.
|
SVCTIMEOUT (Optional)
|
SVCTIMEOUT specifies the amount of time, in seconds, that is allowed for processing of the indicated service. A timed-out service causes the server processing the service request to be terminated with a SIGKILL signal.
The value of |
If your application includes transaction processing, you may also want to set three other parameters in the SERVICES
section: AUTOTRAN
, ROUTING
, and TRANTIME
. These parameters are described in Configuring Your ATMI Application to Use Transactions.
The following listing shows a sample of the
SERVICES
section.
*SERVICES
WITHDRAW ROUTING=ACCOUNT_ID
DEPOSIT ROUTING=ACCOUNT_ID
OPEN_ACCT ROUTING=BRANCH_ID
11.6 Creating the ROUTING Section
In the ROUTING
section you specify the criteria to be used when
data-dependent routing is performed. If a service is listed in multiple entries, each with a
different SRVGRP
parameter, the ROUTING
section must be set
with the same value in all entries. Otherwise, routing cannot be done consistently for that
service. Because a service can be routed on one field only, the value of that field must be
the same in all entries for the same service.
You can add a ROUTING
section to the configuration file to show mappings
between data ranges and groups. The information in this section enables the system to send a
request to a server in a specific group. Each ROUTING
section item contains
an identifier that is used in the SERVICES
section.
Lines within the ROUTING
section have the following form.
CRITERION_NAME required_parameters
where
CRITERION_NAME
is the name of the routing entry specified in the SERVICES
section
for data-dependent routing. The value of
CRITERION_NAME
must be a string with a maximum of 15 characters.
The following table describes the parameters in the ROUTING
section.
Table 11-5 ROUTING Section Parameters
Parameter | Description |
---|---|
RANGES
|
Ranges and associated server groups for the routing field. |
FIELD
|
Name of the routing field, which is assumed to be one of the following: an FML buffer, an XML element or element 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 when sending a message.
|
BUFTYPE
|
A list of types and subtypes of data buffers for which this routing entry is valid.
The value of this parameter may contain up to 256 characters with a maximum of 32 type/subtype combinations. |
See Also:
- How to Create the Configuration File for a Multiple-machine (Distributed) Application
- UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
- Scaling, Distributing, and Tuning CORBA Applications
11.7 Example Configuration File for a Distributed Application
The following excerpt from a sample UBBCONFIG
file
shows the GROUPS
, SERVICES
, and
ROUTING
sections, which support data-dependent routing
in an Oracle Tuxedo application.
*GROUPS
BANKB1 GRPNO=1
BANKB2 GRPNO=2
BANKB3 GRPNO=3
#
*SERVICES
WITHDRAW ROUTING=BY_ACCOUNT_ID
DEPOSIT ROUTING=BY_ACCOUNT_ID
INQUIRY ROUTING=BY_ACCOUNT_ID
OPEN_ACCT ROUTING=BY_BRANCH_ID
CLOSE_ACCT ROUTING=BY_BRANCH_ID
#
*ROUTING
BY_ACCOUNT_ID FIELD=ACCOUNT_ID BUFTYPE=”FML”
RANGES=”MIN - 9999:*,
10000-49999:BANKB1,
50000-79999:BANKB2,
80000-109999:BANKB3,
*:*”
BY_BRANCH_ID FIELD=BRANCH_ID BUFTYPE=”FML”
RANGES=”MIN - 0:*,
1-4:BANKB1,
5-7:BANKB2,
8-10:BANKB3,
*:*”
11.8 Modifying the Domain Gateway Configuration File to Support Routing
All domain gateway configuration information is stored in a
binary file called BDMCONFIG
. This file is created by
first writing a text configuration file called
DMCONFIG
and then compiling it into a binary version
called BDMCONFIG
. The compiled BDMCONFIG
file can be updated while the system is running by using the
dmadmin(1)
command. Although the Oracle Tuxedo
documentation refers to these configuration files as
DMCONFIG
and BDMCONFIG
, you can give
these files any names.
You must have one BDMCONFIG
file for each Oracle
Tuxedo application to which you want to add Domains functionality.
System access to the BDMCONFIG
file is provided
through the Domains administrative server, DMADM(5)
.
When a gateway group is booted, the gateway administrative server,
GWADM(5)
, requests from the DMADM
server
a copy of the configuration required by that group. The
GWADM
server and the
server also ensure that run-time changes to the configuration are
reflected in the corresponding domain gateway groups.
DMADM
Note:
For more information about theDMCONFIG
file, refer to DMCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.
11.8.1 Description of ROUTING Section Parameters in DMCONFIG
The DM_ROUTING
section provides information for data-dependent routing of
service requests using FML
, XML
, VIEW
,
X_C_TYPE
, and X_COMMON
typed buffers. Lines within the
DM_ROUTING
section have the following form.
CRITERION_NAME required_parameters
where
CRITERION_NAME
is the name of the routing entry specified in the SERVICES
section.
The value of
CRITERION_NAME
must be a string with a maximum of 15 characters.
The following table describes the parameters in the DM_ROUTING
section.
Parameter | Description |
---|---|
FIELD (Optional)
|
Specifies the name of the routing field, which is assumed to be one of the following: an FML buffer, an XML element or element 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 when sending a message.
If a field in an |
RANGES (Optional)
|
Specifies the ranges and associated remote domain names (RACCESSPOINT ) for the routing field. The value of RANGES must be a string enclosed in double quotes. The enclosed string, in turn, must consist of a comma-separated ordered list of range/RACCESSPOINT pairs.
The value of lower must be less than or equal to upper . A single quote embedded in a character string value, as in “O’Brien,” for example, must be preceded by two back slashes: “O\\’Brien”.
Use MAX to indicate the maximum value for the data type of the associated FIELD . For strings and carrays, it is effectively an unlimited string of octal-255 characters; for a character field, it is a single octal-255 character; for numeric values, it is the maximum numeric value that can be stored in the field. Thus, MIN - -5 is all numbers less than or equal to -5 , and 6 - MAX is all numbers greater than or equal to 6 .
The metacharacter * (wildcard) in the position of a range indicates any values not covered by other ranges previously seen in the entry. Only one wildcard range is allowed per entry and it should be listed last (ranges following it are ignored). |
BUFTYPE (Optional)
|
BUFTYPE provides a list of types and subtypes of data buffers for which this routing entry is valid. Valid types are FML , VIEW , X_C_TYPE , and X_COMMON . No subtype can be specified for type FML, and subtypes are required for the other types (* is not allowed). Duplicate type/subtype pairs cannot be specified for the same routing criteria name; more than one routing entry can have the same criteria name as long as the type/subtype pairs are unique.
If multiple buffer types are specified for a single routing entry, the data types of the routing field for each buffer type must be the same. If the field value is not set (for |
11.8.1.1 Routing Field Description
The value in the routing field can be any data type supported in
FML
or VIEW
; it may be a numeric range or
a string range. The following rules apply to string range values
for string, carray, and character field types:
- They must be enclosed by single quotation marks and cannot be preceded by a plus or minus sign.
- A short or long integer value must be a string of digits, optionally preceded by a plus or minus sign.
- Floating point numbers must be written in the form required by
the C compiler or
atof()
: a plus or minus sign, followed by a string of digits (optionally containing a decimal point), then an optionale
orE
followed by an optional sign or space, followed by an integer. - When a field value matches a range, the associated
RACCESSPOINT
value specifies the remote domain to which the request should be routed. AnRACCESSPOINT
value of*
indicates that the request may be sent to any remote domain known by the gateway group. Within arange/RACCESSPOINT
pair, the range must be separated from theRACCESSPOINT
by a: (colon).
Parent topic: Description of ROUTING Section Parameters in DMCONFIG
11.8.1.2 Example of a 5-Site Domain Configuration Using Routing
The following sample configuration file defines a two-domain application distributed across five sites. The five sites include a Central Bank Office and four bank branches. Three of the branches belong to an Oracle Tuxedo domain. The fourth branch belongs to another TP domain, and OSI-TP is used to communicate with that domain.
The following Listing shows the Oracle Tuxedo system domain
gateway configuration file from the Central Bank point of view. In
the DM_TDOMAIN
section, this example shows a mirrored
gateway for b01
.
Listing Domains Configuration File for Five Sites
# TUXEDO DOMAIN CONFIGURATION FILE FOR THE CENTRAL BANK
#
#
*DM_LOCAL
# local_domain_name Gateway_Group_name domain_type domain_ID log_device
# [audit log] [blocktime]
# [log name] [log offset] [log size]
# [maxaccesspoint] [maxraptran] [maxtran]
# [maxdatalen] [security]
# [tuxconfig] [tuxoffset]
#
#
DEFAULT: SECURITY = NONE
c01 GWGRP = bankg1
TYPE = TDOMAIN
ACCESSPOINTID = "BA.CENTRAL01"
DMTLOGDEV = "/usr/apps/bank/DMTLOG"
DMTLOGNAME = "DMTLG_C01"
c02 GWGRP = bankg2
TYPE = OSITP
ACCESSPOINTID = "BA.CENTRAL01"
DMTLOGDEV = "/usr/apps/bank/DMTLOG"
DMTLOGNAME = "DMTLG_C02"
NWDEVICE = "OSITP"
URCH = "ABCD"
#
*DM_REMOTE
#remote_domain_name domain_type domain_ID
#
b01 TYPE = TDOMAIN
ACCESSPOINTID = "BA.BANK01"
b02 TYPE = TDOMAIN
ACCESSPOINTID = "BA.BANK02"
b03 TYPE = TDOMAIN
ACCESSPOINTID = "BA.BANK03"
b04 TYPE = OSITP
ACCESSPOINTID = "BA.BANK04"
URCH = "ABCD"
#
*DM_TDOMAIN
#
# local_or_remote_domain_name network_address [nwdevice]
#
# Local network addresses
c01 NWADDR = "//newyork.acme.com:65432" NWDEVICE ="/dev/tcp"
c02 NWADDR = "//192.76.7.47:65433" NWDEVICE ="/dev/tcp"
# Remote network addresses: second b01 specifies a mirrored gateway
b01 NWADDR = "//192.11.109.5:1025" NWDEVICE = "/dev/tcp"
b01 NWADDR = "//194.12.110.5:1025" NWDEVICE = "/dev/tcp"
b02 NWADDR = "//dallas.acme.com:65432" NWDEVICE = "/dev/tcp"
b03 NWADDR = "//192.11.109.156:4244" NWDEVICE = "/dev/tcp"
#
*DM_OSITP
#
#local_or_remote_domain_name apt aeq
# [aet] [acn] [apid] [aeid]
# [profile]
#
c02 APT = "BA.CENTRAL01"
AEQ = "TUXEDO.R.4.2.1"
AET = "{1.3.15.0.3},{1}"
ACN = "XATMI"
b04 APT = "BA.BANK04"
AEQ = "TUXEDO.R.4.2.1"
AET = "{1.3.15.0.4},{1}"
ACN = "XATMI"
*DM_EXPORT
#service_name [Local_Domain_name] [access_control] [exported_svcname]
# [inbuftype] [outbuftype]
#
open_act ACL = branch
close_act ACL = branch
credit
debit
balance
loan LACCESSPOINT = c02 ACL = loans
*DM_IMPORT
#service_name [Remote_domain_name] [local_domain_name]
# [remote_svcname] [routing] [conv]
# [trantime] [inbuftype] [outbuftype]
#
tlr_add LACCESSPOINT = c01 ROUTING = ACCOUNT
tlr_bal LACCESSPOINT = c01 ROUTING = ACCOUNT
tlr_add RACCESSPOINT = b04 LACCESSPOINT = c02 RNAME ="TPSU002"
tlr_bal RACCESSPOINT = b04 LACCESSPOINT = c02 RNAME ="TPSU003"
*DM_ROUTING
# routing_criteria field typed_buffer ranges
#
ACCOUNT FIELD = branchid BUFTYPE ="VIEW:account"
RANGES ="MIN - 1000:b01, 1001-3000:b02, *:b03"
*DM_ACCESS_CONTROL
#acl_name Remote_domain_list
#
branch ACLIST = b01, b02, b03
loans ACLIST = b04
See Also:
- “Understanding the Domains Configuration File” in Using the Oracle Tuxedo Domains Component
- “Setting Up a Domains Configuration” in Using the Oracle Tuxedo Domains Component
- Scaling, Distributing, and Tuning CORBA Applications
Parent topic: Description of ROUTING Section Parameters in DMCONFIG