DMCONFIG(5)


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| File Formats and Data Descriptions Reference \| Local Topics \| Previous Topic \| Next Topic \| Contents

DMCONFIG(5)

Name

DMCONFIG—Text version of a Domains configuration file

Description

A Domains configuration is a set of two or more domains (or applications) that can communicate and share services with the help of the BEA Tuxedo Domains feature. How multiple domains are connected and which services they make accessible to each other are defined in a Domains configuration file on each domain. The text version of a Domains configuration file is known as the DMCONFIG file (after the environment variable used to hold the name of the actual file used).

A DMCONFIG file defines the following:

The remote domains with which the local domain can communicate
The local resources (such as services and queues) accessible to remote domains
The remote resources accessible to the local domain
Which local and remote resources are accessible through which gateways

The DMCONFIG file is parsed and loaded into a binary version, called BDMCONFIG, by the dmloadcf(1) utility. The dmadmin(1) command uses BDMCONFIG (or a copy of it) for monitoring the run-time application.

One BDMCONFIG file is required on each domain in a multi-domain configuration in which the Domains feature is being used.

The DMCONFIG and BDMCONFIG files are analogous to the UBBCONFIG and TUXCONFIG files used to define a BEA Tuxedo application.

For additional information pertaining to the entire DMCONFIG file, see DMCONFIG(5) Additional Information.

Definitions

A BEA Tuxedo system domain application is defined as the environment described in a single TUXCONFIG file. A BEA Tuxedo system application can communicate with another BEA Tuxedo system application or with another TP application via a domain gateway group. In "BEA Tuxedo system domain" terms, an application is the same as a TP Domain.

A gateway group is a collection of domain gateway processes that provide communication services with a specific type of TP Domain.

A domain gateway is a BEA Tuxedo system domain process that relays requests to another TP Domain and receives replies.

A local domain is a part of the application (set or subset of services) that is made available to other domains. A local domain is always represented by a domain gateway group, and both terms are used as synonyms.

A remote domain is a remote application that is accessed through a gateway group. The remote application may be another BEA Tuxedo system domain application or an application running under another TP system.

A remote service is a service provided by a remote domain that is made available to the application through a gateway group.

A local service is a service of a local domain that is made available to remote domains through a gateway group.

Configuration File Format

The format of a domain configuration file is as follows.

The file is made up of eight possible specification sections. Allowable section names are: DM_LOCAL_DOMAINS, DM_REMOTE_DOMAINS, DM_LOCAL_SERVICES, DM_REMOTE_SERVICES, DM_RESOURCES, DM_ROUTING, DM_ACCESS_CONTROL, and DM_domtype, where domtype is one of the following: OSITP, OSITPX, SNAX, TDOMAIN, or TOPEND. The DM_LOCAL_DOMAINS section must precede the DM_REMOTE_DOMAINS section.

Note: This reference page describes how to configure a domain of only one type: TDOMAIN. See BEA eLink documentation for information about how to configure an OSITP, OSITPX, or an SNAX domain. For information about how to configure a TOP END Domain Gateway, see DMCONFIG for GWTOPEND(5) and Using the BEA Tuxedo TOP END Domain Gateway with ATMI Applications.

Parameters are generally specified by: KEYWORD = value; white space (space or tab character) is allowed on either side of the equal sign (=). This format sets KEYWORD to value. Valid keywords are described below within each section.

Lines beginning with the reserved word, DEFAULT:, contain parameter specifications that apply to all lines that follow them in the section in which they appear. Default specifications can be used in all sections. They can appear more than once in the same section. The format for these lines is:

DEFAULT: [KEYWORD1 = value1 [KEYWORD2 = value2 [...]]]

The values set on this line remain in effect until reset by another DEFAULT: line, or until the end of the section is reached. These values can also be overridden on non-DEFAULT: lines by placing the optional parameter setting on the line. If on a non-DEFAULT: line, the parameter setting is valid for that line only; lines that follow revert to the default setting. If DEFAULT: appears on a line by itself, all previously set defaults are cleared and their values revert to the system defaults.

If a value is numeric, standard C notation is used to denote the base (that is, 0x prefix for base 16 (hexadecimal), 0 prefix for base 8 (octal), and no prefix for base 10 (decimal)). The range of values acceptable for a numeric parameter are given under the description of that parameter.

If a value is an identifier (a string value already known to the BEA Tuxedo Domains feature such as TDOMAIN for the TYPE parameter), standard C rules are typically used. A standard C identifier starts with an alphabetic character or underscore and contains only alphanumeric characters or underscores. The maximum allowable length of an identifier is 30 (not including the terminating NULL).

