[Top] [Previous Page] [Next Page] [Bottom]


Chapter 5. Distributing Applications

This chapter discusses the following topics:

Why Distribute an Application?

Distributing an application enables you to select which parts of an application should be grouped together logically and where these groups should run. You distribute an application by creating more than one entry in the GROUPS section of the UBBCONFIG file, and by dividing application resources or tasks among the groups. Creating groups of servers enables you to partition a very large application into its component business applications and, in turn, to partition each of these applications into logical components of manageable size and optimal location.

Benefits of a Distributed Application

Characteristics of Distributing an Application

A distributed application has the following characteristics:

Using Data-dependent Routing

Data-dependent routing is a mechanism whereby a service request is routed by a client (or a server acting as a client) to a server within a specific group based on a data value contained within the buffer that is sent. Within the internal code of a service call, the BEA TUXEDO system chooses a destination server by comparing a data field with the routing criteria it finds in the Bulletin Board shared memory.

For any given service, a routing criteria identifier can be specified in the SERVICES section of the UBBCONFIG file. The routing criteria identifier, in particular, the mapping of data ranges to server groups, is specified in the ROUTING section.

Characteristics of Data-dependent Routing

Data-dependent routing has the following characteristics:

Example: A Distributed Application

The following table illustrates how client requests are routed to servers. In this example, a banking application called bankapp uses data-dependent routing. For bankapp, there are three groups (BANKB1, BANKB2, and BANKB3), and two routing criteria (Account ID and Branch ID). The services WITHDRAW, DEPOSIT, and INQUIRY are routed using the Account_ID field; the services OPEN and CLOSE are routed using the Branch_ID field.

Server Group Routing Criteria Used For These Services
BANKB1 Account_ID: 10000 - 49999 WITHDRAW, DEPOSIT, and INQUIRY
Branch_ID: 1 - 4 OPEN and CLOSE
BANKB2 Account_ID: 50000 - 79999 WITHDRAW, DEPOSIT, and INQUIRY
Branch_ID: 5 - 7 OPEN and CLOSE
BANKB3 Account_ID: 80000 - 109999 WITHDRAW, DEPOSIT, and INQUIRY
Branch_ID: 8 - 10 OPEN and CLOSE

Modifying and Creating the UBBCONFIG Sections for a Distributed Application

Data-dependent routing is described in the UBBCONFIG file, as follows:

Modifying the GROUPS Section

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. In addition, 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. Table 5-1 describes the parameters in the GROUPS section.

Table 5-1 Description of the GROUPS Section Parameters

Parameter Meaning
LMID LMID must be assigned in the MACHINES section. It indicates that this server group runs on this particular machine. A second LMID value can be specified (separated from the first by a comma) to name an alternate machine to which this server group can be migrated if the MIGRATE option has been specified. Servers in the group must specify RESTART=Y to migrate.
GRPNO GRPNO is a required parameter that associates a numeric group number with this server group. The number must be greater than 0 and less than 30000. It must be unique among entries in the GROUPS section in this configuration file.
TMSNAME Specifies which transaction management server (TMS) should be associated with this server group.
TMSCOUNT An optional parameter that can be used to specify how many copies of TMSNAME should be started for this server group. The minimum value is 2. If not specified, the default is 3. All TMSNAME servers started for a server group are automatically set up in an MSSQ set.
OPENINFO Specifies information needed to open a particular instance of a particular resource manager, or it indicates that such information is not required for this server group. When a resource manager is named in the OPENINFO parameter, information such as the name of the database and the access mode is included. The entire value string must be enclosed in double quotes and must not be more than 256 characters. The format of the OPENINFO string is dependent on the requirements of the vendor providing the underlying resource manager. The string required by the vendor must be prefixed with rm_name:, which is the published name of the vendor's transaction (XA) interface followed immediately by a colon (:).

The OPENINFO parameter is ignored if TMSNAME is not set or is set to TMS. If TMSNAME is set but the OPENINFO string is set to the null string ("") or if this parameter does not appear on the entry, it means that a resource manager exists for the group but does not require any information for executing an open operation.

CLOSEINFO Specifies information the resource manager needs when closing a database. The parameter can be omitted or the null string can be specified. The default is the null string.

