Creating the Configuration File for a Distributed ATMI Application

This section includes the following topics:

• Configuration File Requirements for a Distributed BEA 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

Note: For detailed information about creating a configuration file for a distributed BEA Tuxedo CORBA application, refer to the Scaling, Distributing, and Tuning CORBA Applications guide.

 

---

Configuration File Requirements for a Distributed BEA Tuxedo ATMI Application

A distributed BEA 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 BEA 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.

 

---

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 BEATuxedo application, see UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

Table 8-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 BBLQUERY must be greater than 0. If this parameter is not specified, the default is set so that (SCANUNIT * BBLQUERY) is approximately 300 seconds.
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 BLOCKTIME must be greater than 0. If this parameter is not specified, the default is set so that (SCANUNIT * BLOCKTIME) is approximately 60 seconds.
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 DBBLWAIT must be greater than 0. If this parameter is not specified, the default is set so that (SCANUNIT * DBBLWAIT) is the greater of SCANUNIT or 20 seconds.
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 IPCKEY must be greater than 32,768 and less than 262,143.
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 MACHINES section. Each string may contain up to 30 characters.
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 MAXGROUPS must be greater than or equal to 100 and less than 32,768. The default is 100.
MAXSERVERS (Optional)	MAXSERVERS specifies the maximum number of servers to be accommodated in the server table of the bulletin board. The value of MAXSERVERS must be greater than 0 and less than 8192. The default is 50.
MAXSERVICES (Optional)	MAXSERVICES specifies the maximum number of services to be accommodated in the services table of the bulletin board. The value of MAXSERVICES must be greater than 0 and less than 32,768. The default is 100.
SANITYSCAN (Optional)	SANITYSCAN sets a multiplier of the basic SCANUNIT between sanity checks of the system. The value of SCANUNIT must be greater than 0. The default is set so that (SCANUNIT * SANITYSCAN) is approximately 120 seconds. 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 SCANUNIT must be a multiple of 5 greater than 0 and less than or equal to 60 seconds. The default is 10 seconds.

 

 

---

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 8-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 ENVFILE is an invalid filename, no values are added to the environment.
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 MAXACCESSERS must be greater than 0 and less than 32,768. The default is the value specified in the RESOURCES section.
MAXCONV (Optional)	MAXCONV specifies the maximum number of simultaneous conversations allowed for processes on a particular machine. The value of MAXCONV must be greater than 0 and less than 32,768. The maximum number of simultaneous conversations per server is 64. The default is the value specified in the RESOURCES section.
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 BEA 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 a BEA Tuxedo system-supplied surrogate, the workstation handler. The value of MAXWSCLIENTS must be greater than or equal to 0, and less than 32,768; it may not be greater than the value of MAXACCESSERS. (Assigning a value to MAXWSCLIENTS that is higher than the value of MAXACCESSERS is an error.) The default is 0.

 

 

---

Creating the GROUPS Section

In the GROUPS section you identify each server group in your application so that the BEA 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 the MIGRATE option is specified.

The following table describes the parameters in the GROUPS section.

Table 8-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 ENVFILE is an invalid filename, no values are added to the environment.
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 GROUPS section.
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 LMID must be the values assigned to the LMID parameter in the MACHINES section.

 

 

---

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 8-4 SERVICES Section Parameters

Parameter	Description
LOAD (Optional)	LOAD specifies the size of the load imposed by SVCNM on the system. The value of LOAD must be a number between 1 and 32,767, inclusive. A higher number indicates a greater load. The default is 50.
PRIO (Optional)	PRIO specifies the dequeuing priority of SVCNM. The value of PRIO must be greater than 0 and less than or equal to 100, with 100 being the highest priority. The default is 50.
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 ROUTING may contain up to 15 characters. If multiple entries exist for the same service name but with different SRVGRP parameters, the ROUTING parameter must be the same for all entries.
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, GROUP1 and GROUP2, that offer a service called WITHDRAW. By setting SRVGRP you can assign different load factors to each copy of the service, as follows: WITHDRAW ROUTING=123 LOAD=60 SRVGRP=GROUP1 WITHDRAW ROUTING=123 LOAD=60 SRVGRP=GROUP2 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 SVCTIMEOUT must be greater than or equal to 0. A value of 0 indicates that the service will not be timed out. The default is 0.

 

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

 

---

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 8-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

 

---

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 a BEA 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,
                        *:*"

 

---

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 BEA 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 BEA 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 DMADM server also ensure that run-time changes to the configuration are reflected in the corresponding domain gateway groups.

Note: For more information about the DMCONFIG file, refer to DMCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

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 FML32 buffer is used for routing, it must have a field number less than or equal to 8191.
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 range may be either a single value (a signed numeric value or a character string enclosed in single quotes), or a range of the form lower - upper (where lower and upper are both signed numeric values or character strings in single quotes). 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 MIN to indicate the minimum value for the data type of the associated FIELD. For strings and carrays, it is the null string; for character fields, it is 0; for numeric values, it is the minimum numeric value that can be stored in the field. 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 FML buffers), or does not match any specific range, and a wildcard range has not been specified, an error is returned to the application process that requested the execution of the remote service.

 

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 optional e or E 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. An RACCESSPOINT value of * indicates that the request may be sent to any remote domain known by the gateway group. Within a range/RACCESSPOINT pair, the range must be separated from the RACCESSPOINT by a: (colon).

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 a BEA Tuxedo domain. The fourth branch belongs to another TP domain, and OSI-TP is used to communicate with that domain.

The example shows the BEA 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 8-1 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" on page 1-16 in Using the BEA Tuxedo Domains Component

• "Setting Up a Domains Configuration" on page 2-27 in Using the BEA Tuxedo Domains Component

• Scaling, Distributing, and Tuning CORBA Applications