There is no need to enclose an identifier in double quotes. A value that is neither an integer number nor an identifier must be enclosed in double quotes.

Input fields are separated by at least one space (or tab) character.

"#" introduces a comment. A newline ends a comment.

Blank lines and comments are ignored.

Comments can be freely attached to the end of any line.

Lines are continued by placing at least one tab after the newline. Comments cannot be continued.

Domains Terminology Improvements

In this release, some of the domains terminology is changing. The Domains MIB uses improved class and attribute terminology to describe the interaction between local and remote domains. While this improved terminology is more accurate than previous domains terminology, the scope of changes to domains-related documentation and error messages is limited in this release. The improved terminology has been applied to the DM_MIB classes, reference page, and error messages, the DMCONFIG file syntax, and various DMCONFIG error messages.

For backwards compatibility, aliases are provided between the DMCONFIG terminology used prior to this release and the improved Domains MIB terminology. In this release, DMCONFIG accepts both versions of the terminology. For details, see Domains Terminology Improvements in the DM_MIB(5) reference page.

DM_LOCAL_DOMAINS Section

This section identifies local domains and their associated gateway groups. The section must have an entry for each gateway group (local domain). Each entry specifies the parameters required for the domain gateway processes running in that group.

Entries have the form:

LDOM required_parameters [optional_parameters]

where LDOM is an identifier value used to name the local domain. LDOM must be unique within a particular configuration. As you will see in the description of the DM_LOCAL_SERVICES section, LDOM is the identifier that associates the local services with a particular gateway group.

The following are required parameters:

GWGRP = identifier

Specifies the name of the gateway server group (the name provided in the TUXCONFIG file) representing this local domain. There is a one-to-one relationship between a DOMAINID (see below) and the name of the gateway server group.

TYPE = identifier

Used for grouping local domains into classes. TYPE can be set to one of the following values: TDOMAIN, SNAX, OSITP, OSITPX, or TOPEND. The TDOMAIN value indicates that this local domain can only communicate with another BEA Tuxedo system domain. The SNAX value indicates that this local domain communicates with another TP domain via the SNA protocol. The OSITP or OSITPX value indicates that this local domain communicates with another TP domain via the OSI TP protocol. The TOPEND value indicates that this local domain can communicate only with a BEA TOP END system. Domain types must be defined in the $TUXDIR/udataobj/DMTYPE file.

Note: OSITPX is the BEA OSI TP 4.0 or later gateway that must be used when connecting to BEA Tuxedo 8.0 or later.

DOMAINID = string

Used to identify the local domain. DOMAINID must be unique across both local and remote domains. The value of string can be a sequence of characters (for example, "BA.CENTRAL01"), or a sequence of hexadecimal digits preceded by "0x" (for example, "0x0002FF98C0000B9D6"). DOMAINID must be 30 octets or fewer in length. If the value is a string, it must be 30 characters or fewer (counting the trailing NULL).

Optional parameters describe resources and limits used in the operation of domain gateways:

AUDITLOG = string

Specifies the name of the audit log file for this local domain. The audit log feature is activated from the dmadmin(1) command and records all the operations within this local domain. If the audit log feature is active and this parameter is not specified, the file DMmmddyy.LOG (where mm=month, dd=day, and yy=year) is created in the directory specified by the $APPDIR environment variable or the APPDIR keyword of the MACHINES section of the TUXCONFIG file.

BLOCKTIME = numeric

Specifies the maximum wait time allowed for a blocking call. The value sets a multiplier of the SCANUNIT parameters specified in the TUXCONFIG file. The value SCANUNIT * BLOCKTIME must be greater than or equal to SCANUNIT and less than 32,768 seconds. If this parameter is not specified, the default is set to the value of the BLOCKTIME parameter specified in the TUXCONFIG file. A timeout always implies a failure of the affected request. Notice that the timeout specified for transactions in the TUXCONFIG will always be used when the request is issued within a transaction.

CONNECTION_PRINCIPAL_NAME = string[0..511]

Specifies the connection principal name identifier, which is the principal name for verifying the identity of this local domain when establishing a connection to a remote domain. This parameter only applies to domains of type TDOMAIN that are running BEA Tuxedo 7.1 or later software.

The CONNECTION_PRINCIPAL_NAME parameter may contain a maximum of 511 characters (excluding the terminating NULL character). If this parameter is not specified, the connection principal name defaults to the DOMAINID string for this local domain.

For default authentication plug-ins, if a value is assigned to the CONNECTION_PRINCIPAL_NAME parameter for this local domain, it must be the same as the value assigned to the DOMAINID parameter for this local domain. If these values do not match, the local domain gateway process will not boot, and the system will generate the following userlog(3c) message: ERROR: Unable to acquire credentials.