Modifying the SERVICES Section

The SERVICES section contains parameters that control the way application services are handled. An entry line in this section is associated with a service by its identifier name. 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. Three parameters in the SERVICES section are particularly related to DTP: ROUTING, AUTOTRAN, and TRANTIME. Table 5-2 describes the parameters in the SERVICES section.

Table 5-2 Description of the SERVICES Section Parameters

Parameter Meaning
ROUTING The ROUTING parameter in the SERVICES section points to an entry in the ROUTING section where data-dependent routing is specified for transactions that request this service.
AUTOTRAN Setting the AUTOTRAN parameter to Y or N determines whether a transaction should be started automatically if a message received by this service is not already in transaction mode.The default is N. Use of the parameter should be coordinated with the programmers coding the services for your application.
TRANTIME The TRANTIME parameter sets a timeout value in seconds for transactions automatically started in this service. The default is 30 seconds. The TRANTIME parameter is needed only if AUTOTRAN =Y, and not even then if the default is acceptable.

Sample SERVICES Section

The following listing shows a sample SERVICES section. 

SERVICES

WITHDRAW  ROUTING=ACCOUNT_ID
DEPOSIT   ROUTING=ACCOUNT_ID
OPEN_ACCT ROUTING=BRANCH_ID

Creating the ROUTING Section

For information about ROUTING parameters that support the BEA TUXEDO system data-dependent routing, see Chapter 3, "Creating a Configuration File."

Example of UBBCONFIG Sections in a Distributed Application

The following UBBCONFIG file contains the GROUPS, SERVICES, and ROUTING sections of a configuration file to accomplish data-dependent routing in the BEA TUXEDO system. 

GROUPS
BANKB1            GRPNO=1
BANKB2            GRPNO=2
BANKB3            GRPNO=3
#
SERVICES
WITHDRAW          ROUTING=ACCOUNT_ID
DEPOSIT           ROUTING=ACCOUNT_ID
INQUIRY           ROUTING=ACCOUNT_ID
OPEN_ACCT         ROUTING=BRANCH_ID
CLOSE_ACCT        ROUTING=BRANCH_ID
#
ROUTING
ACCOUNT_ID        FIELD=ACCOUNT_ID BUFTYPE="FML"
                   RANGES="MIN - 9999:*,
                      10000-49999:BANKB1,
                      50000-79999:BANKB2,
                      80000-109999:BANKB3,
                      *:*"
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

This section explains how and why you need to modify the domain gateway configuration to support routing. For more information about the domain gateway configuration file, see Chapter 8, ``Working with Multiple Domains.''

What Is the Domains Gateway Configuration File?

All Domains gateway configuration information is stored in a binary file, the BDMCONFIG file. The DMCONFIG file (ASCII) is created and edited with any text editor. The compiled BDMCONFIG file can be updated while the system is running by using the dmadmin(1) command.

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 Domains gateway groups.

Note: For more information about the DMCONFIG file, refer to the dmconfig(5) reference page in the BEA TUXEDO Reference Manual.

Description of Parameters in the ROUTING Section of the DMCONFIG File

The DM_ROUTING section provides information for data-dependent routing of service requests using FML, VIEW, X_C_TYPE, and X_COMMON typed buffers. Lines within the DM_ROUTING section have the form CRITERION_NAME, where CRITERION_NAME is the (identifier) name of the routing entry specified in the SERVICES section. The CRITERION_NAME entry may contain no more than 15 characters. The following table describes the parameters in the DM_ROUTING section.

