Creating the Configuration File for a Distributed 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:

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.

Table 10-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 1,048,575. 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 2 or 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 10-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:

Table 10-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.

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.

*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.

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.

Table 10-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

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.

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.

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:

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.

# 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

Setting Up a BEA Tuxedo Application

Creating the Configuration File for a Distributed ATMI Application

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

See Also

Example Configuration File for a Distributed Application

Modifying the Domain Gateway Configuration File to Support Routing

Description of ROUTING Section Parameters in DMCONFIG

Routing Field Description

Example of a 5-Site Domain Configuration Using Routing

See Also