CONNECTION_POLICY = string

Specifies the conditions under which a local domain gateway tries to establish a connection to a remote domain. Supported values are: ON_DEMAND, ON_STARTUP, or INCOMING_ONLY.

A connection policy of ON_DEMAND means that a connection will be attempted only when requested by either a client request to a remote service or an administrative "connect" command. The default setting for CONNECTION_POLICY is ON_DEMAND. The ON_DEMAND policy provides the equivalent behavior to previous releases, in which the CONNECTION_POLICY was not explicitly available. Connection retry processing is not allowed when the connection policy is ON_DEMAND.

A connection policy of ON_STARTUP means that a domain gateway will attempt to establish a connection with its remote domains at gateway server initialization time. If the value chosen for the CONNECTION_POLICY is set to ON_STARTUP, then remote services (that is, services advertised by the local domain gateway) will be advertised only if a connection is successfully established to that remote domain. Thus, if there is no active connection to the remote domain, then the remote services will be suspended. By default, this connection policy will retry failed connections every 60 seconds, but you can specify a different value for this interval (see MAXRETRY and RETRY_INTERVAL).

A connection policy of INCOMING_ONLY means that a domain gateway will not attempt an initial connection to remote domains upon starting and remote services will initially be suspended. The domain gateway will be available for incoming connections from remote domains, and remote services will be advertised when the local domain gateway receives an incoming connection. Connection retry processing is not allowed when the connection policy is INCOMING_ONLY. (The CONNECTION_POLICY parameter does not apply to domains of type OSI or SNA.)

DMTLOGDEV = string

Specifies the BEA Tuxedo filesystem that contains the Domain transaction log (DMTLOG) for this machine. The DMTLOG is stored as a BEA Tuxedo system VTOC table on the device. If this parameter is not specified, the domain gateway group is not allowed to process requests in transaction mode. Local domains running on the same machine can share the same DMTLOGDEV filesystem, but each local domain must have its own log (a table in the DMTLOGDEV) named as specified by the DMTLOGNAME keyword (see below).

DMTLOGNAME = identifier

Specifies the name of the domain transaction log for this domain. This name must be unique when the same DMTLOGDEV is used for several local domains. If not specified, the default is the string "DMTLOG". The name must be 30 characters or less.

DMTLOGSIZE = numeric

Specifies the numeric size, in pages, of the Domain transaction log for this machine. It must be greater than 0 and less than the amount of available space on the BEA Tuxedo filesystem. If not specified, the default is 100 pages.

MAXRDOM = numeric

Specifies the maximum number of connections allowed per gateway. It applies only to OSITP and SNA domains.

MAXRDTRAN = numeric

Specifies the maximum number of domains that can be involved in a transaction. It must be greater than 0 and less than 32,768. If not specified, the default is 16.

MAXRETRY = {numeric | MAXLONG}

Specifies the number of times that a domain gateway will try to establish connections to remote domains. The minimum value is 0 and the maximum is MAXLONG. MAXLONG indicates that retry processing will be repeated indefinitely, or until a connection is established. For a connection policy of ON_STARTUP, the default setting for MAXRETRY is MAXLONG. Setting MAXRETRY=0 turns off the auto retry mechanism. For other connection policies, auto retries are disabled.

The MAXRETRY parameter is valid only when the connection policy is ON_STARTUP. The MAXRETRY parameter does not apply to domains of type OSI or SNA.

MAXTRAN = numeric

Specifies the maximum number of simultaneous global transactions allowed on this local domain. It must be greater than or equal to 0 and less than or equal to the MAXGTT parameter specified in the TUXCONFIG file. If not specified, the default is the value of MAXGTT.

MTYPE = value

Used for grouping domains so that encoding/decoding of messages between domains can be bypassed. If MTYPE is not specified, the default is to turn encoding/decoding on. If the value set for the MTYPE field is the same in both the DM_LOCAL_DOMAINS and the DM_REMOTE_DOMAINS section of a domain configuration file, data encoding/decoding is bypassed. The value set for MTYPE can be any string value up to 15 characters in length. It is used only for comparison.

RETRY_INTERVAL = numeric

Specifies the number of seconds between automatic attempts to establish a connection to remote domains. The minimum value is 0 and the maximum value is 2147483647. The default setting for RETRY_INTERVAL is 60. If MAXRETRY is set to 0, then setting RETRY_INTERVAL is not allowed.

The RETRY_INTERVAL parameter is valid only when the connection policy is ON_STARTUP. For other connection policies, automatic retries are disabled. The RETRY_INTERVAL parameter does not apply to domains of type OSI or SNA.