Parameter Meaning
FIELD = identifier Specifies the name of the routing field. It must contain 30 characters or fewer. This field is assumed to be a field name identified in an FML field table (for FML buffers) or an FML VIEW table (for VIEW, X_C_TYPE, or X_COMMON buffers). The FLDTBLDIR and FIELDTBLS environment variables are used to locate FML field tables; the VIEWDIR and VIEWFILES environment variables are used to locate FML VIEW tables. If a field in an FML32 buffer is used for routing, it must have a field number less than or equal to 8191.
RANGES ="range1:rdom1[,range2:rdom2 ...]" Specifies the ranges and associated remote domain names (RDOM) for the routing field. The string must be enclosed in double quotes, with the format of a comma-separated ordered list of range/RDOM pairs. A range is either a single value (signed numeric value or character string 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 backslashes ("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 the other ranges previously seen in the entry. Only one wildcard range is allowed per entry and it should be last (ranges following it are ignored).
BUFTYPE = "type1[:subtype1[,subtype2 . . . ]][;type2[:subtype3[, . . . ]]] . . ." A list of types and subtypes of data buffers for which this routing entry is valid. The types are restricted to 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. This parameter is required. 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 routing field can be of any data type supported in FML or VIEW. A numeric routing field must have numeric range values, and a string routing field must have string range values.

String range values for string, carray, and character field types must be placed inside a pair of single quotes and cannot be preceded by a sign. Short and long integer values are a string of digits, optionally preceded by a plus or minus sign. Floating point numbers are of the form accepted by the C compiler or atof(): an optional sign, then 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 RDOM value specifies the remote domain to which the request should be routed. An RDOM value of * indicates that the request can go to any remote domain known by the gateway group. Within a range/RDOM pair, the range is separated from the RDOM by a : (colon).

Example of a Five-Site Domain Configuration Using Routing

The following configuration file defines a 5-site domain configuration. Listing 5-1 shows four bank branch domains communicating with a Central Bank Branch. Three of the bank branches run within other BEA TUXEDO system domains. The fourth branch runs under the control of another TP domain, and OSI-TP is used in the communication with that domain. The example shows the BEA TUXEDO system Domains gateway configuration file from the Central Bank point of view. In the DM_TDOMAIN section, this example shows a mirrored gateway for b01.

Listing 5-1 A 5-Site Domains Configuration 

# TUXEDO DOMAIN CONFIGURATION FILE FOR THE CENTRAL BANK
#
#
DM_LOCAL_DOMAINS
# <local domain name> <Gateway Group name> <domain type> <domain id> <log device>
#                     [<audit log>] [<blocktime>]
#                     [<log name>] [<log offset>] [<log size>]
#                     [<maxrdom>] [<maxrdtran>] [<maxtran>]
#                     [<maxdatalen>] [<security>]
#                     [<tuxconfig>] [<tuxoffset>]

#
#
DEFAULT: SECURITY = NONE
c01     GWGRP = bankg1
        TYPE = TDOMAIN
        DOMAINID = "BA.CENTRAL01"
        DMTLOGDEV = "/usr/apps/bank/DMTLOG"
        DMTLOGNAME = "DMTLG_C01"
c02     GWGRP = bankg2
        TYPE = OSITP
        DOMAINID = "BA.CENTRAL01"
        DMTLOGDEV = "/usr/apps/bank/DMTLOG"
        DMTLOGNAME = "DMTLG_C02"
        NWDEVICE = "OSITP"
        URCH = "ABCD"
#
DM_REMOTE_DOMAINS
#<remote domain name>  <domain type> <domain id>
#
b01     TYPE = TDOMAIN
        DOMAINID = "BA.BANK01"
b02     TYPE = TDOMAIN
        DOMAINID = "BA.BANK02"
b03     TYPE = TDOMAIN
        DOMAINID = "BA.BANK03"
b04     TYPE = OSITP
        DOMAINID = "BA.BANK04"
        URCH = "ABCD"
#
DM_TDOMAIN
#
#     <local or remote domainname> <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_LOCAL_SERVICES
#<service_name>  [<Local Domain name>] [<access control>] [<exported svcname>]
#                [<inbuftype>] [<outbuftype>]
#
open_act        ACL = branch
close_act       ACL = branch
credit
debit
balance
loan            LDOM = c02      ACL = loans
DM_REMOTE_SERVICES
#<service_name>   [<Remote domain name>] [<local domain name>]
#                 [<remote svcname>] [<routing>] [<conv>]
#                 [<trantime>] [<inbuftype>] [<outbuftype>]
#
tlr_add   LDOM = c01  ROUTING = ACCOUNT
tlr_bal   LDOM = c01  ROUTING = ACCOUNT
tlr_add   RDOM = b04  LDOM = c02 RNAME ="TPSU002"
tlr_bal   RDOM = b04  LDOM = 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


[Top] [Previous Page] [Next Page] [Bottom]