SECURITY = value

Specifies the type of application security to be enforced. The SECURITY parameter currently has three valid values: NONE, APP_PW, or DM_PW. The value NONE indicates that no security is used. This is the default. The value APP_PW indicates that the application password security is to be enforced when a connection is established from a remote domain. The application password should be defined in the TUXCONFIG file. The value DM_PW indicates that domain password security is to be enforced when a connection is established from a remote domain. Domain passwords must be defined through the dmadmin(1) command.

The SECURITY option does not apply to the OSITP domain type. For the OSITPX domain type in the OSI TP 4.0 or later gateway used with BEA Tuxedo 8.0 or later, the values NONE or DM_PW can be used.

DM_REMOTE_DOMAINS Section

This section identifies the known set of remote domains and their characteristics.

Entries have the form:

RDOM required_parameters [optional_parameters]

where RDOM is an identifier value used to identify each remote domain known to this configuration. RDOM must be unique within the configuration.

The following are required parameters:

TYPE = identifier

Used for grouping remote domains into classes. TYPE can be set to one of the following values: TDOMAIN, SNAX, OSITP, OSITPX, or TOPEND. The TDOMAIN value indicates that this remote domain can communicate only with another BEA Tuxedo system domain. The SNAX value indicates that this domain communicates with another TP domain via SNA protocol. The OSITP or OSITPX value indicates that this remote domain communicates with another TP domain via the OSI TP protocol. The TOPEND value indicates that this remote domain is a BEA TOP END system and can communicate only with a local domain of type TOPEND.

Note: OSITPX is the BEA OSI TP 4.0 or later gateway that must be used when connecting to BEA Tuxedo 8.0 or later.

DOMAINID = string

Used to identify a remote domain. DOMAINID must be 30 octets or fewer in length. If the value is a string, it must be 30 characters or fewer (counting the trailing NULL). DOMAINID must be unique across remote domains. The value of string can be a sequence of characters or a sequence of hexadecimal digits preceded by "0x".

Optional parameters describe resources and limits used in the operation of domain gateways:

ACL_POLICY = {LOCAL | GLOBAL}

Specifies the access control list (ACL) policy for this remote domain. This parameter only applies to domains of type TDOMAIN that are running BEA Tuxedo 7.1 or later software.

LOCAL means that the local domain modifies the identity of service requests received from this remote domain to the principal name specified in the LOCAL_PRINCIPAL_NAME parameter for this remote domain. GLOBAL means that the local domain uses any credential it might receive from the remote domain on inbound service requests. If no credential is received from the remote domain, then the service request is forwarded to the service without credentials (which usually fails). If not specified, the default is LOCAL.

Note that this parameter controls whether or not the local domain accepts a credential from a remote domain. The CREDENTIAL_POLICY parameter is related to this parameter and controls whether or not a local domain sends credentials to the remote domain.

CONNECTION_PRINCIPAL_NAME = string[0..511]

Specifies the connection principal name identifier, which is the principal name for verifying the identity of this remote domain when establishing a connection to the local domain. This parameter only applies to domains of type TDOMAIN that are running BEA Tuxedo 7.1 or later software.

For default authentication plug-ins, if a value is assigned to the CONNECTION_PRINCIPAL_NAME parameter for this remote domain, it must be the same as the value assigned to the DOMAINID parameter for this remote domain. If these values do not match, any attempt to set up a connection between the local domain gateway and the remote domain gateway will fail, and the system will generate the following userlog(3c) message: ERROR: Unable to initialize administration key for domain domain_name.

CREDENTIAL_POLICY={LOCAL|GLOBAL}

Specifies the credential policy for this remote domain. This parameter only applies to domains of type TDOMAIN that are running BEA Tuxedo 8.0 or later software. If the policy is LOCAL then the domain does not attach the credentials of the user that originated a request with the invocation to the remote domain. If the policy is GLOBAL then the domain attaches the credentials of the user that originated the request with the invocation to the remote domain. If not specified, the default is LOCAL.

Note that this parameter controls whether or not user credentials are sent to a remote domain. The ACL_POLICY parameter is related to this one and controls whether or not incoming credentials are accepted by a domain.

LOCAL_PRINCIPAL_NAME = string[0..511]

The local principal name identifier, which is the identity assigned by the local domain to service requests received from this remote domain. This parameter only applies to domains of type TDOMAIN that are running BEA Tuxedo 7.1 or later software.

The LOCAL_PRINCIPAL_NAME parameter is valid only if the ACL_POLICY parameter for this remote domain is set (or defaulted) to LOCAL. The LOCAL_PRINCIPAL_NAME parameter may contain a maximum of 511 characters (excluding the terminating NULL character). If this parameter is not specified, the local principal name defaults to the DOMAINID string for this remote domain.

MTYPE = value

Entries associated with a remote domain can be specified more than once. The first one specified is considered to be the primary address, which means it is the first one tried when a connection is being attempted to a remote domain. If a network connection cannot be established using the NWADDR of the primary entry, the NWADDR associated with the secondary entry is used.

PRIORITY_TYPE = {LOCAL_RELATIVE | LOCAL_ABSOLUTE | GLOBAL}

INPRIORITY = number

Specifies the message priority handling for this remote domain. These parameters only apply to domains that are running BEA Tuxedo 8.0 or later software. The LOCAL_RELATIVE and LOCAL_ABSOLUTE parameters can apply to all domain types. However, the GLOBAL parameter only applies to domains of type TDOMAIN.

The LOCAL_RELATIVE parameter means that the priority associated with a request from the remote domain (for example, via the tpsprio call) is not propagated to the local domain. If the INPRIORITY value is set, the priority of these incoming requests from the remote domain will be set relative to the INPRIORITY value. The INPRIORITY value must be between -99 and +99, inclusive, with 0 being the default value if the INPRIORITY value is not set. The setting of INPRIORITY value increments or decrements a service's default priority as follows: up to a maximum of 100 or down to a minimum of 1, depending on its sign, where 100 is the highest priority. For requests to the remote domain, the priority associated with a request will be sent to the remote domain (along with the request).

The LOCAL_ABSOLUTE parameter means that the priority associated with a request from the remote domain is not propagated to the local domain. However, the priority of incoming requests will be set to the absolute value of the INPRIORITY value. If the INPRIORITY value is not set, it defaults to 50. The INPRIORITY value must be within a range of 1-100, inclusive, with 100 being the highest priority. For requests to the remote domain, the priority associated with a request will be sent to the remote domain (along with the request).

The GLOBAL parameter means that the priority associated with a request from the remote domain is propagated to the local domain. The default value for the specific service will be ignored locally. If the INPRIORITY value is set, the priority of the incoming request from the remote domain will be added to the INPRIORITY value. The sum of the priorities will then be set absolutely for the incoming request. The INPRIORITY value must be between -99 and +99, inclusive, with 0 being the default value if the INPRIORITY value is not set. The setting of the INPRIORITY value increments or decrements a service's default priority as follows: up to a maximum of 100 or down to a minimum of 1, depending on its sign, where 100 is the highest priority. Setting INPRIORITY to 0 means the priority is coming directly from the remote domain. For requests to the remote domain, the priority associated with a request will be sent to the remote domain (along with the request).

Unless specified otherwise, the default setting is LOCAL_RELATIVE with INPRIORITY set to 0.

DM_TDOMAIN Section

This section defines the addressing information required by domains of type TDOMAIN. This section should have one entry per local domain if requests from remote domains to local services are accepted on that local domain (gateway group), and one entry per remote domain accessible by the defined local domains.

Entries have the form:

DOM required_parameters [optional_parameters]

where DOM is an identifier value used to identify either a local domain (LDOM) or a remote domain (RDOM) in the DM_LOCAL_DOMAINS section or in the DM_REMOTE_DOMAINS section. The DOM identifier must match a previously defined LDOM in the DM_LOCAL_DOMAINS section or RDOM in the DM_REMOTE_DOMAINS section.

The following parameter is required:

NWADDR = string

This parameter specifies the network address associated with a local domain or a remote domain. If the association is with a local domain, the NWADDR is used to accept connections from other BEA Tuxedo system domains. If the association is with a remote domain, the NWADDR is used to initiate a connection. Specifies the network address to be used by the process as its listening address. The listening address for a domain gateway is the means by which it is contacted by other gateway processes participating in the application.

If string has the form "0xhex-digits" or "\\xhex-digits" it must contain an even number of valid hex digits. These forms are translated internally into a character array containing TCP/IP addresses. The value of string may also be represented in either of the following forms:

"//host.name:port_number"

"//#.#.#.#:port_number"

In the first of these formats, hostname is resolved to a TCP/IP host address at the time the address is bound using the locally configured name resolution facilities accessed via gethostbyname(3c). The string #.#.#.# is the dotted decimal format where each # represents a decimal number in the range 0 to 255.

Port_number is a decimal number in the range 0 to 65535.

Note: Some port numbers may be reserved for the underlying transport protocols (such as TCP/IP) used by your system. Check the documentation for your transport protocols to find out which numbers, if any, are reserved on your system.

This parameter specifies the network address used by a local or a remote domain to accept connections from other BEA Tuxedo system domain domains. If string has the form "0xhex-digits", it must contain an even number of valid hexadecimal digits.

The following parameters are optional:

NWDEVICE = string

Specifies the device filename to be used when binding to the listening address of a local or a remote domain. The NWDEVICE parameter is not required. In prior releases, if the networking functionality is TLI-based, the device name must be an absolute pathname.

CMPLIMIT = numeric

This parameter specifies the compression threshold to be used when sending data to the remote domain. Application buffers larger than this size will be compressed. This parameter defaults to 2,147,483,647.

MINENCRYPTBITS = {0 | 40 | 56 | 128}

Specifies the minimum level of encryption required when a link for this domain is being established. 0 means no encryption, while 40, 56, and 128 specify the encryption key length (in bits). If this minimum level of encryption cannot be met, link establishment fails. The default is 0.

Note: The link-level encryption value of 40 bits is provided for backward compatibility.

MAXENCRYPTBITS = {0 | 40 | 56 | 128}

Specifies the maximum level of encryption allowed when a link for this domain is being established. 0 means no encryption, while 40, 56, and 128 specify the encryption length (in bits). The default is 128.

Note: The link-level encryption value of 40 bits is provided for backward compatibility.

Entries associated with a remote domain can be specified more than once. The first one specified is considered to be the primary address, which means it is the first one tried when a connection is being attempted to a remote domain. If a network connection cannot be established using the primary entry's NWADDR, the NWADDR associated with the secondary entry is used.

If this TDOMAIN is a local domain (that is, if DOM matches a previously specified LDOM), then NWADDRs are network addresses to be used to listen for incoming connections. A secondary entry cannot be used for local domain entries.

If this TDOMAIN entry points to a secondary remote domain (that is, if DOM matches a previously specified RDOM), then the entry points to a gateway that is only used when a network connection cannot be established using the NWADDR of the primary entry. The secondary remote gateway must reside in a different BEA Tuxedo Domain from the primary. However, the secondary gateway must have the same DOMAINID defined in its DM_LOCAL_DOMAINS section as the primary remote gateway; this arrangement is often referred to as a mirrored gateway. This feature is not recommended for use with transactions or conversations. In addition, the mirrored gateway is not recommended for use when the primary gateway is available.

DM_ACCESS_CONTROL Section

This section specifies the access control lists used by local domain. Lines in this section are of the form:

ACL_NAME required_parameters

where ACL_NAME is an identifier used to specify an access control list; it may contain no more than 15 characters.

The only required parameter is:

ACLIST = identifier [,identifier]

where an ACLIST is composed of one or more remote domain names (RDOM) separated by commas. The wildcard character (*) can be used to specify that all the remote domains defined in the DM_REMOTE_DOMAINS section can access a local domain.

DM_LOCAL_SERVICES Section

This section provides information on the services exported by each local domain. This section is optional; if it is not specified, then all local domains defined in the DM_LOCAL_DOMAINS section accept requests to all of the services advertised by the BEA Tuxedo system domain application. If this section is specified then it should be used to restrict the set of local services that can be requested from a remote domain.

Lines within this section have the form:

service [optional_parameters]

where service is the identifier value used to specify the local name of the exported service, and it must be 15 characters or fewer in length. This name corresponds to a name advertised by one or more servers running with the local BEA Tuxedo system domain application. Notice that exported services inherit the properties specified for the service in an entry in the SERVICES section of the TUXCONFIG file, or their defaults. Some of the properties that may be inherited are: LOAD, PRIO, AUTOTRAN, ROUTING, BUFTYPE, and TRANTIME.

Optional parameters are:

ACL = identifier

Specifies the name of the access control list (ACL) to be used by the local domain to restrict requests made to this service by remote domains. The name of the ACL is defined in the DM_ACCESS_CONTROL section. If this parameter is not specified then access control will not be performed for requests to this service.

LDOM = identifier

Specifies the name identifying the local domain exporting this service. If this keyword is not specified then all the local domains defined in the DM_LOCAL_DOMAINS section will accept requests to this local service.

INBUFTYPE = type[:subtype]

Restricts the buffer type naming space of data types accepted by this service to a single buffer type. This parameter should be defined when the service is going to be used from an OSITP type gateway that uses the UDT ASE Application Context. It does not apply to TDOMAIN.

OUTBUFTYPE = type[:subtype]

Restricts the buffer type naming space of data types returned by this service to a single buffer type. This parameter should be defined when the service is going to be used from an OSITP type gateway that uses the UDT ASE Application Context. The FML buffer type cannot be used for the OSITP type gateway. It does not apply to TDOMAIN.

RNAME = string

Specifies the name exported to remote domains. This name will be used by the remote domains for request to this service. If this parameter is not specified, the local service name is supposed to be the name used by any remote domain.

DM_REMOTE_SERVICES Section

This section provides information on services "imported" and available on remote domains. Lines within this DM_REMOTE_SERVICES section have the form:

service [optional_parameters]

where service is the identifier name used by the local BEA Tuxedo system domain application for a particular remote service. Remote services are associated with a particular remote domain.

Optional parameters are:

CONV = {Y | N}

Specifies whether (Y) or not (N) the remote service is a conversational service. The default is N.

LDOM = identifier

Specifies the name of a local domain in charge of routing requests to this remote service. The gateway group associated with the local domain advertises service in the BEA Tuxedo system domain bulletin board. If this parameter is not specified then all the local domains will be able to accept requests to this remote service. The service request will be then redirected to a remote domain of the same type (see RDOM keyword below).

INBUFTYPE = type[:subtype]

OUTBUFTYPE = type[:subtype]

RDOM = identifier1[,identifier2][,identifier3]

Specifies the name of the remote domain responsible for the execution of this service. If this parameter is not specified and a routing criteria is not specified, the local domain assumes that any remote domain of the same type accepts requests for this service.

You must specify ON_STARTUP as the value of the CONNECTION_POLICY parameter if you want to configure alternate remote domains with the identifier2 and identifier3 arguments. If identifier2 is configured, it is used for failover. (When the remote domain specified by identifier1 is unavailable, the remote domain specified by identifier2 is used.) Similarly, if identifier3 is configured, it is used for failover. (When the remote domain specified by identifier1 and identifier2 are unavailable, the remote domain specified by identifier3 is used.)

RNAME = string

Specifies the actual service name expected by the remote domain. If this parameter is not specified, the remote service name is the same as the name specified in service.

ROUTING = identifier

When more than one remote domain offers the same service, a local domain can perform data-dependent routing if this optional parameter is specified. The identifier specifies the name of the routing criteria used for this data-dependent routing. If not specified, data-dependent routing is not done for this service. identifier must be 15 characters or less in length. If multiple entries exist for the same service name but with different RDOM parameters, the ROUTING parameter should be the same for all of these entries.

TRANTIME = integer

Specifies the default timeout value in seconds for a transaction automatically started for the associated service. The value must be greater than or equal to 0 and less than 2147483648. The default is 30 seconds. A value of 0 implies the maximum timeout value for the machine.

DM_RESOURCES

This optional section is used for defining global Domains configuration information, specifically a user-supplied configuration version string.

The only parameter in this section is:

VERSION = string

where string is a field in which users can enter a version number for the current Domains configuration file. This field is not checked by the software.

DM_ROUTING Section

This section provides information for data-dependent routing of service requests using FML, FML32, XML, VIEW, VIEW32, X_C_TYPE, and X_COMMON typed buffers. Lines within the DM_ROUTING section have the form:

CRITERION_NAME required_parameters

where CRITERION_NAME is the identifier name of the routing entry that was specified in the services entry. CRITERION_NAME must be 15 characters or less in length.

Required parameters are:

FIELD = identifier

Specifies the name of the routing field. It must be 30 characters or less. It is assumed that the value of identifier is one of the following: a field name that is identified in an FML field table (for FML and FML32 buffers); an XML element or element attribute (for XML buffers); or an FML view table (for VIEW, X_C_TYPE, or X_COMMON buffers). Two environment variables — FLDTBLDIR and FIELDTBLS, or FLDTBLDIR32 and FIELDTBLS32 are used to locate FML field tables. Similarly, two environment variables VIEWDIR and VIEWFILES, or VIEWDIR32 and VIEWFILES32 are used to locate FML view tables. If a field in an FML or FML32 buffer is used for routing, the value of that field must be a number less than or equal to 8191.

When XML documents are being routed on the basis of element content or element attribute, the FIELD parameter must be defined with the following syntax:

FIELD = "root_element[/child_element][/child_element][/. . .][/@attribute_name]"

The value of FIELD specifies the name of a routing element or an element attribute. It is assumed that the value of root_element is an element type (or name) or an element attribute name for an XML document or datagram. This information is used to identify the element content or element attribute value for data-dependent routing while sending a document or datagram. The element name and attribute name combined may contain no more than 30 characters. Because indexing is not supported, the BEA Tuxedo system recognizes only the first occurrence of a given element type when processing an XML buffer for data-dependent routing.

XML strictly defines the set of characters that may be used in an attribute name. An attribute name must be a string consisting of a single letter, underscore, or colon, followed by one or more name characters. Both element names and attribute names are case-sensitive.

You can find more information about XML on the World Wide Web Consortium Web site at http://www.w3c.org/XML.

FIELDTYPE = type

Indicates the type of routing field specified in the FIELD parameter. This parameter is used only for routing XML buffers. The value type can be set to one of the following: CHAR, SHORT, LONG, FLOAT, DOUBLE, or STRING. The default type of the routing field is STRING.

RANGES = "string"

Specifies the ranges and associated remote domain names (RDOM) for the routing field. string must be enclosed in double quotes. The format of string is a comma-separated ordered list of range/RDOM pairs (see EXAMPLES below).

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). Note that "lower" must be less than or equal to "upper".

To embed a single quote in a character string value (as in O'Brien, for example), it must be preceded by two backslashes (O\\'Brien).

The value MIN can be used 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.

The value MAX can be used 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 meta-character "*" (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 will be ignored).

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. A 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 ":".

An XML element content and attribute value must be encoded in UTF-8 and can be used for routing if it can be converted to the data type specified by the FIELDTYPE parameter.

When used for routing, the element content cannot contain character references, entity references, or CDATA sections.

An XML attribute value (encoded in UTF-8) can be used for routing if the element to which the attribute belongs is defined.

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 either FML, FML32, XML, VIEW, VIEW32, X_C_TYPE, or X_COMMON. No subtype can be specified for types FML, FML32, or XML; subtypes are required for types VIEW, VIEW32, X_C_TYPE, and X_COMMON ("*" 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 or FML32 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.

DMCONFIG(5) Additional Information

Files

The BDMCONFIG environment variable is used to find the BDMCONFIG configuration file.

Example1

The following configuration file defines a five-site Domains configuration. The example shows four Bank Branch domains communicating with a Central Bank Branch. Three of the Bank Branches run within other BEA Tuxedo domains. The fourth Branch runs under the control of another TP Domain. OSI TP is used for communication between that domain and the Central Bank. The example shows the Domains configuration file from the Central Bank point of view.

# BEA 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.CENTRAL02"
     DMTLOGDEV = "/usr/apps/bank/DMTLOG"
     DMTLOGNAME = "DMTLG_C02"
    
#
*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"
    
*DM_TDOMAIN
#
# <local or remote domain name> <network address> [<nwdevice>]
#
# Local network addresses
c01  NWADDR = "//newyork.acme.com:65432"  NWDEVICE ="/dev/tcp"

# Remote network addresses
b01  NWADDR = "//192.11.109.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"
tlr_bal RDOM = b02, b03 LDOM = c02
*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

Example2

This example shows the BEA Tuxedo Domains configuration file for one of the Bank Branches (BANK01).

#
#BEA TUXEDO DOMAIN CONFIGURATION FILE FOR A BANK BRANCH
#
#
*DM_LOCAL_DOMAINS
#
b01  GWGRP = auth
     TYPE = TDOMAIN
     DOMAINID = "BA.BANK01"
     DMTLOGDEV = "/usr/apps/bank/DMTLOG"
 
*DM_REMOTE_DOMAINS
#
c01  TYPE = TDOMAIN
     DOMAINID = "BA.CENTRAL01"
 
*DM_TDOMAIN
#
b01  NWADDR = "//192.11.109.156:4244" NWDEVICE = "/dev/tcp"
c01  NWADDR = "//newyork.acme.com:65432"  NWDEVICE ="/dev/tcp"
*DM_LOCAL_SERVICES
#
tlr_add   ACL = central
tlr_bal   ACL = central
 
*DM_REMOTE_SERVICES
#
 
OPA001   RNAME = "open_act"
CLA001   RNAME = "close_act"
CRD001   RNAME = "credit"
DBT001   RNAME = "debit"
BAL001   RNAME = "balance"
 
*DM_ACCESS_CONTROL
#
central   ACLIST = c01

Network Addresses

Suppose the local machine on which a TDomain is being run is using TCP/IP addressing and is named backus.company.com, with address 155.2.193.18. Further suppose that the port number at which the TDomain should accept requests is 2334. Assume that port number 2334 has been added to the network services database under the name bankapp-gwtaddr. The address can be represented in the following ways:

//155.2.193.18:bankapp-gwtaddr

//155.2.193.18:2334

//backus.company.com:bankapp-gwtaddr

//backus.company.com:2334

0x0002091E9B02C112

The last of these representations is hexadecimal format. The 0002 is the first part of a TCP/IP address. The 091E is the port number 2334 translated into a hexadecimal number. After that each element of the IP address 155.2.193.12 is translated into a hexadecimal number. Thus the 155 becomes 9B, 2 becomes 02 and so on.