BEA Logo BEA Tuxedo Release 7.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

 

   Tuxedo Doc Home   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo File Formats and Data Descriptions Reference

DMCONFIG for GWTOPEND(5)

Name

DMCONFIG for GWTOPEND - text version of a Domains configuration file for a TOP END Domain Gateway

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

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 several possible specification sections. Allowable section names are: DM_LOCAL_DOMAINS, DM_REMOTE_DOMAINS, DM_LOCAL_SERVICES, DM_REMOTE_SERVICES, DM_TOPEND, DM_RESOURCES, DM_ROUTING, and DM_ACCESS_CONTROL. Additional section names applicable only to other gateway types are: DM_TDOMAINS, DM_OSITP, DM_SNACRM, DM_SNASTACKS, and DM_SNALINKS. The DM_LOCAL_DOMAINS section must precede the DM_REMOTE_DOMAINS section.

Note: This reference page describes how to configure a domain gateway of only one type: TOPEND. For information about how to configure a domain of type TDOMAIN, see DMCONFIG(5). See BEA eLink documentation for information about how to configure an OSITP or an SNAX domain.

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 is 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 TOPEND 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. The entry defines a GWTOPEND instance (with its associated GWADM) that is associated with a single BEA TOP END system. The local domain communicates with remote domains of type TOPEND that are part of the same BEA TOP END system. The BEA TOP END system name is defined in the DM_TOPEND section.

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 described in the DM_LOCAL_SERVICES section, LDOM is the identifier that associates the local and remote 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

is used for grouping local domains into classes. TYPE can be set to one of the following values: TOPEND, TDOMAIN, SNAX, or OSITP. The TOPEND value indicates that this local domain can communicate only with a BEA TOP END system. The TDOMAIN value indicates that this local domain can communicate only 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 value indicates that this local domain communicates with another TP Domain via the OSI TP protocol. Domain types must be defined in the $TUXDIR/udataobj/DMTYPE file.

DOMAINID = string

is used to identify the local domain. DOMAINID must be unique across both local and remote domains. For a local domain of type TOPEND, this value is used as the BEA TOP END user ID for requests made to a BEA TOP END system. The associated password can be entered using the dmadmin(1) subcommand topendpasswd. The BEA TOP END user ID is 1-12 characters excluding any trailing null. ASCII characters ranging from " "(32) through "~" (126), excluding "/" (47) are valid for this string.

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 file are always used when the request is issued within a transaction.

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, and INCOMING_ONLY. A connection policy of ON_DEMAND means that a connection is 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. Multiple entries for a remote domain may be specified in the DM_TOPEND section if you want to configure multiple network addresses to be tried serially to connect to the remote domain. Connection retry processing is not allowed when the connection policy is ON_DEMAND.

A connection policy of ON_STARTUP means that a domain gateway attempts to establish a connection with its remote domains at gateway server initialization time. Multiple entries for a remote domain may be specified in the DM_TOPEND section if you want to configure multiple network addresses to be tried serially to connect to the remote domain. If CONNECTION_POLICY is set to ON_STARTUP, then remote services (that is, services advertised by the local domain gateway) are 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 are suspended. By default, this connection policy retries failed connections (all network addresses tried) 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 does not attempt an initial connection to remote domains upon starting and remote services are initially suspended. The domain gateway is available for incoming connections from remote domains or a connection can be attempted when requested due to an administrative "connect" command. Remote services are advertised when the local domain gateway receives an incoming connection or an administrative connection is made. Multiple entries for a remote domain may be specified in the DM_TOPEND section if you want to configure multiple network addresses to be tried serially only on an administrative connect to the remote domain. Connection retry processing is not allowed when the connection policy is INCOMING_ONLY.

DMTLOGDEV = string

specifies the BEA Tuxedo file system 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 file system. If not specified, the default is 100 pages.

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 tries to establish connections to remote domains. The minimum value is 0 and the maximum is MAXLONG. MAXLONG indicates that retry processing is 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.

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.

RETRY_INTERVAL = numeric

specifies the number of seconds between automatic attempts (all network addresses tried) 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.

SECURITY = value

specifies the type of application security to be enforced. The SECURITY parameter currently has four valid values for domains of type TOPEND: NONE, CLEAR, SAFE, or PRIVATE. The value NONE is the default and specifies that BEA TOP END security is not used by the system for authentication, authorization, or protection of inter-node messages. A value other then NONE specifies that BEA TOP END authentication and authorization are used by the BEA TOP END system and the gateway. In addition, the value CLEAR specifies that no protection is required for inter-node messages. The value SAFE indicates that messages should be sent using the Kerberos SAFE message checksum. The value PRIVATE indicates that messages should be encrypted using the Kerberos 4 implementation of DES. The value of SECURITY must be consistent with the corresponding BEA TOP END Node Manager configuration in the nm_config (4T) file on each BEA TOP END node. This is validated when a connection is established with a remote BEA TOP END node.

DM_REMOTE_DOMAINS Section

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

For TOP END Domain Gateway (TEDG) definitions, this section defines connections to Network Interface components on nodes of remote BEA TOP END systems.

Entries have the form:

RDOM required_parameters

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

Each RDOM defines a node in the BEA TOP END system to which a BEA TOP END LDOM may have a connection. The LDOM communicates with remote domains of type TOPEND that are part of the same BEA TOP END system as the LDOM. (The BEA TOP END system name is defined in the DM_TOPEND section.) Because of the BEA TOP END adjacent node routing topology, the services for the BEA TOP END system may reside on several different nodes. Therefore, a TEDG LDOM may need several RDOM entries to define connections to the BEA TOP END nodes where the desired BEA TOP END services reside.

The TYPE and DOMAINID parameters are required; MTYPE is not used for remote domains of type TOPEND:

TYPE = identifier

is used for grouping remote domains into classes. TYPE can be set to one of the following values: TOPEND, TDOMAIN, SNAX or OSITP. 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. 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 value indicates that this remote domain communicates with another TP domain via the OSI TP protocol.

DOMAINID = string

is 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". The DOMAINID value is used by the BEA TOP END gateway as the BEA Tuxedo user ID for requests made to the BEA Tuxedo system by the BEA TOP END system on this RDOM connection.

DM_TOPEND Section

This section defines the addressing information required by domains of type TOPEND. This section should have an entry per local domain if requests from remote domains to local services are accepted on that local domain (gateway group), and an 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.

Local and remote domains and their network addresses must be configured such that no more than one BEA TOP END gateway connection to a BEA TOP END node is activated for a particular TP_SYSTEM name at runtime. The BEA TOP END network interface protocol does not support multiple gateway connections. If an attempt is made to activate more than one connection, runtime errors occur in the TEDG or on the BEA TOP END node, and all connections except one are rejected. Due to variations in how network addresses can be specified, this type of configuration cannot be fully validated in this configuration file.

The following parameters are required:

NWADDR = string

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 BEA TOP END systems. 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 Network Interface components of the BEA TOP END system.

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. They may also be written in either of the following two forms:

"//host.name:port_number"

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

In the first of these formats, host.name 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 "#.#.#.#" is the dotted decimal format where each # represents a decimal number in the range 0 to 255.

The value of port_number is a decimal number in the range 0 to 65535, the hexadecimal representations of the string specified.

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 port address used by a local or a remote domain to accept connections. If string has the form "0xhex-digits", it must contain an even number of valid hexadecimal digits.

If the administrator wishes to specify INADDR_ANY for an LDOM listening address such as the one used by the BEA TOP END Network Interface, the format should be "//0.0.0.0:port_number". When an address is specified in this format, the TEDG (GWTOPEND) process can listen on port_number for all available IP addresses on the machine.

Note: Care should be taken when specifying the host address portion of the NWADDR parameter. When a BEA TOP END NI accepts a connection request that was issued from a TEDG, it resolves the network address of the TEDG to a name. The resolved name must match the defined hostname of the TEDG. If the defined hostname of the TEDG and the resolved name differ, including case, the NI connection fails. Such a failure may not be evident from either the GWTOPEND log file or the remote BEA TOP END NI log file. As a general rule, ensure that the hostname definitions match in the DMCONFIG file, the TOP END NI configuration file, the TOP END nodemap file, the TOP END tp_alias file, and the locally configured name resolution facilities. For further information on NI name resolution, refer to the tp_alias(4T) reference page in the BEA TOP END Programmer's Reference Manual.

NWDEVICE = string

specifies the device file name 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.

TP_SYSTEM = string

defines the BEA TOP END system associated with the LDOM or RDOM defined in the DM_LOCAL_DOMAINS and DM_REMOTE_DOMAINS sections of the configuration file. The parameter accepts a string that corresponds to the BEA TOP END system name. The BEA TOP END system name may contain from 1 to 8 characters, excluding any trailing null. ASCII characters ranging from " "(32) through "~" (126), excluding "/" (47) are valid for this string. The value of string must match the value of the TP_SYSTEM environment variable, which is defined in the nm_script (4T) file on the BEA TOP END system.

If the entry is for a BEA TOP END local domain (that is, if DOM matches a previously specified LDOM), then NWADDR is the network address to be used to listen for incoming connections. Only one entry may be configured for a local domain.

Multiple entries may be configured for a remote domain to specify network addresses to be tried serially on a connection attempt. The first one specified is considered 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. Each subsequent entry is used if all previous entries have failed. A connection attempt fails when all configured network addresses have been tried. Entries associated with a remote domain can be specified an unlimited number of times. Configuring too many network addresses or addresses that may not be operational can degrade performance.

If the entry is for a secondary remote domain (that is, if DOM matches a previously specified RDOM), then the entry is used only when a network connection cannot be established using the NWADDR of the primary entry (and any prior secondary entries). For every secondary entry:

Secondary remote gateway definitions are not recommended for use with TOP END Domain Gateways.

DM_ACCESS_CONTROL Section

This section specifies the access control lists used by the 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 defines the mapping information required to make BEA Tuxedo services and /Q queue spaces available to BEA TOP END systems. In DMCONFIG files written for domain gateways other than the TEDG, the purpose of entries in this section is to map local services to remote names for those services. In DMCONFIG files written for the TEDG, however, the type entry is used to define request/reply and conversational service mapping. Additionally, similar entries are accepted in this section for defining BEA Tuxedo queue space mapping and queue name mapping. Entries may be for a SERVICE, QSPACE or QNAME and are identified by the TYPE parameter. This section is required for TOP END domain gateways.

Lines within this section have one of these forms:

service [TYPE=SERVICE]required_parameters [optional_parameters]

qspace  TYPE=QSPACE required_parameters [optional_parameters]

qname   TYPE=QNAME required_parameters [optional_parameters]

where service is the name of an exported BEA Tuxedo service, qspace is the name of an exported BEA Tuxedo queue space, and qname is the name of a queue name defined within a BEA Tuxedo queue space. Each of these names may contain no more than 15 characters.

SERVICE entries define BEA Tuxedo services that are advertised (product, function, target) to the BEA TOP END system by the TEDG. Entries for BEA Tuxedo services that are advertised to a BEA TOP END system must include a mapping from BEA TOP END service identifiers (product, function, target, qualifier) to BEA Tuxedo service names. These service identifiers are used with the BEA TOP END tp_client_send(3T) and tp_client_signon(3T) routine calls.

QSPACE entries in this section define BEA Tuxedo queue spaces that are made available to BEA TOP END as RTQ queues (limitations apply). RTQ queues are made available in BEA TOP END by advertising the RTQ Group name, RTQ Queue name, and target name as a BEA TOP END service name. The BEA TOP END gateway handles tp_rtq_put(3T) requests sent to its RTQ queue names in a manner similar to that used by the RTQ server. Each request is then mapped to the BEA Tuxedo queue space identified in this QSPACE entry. Both QSPACE entries and QNAME entries are required for message queuing.

QNAME entries define the mapping of a BEA TOP END service request to a BEA Tuxedo queue name for requests enqueued to the BEA Tuxedo system via RTQ. QNAME entries are not advertised as services to the BEA TOP END system. QSPACE and QNAME entries are independent. Any combination of QSPACE and QNAME identifiers may be used by an application by supplying the associated BEA TOP END identifiers with a tp_rtq_put(3T) routine call. A run-time error results if the combination does not exist in the local BEA Tuxedo domain.

QNAME entries should be unique with respect to their product, function, target, and qualifier combination for a particular LDOM. If multiple entries of the same combination are configured, the TEDG uses only the first one.

Any SERVICE or QNAME entry that includes the TE_PRODUCT parameter, or any QSPACE entry that includes the TE_RTQGROUP parameter, is applicable to all local domains of type TOPEND if the entry is not configured for a particular local domain using the LDOM parameter. Entries configured for a specific LDOM are applicable only to the gateway for that domain.

Because SERVICE and QSPACE entries configure BEA TOP END service identifiers that are advertised as BEA TOP END services, these identifiers must not overlap for a particular LDOM. For a SERVICE entry, the TE_PRODUCT, TE_FUNCTION, and TE_TARGET are advertised. For a QSPACE entry, the TE_RTQGROUP, TE_RTQNAME, and TE_TARGET are advertised as product, function, and target identifiers. Therefore if a SERVICE entry product, function, and target match a QSPACE entry RTQ Group, RTQ Queue name and target, the TEDG cannot route the request. Note that, as in the BEA TOP END system, the default value for the target is the truncated node name.

If the configuration includes LDOMs for more than one BEA TOP END system, or if it includes multiple gateway types, the LDOM parameter should be specified in the local service entry. Mixed configurations that do not specify LDOM should not be created; they may prevent a gateway from initializing properly. If in doubt, explicitly set LDOM.

The following are the required and optional parameters for each entry type:

Entry TYPE

Required Parameters

Optional Parameters

SERVICE

TE_PRODUCT, TE_FUNCTION

TYPE, ACL, LDOM, INBUFTYPE, OUTBUFTYPE, TE_TARGET, TE_QUALIFIER

QSPACE

TYPE, TE_RTQGROUP, TE_RTQNAME

ACL, LDOM, TE_TARGET

QNAME

TYPE, TE_PRODUCT, TE_FUNCTION

LDOM, INBUFTYPE, TE_TARGET, TE_QUALIFIER

The following are descriptions of both required and optional parameters.

TYPE = SERVICE | QSPACE | QNAME

Specifies the type of entry being defined. The value SERVICE specifies that the entry defines the mapping parameters applicable to a local BEA Tuxedo service being exported to the BEA TOP END system. The value QSPACE specifies that the entry defines the mapping parameters applicable to a local BEA Tuxedo queue space being made available to the BEA TOP END system as an RTQ queue. The value QNAME specifies that the entry defines the parameters applicable to mapping a BEA TOP END service name to a BEA Tuxedo queue name for requests enqueued to the BEA Tuxedo system via RTQ. The default value is SERVICE.

TE_PRODUCT = string

specifies the BEA TOP END product name, which may contain up to 32 characters, excluding the trailing null. Only the following characters are considered valid: a-z, A-Z, 0-9, _, -, and .(period).

TE_FUNCTION = string

specifies the BEA TOP END function name, which may contain up to 8 characters, excluding the trailing null. Only the following characters are considered valid: a-z, A-Z, 0-9, _, -, and .(period).

TE_TARGET = string

specifies the BEA TOP END Message Sensitive Routing (MSR) target. The value of string may contain up to 8 characters, excluding the trailing null. Only the following characters are considered valid: a-z, A-Z, 0-9, _, -, and .(period). For SERVICE and QSPACE space entries, an asterisk is allowed as the last non-space character. The default value of the TE_TARGET parameter in the DMCONFIG file is spaces, indicating that it is not set. For SERVICE and QSPACE entries, the value of this parameter is changed at run time to default to the truncated node name of the TEDG. These values match the convention followed by the BEA TOP END system for default target names.

TE_QUALIFIER = integer

specifies the BEA TOP END function qualifier. Values in the following range are valid: 0-2147483647. The default is 0.

TE_RTQGROUP = string

specifies the BEA TOP END RTQ Group name. The value of string may contain up to 32 characters, excluding the trailing null. Only the following characters are considered valid: a-z, A-Z, 0-9, _, -, and .(period).

TE_RTQNAME = string

specifies the BEA TOP END RTQ Queue name. The value of string may contain up to 8 characters, excluding the trailing null. Only the following characters are considered valid: a-z, A-Z, 0-9, _, -, and .(period).

ACL = identifier

specifies the name of the access control list (ACL) to be used by the TEDG to restrict requests made to this SERVICE or QSPACE by BEA TOP END systems. The ACL is defined in the DM_ACCESS_CONTROL section of the DMCONFIG file. If this parameter is not specified, then access control is not performed for requests to this entry.

LDOM = identifier

specifies the name of the local domain that exports this service or queue space or to which the queue name entry applies. If this keyword is not specified then the entry is applicable to all the local domains of type TOPEND defined in the DM_LOCAL_DOMAINS section.

INBUFTYPE = type[:subtype]

restricts the input buffer type allowed for this service or queue name to a single buffer type. For BEA TOP END service and queue name entries, the valid values for type are: FML32, CARRAY, and X_OCTET.

OUTBUFTYPE = type[:subtype]

restricts the output buffer type accepted from this service to a single buffer type. For BEA TOP END service entries the valid values for type are: FML32, CARRAY, and X_OCTET.

DM_REMOTE_SERVICES Section

This section defines the mapping information required to make BEA TOP END services, RTQ queues, and services accessed via RTQ available to BEA Tuxedo applications. In DMCONFIG files written for domain gateways other than the TEDG, the purpose of entries in this section is to map local services to remote names for those services.

In a DMCONFIG file written for the TEDG, however, the purpose of entries in this section is different.

Entries may be included for a SERVICE, QSPACE, or QNAME, and are identified by the TYPE parameter. This section is required for TOP END domain gateways.

Lines within this section have one of these forms:

service [TYPE=SERVICE]required_parameters [optional_parameters]

qspace  TYPE=QSPACE   required_parameters [optional_parameters]

qname   TYPE=QNAME    required_parameters [optional_parameters]

where service is the BEA Tuxedo service name assigned to the BEA TOP END service, qspace is the BEA Tuxedo queue space name assigned to the RTQ Queue, and qname is the BEA Tuxedo queue name assigned to a BEA TOP END service accessed through RTQ. Each of these names may contain 15 characters or fewer.

SERVICE entries define BEA TOP END services that are advertised to the BEA Tuxedo domain by the TEDG. Entries for BEA TOP END services that are advertised to a BEA Tuxedo application must map BEA Tuxedo service names to BEA TOP END service identifiers. These service names are used with the XATMI tpcall(3c) and tpacall(3c) functions.

QSPACE entries in this section define BEA TOP END RTQ queues that are made available in the BEA Tuxedo domain by the TEDG as if they were BEA Tuxedo queue spaces (limitations apply). A queue space is made available in the BEA Tuxedo system by advertising the queue space name as a BEA Tuxedo service name. The gateway handles a tpenqueue request sent to its queue space name in a manner similar to that used by the TMQUEUE server. The request is then mapped to the RTQ queue identified in this qspace entry. Both QSPACE and QNAME entries are required for message queuing.

QNAME entries define the mapping of a BEA Tuxedo queue name to a BEA TOP END service name for requests enqueued to the BEA TOP END system. QNAME entries are not advertised as services to BEA Tuxedo systems. Note that QSPACE and QNAME entries are independent; any combination of QSPACE and QNAME identifiers may be used by an application with the tpenqueue(3c) function.

QNAME entries should be unique with respect to the queue name identifier for a particular LDOM. If multiple entries for the same identifier value are configured, the TEDG uses only the first one.

Any SERVICE or QNAME entry that includes the TE_PRODUCT parameter, or any QSPACE entry that includes the TE_RTQGROUP parameter, is applicable to each local domain of type TOPEND if the entry is not configured for a particular local domain using the LDOM parameter. Entries configured for a specific LDOM are also applicable to the gateway for that domain.

Because SERVICE and QSPACE entries configure service identifiers and queue space identifiers that are advertised as BEA Tuxedo services, these identifiers must not overlap for a particular LDOM. However, multiple entries of the same type and identifier are permitted for load balancing. All entries for the same service identifier must have the same value for the CONV parameter.

If the configuration includes LDOMs for more than one BEA TOP END system, or if it includes multiple gateway types, the LDOM parameter should be specified in the DM_REMOTE_SERVICES section of the DMCONFIG file. If an RDOM is specified in a remote services entry, or in a referenced routing entry, its value should match the value of the LDOM type (TOPEND) and TP_SYSTEM. Mixed configurations that do not specify LDOM, or that reference RDOMs of mixed types or mixed TP_SYSTEMs should not be created; they may prevent gateways from initializing properly. If in doubt, explicitly set LDOM and specify a remote domain (via the RDOM parameter or ROUTING). A "wildcard" specification for a remote domain should be used only when a single gateway type is defined.

The following are the required and optional parameters for each entry type.

Entry TYPE

Required Parameters

Optional Parameters

SERVICE

TE_PRODUCT, TE_FUNCTION

TYPE, LDOM, RDOM, INBUFTYPE, OUTBUFTYPE, CONV, TE_TARGET, TE_QUALIFIER, TRANTIME, ROUTING

QSPACE

TYPE, TE_RTQGROUP, TE_RTQNAME

LDOM, RDOM, TE_TARGET, TRANTIME, ROUTING

QNAME

TYPE, TE_PRODUCT, TE_FUNCTION

LDOM, INBUFTYPE, TE_TARGET, TE_QUALIFIER

The following are descriptions of both required and optional parameters.

TYPE = SERVICE | QSPACE | QNAME

specifies the type of entry being defined. The value SERVICE specifies that the entry defines the mapping parameters needed to make a BEA TOP END service available as a local BEA Tuxedo service. The value QSPACE specifies that the entry defines the mapping parameters needed to make a BEA TOP END RTQ queue available as a local BEA Tuxedo queue space. The value QNAME specifies that the entry defines the parameters needed to map a BEA Tuxedo queue name to a BEA TOP END service name for requests enqueued to the BEA TOP END system via /Q. The default value is SERVICE.

TE_PRODUCT = string

specifies the BEA TOP END product name, which may contain up to 32 characters, excluding the trailing null. Only the following characters are considered valid: a-z, A-Z, 0-9, _, -, and .(period).

TE_FUNCTION = string

specifies the BEA TOP END function name, which may contain up to 8 characters, excluding the trailing null. Only the following characters are considered valid: a-z, A-Z, 0-9, _, -, and .(period).

TE_TARGET = string

specifies the BEA TOP END Message Sensitive Routing (MSR) target, which may contain up to 8 characters, excluding the trailing null. Only the following characters are considered valid: a-z, A-Z, 0-9, _, -, and .(period). The default is spaces.

TE_QUALIFIER = integer

specifies the BEA TOP END function qualifier. Values in the following range are valid: 0-2147483647 (unsigned long max). The default is 0.

TE_RTQGROUP = string

specifies the BEA TOP END RTQ Group name, which may contain up to 32 characters, excluding the trailing null. Only the following characters are considered valid: a-z, A-Z, 0-9, _, -, and .(period).

TE_RTQNAME = string

specifies the BEA TOP END RTQ Queue name, which may contain up to 8 characters, excluding the trailing null. Only the following characters are considered valid: a-z, A-Z, 0-9, _, -, and .(period).

LDOM = identifier

specifies the name of the local domain that imports this service or RTQ queue, or to which a queue name entry applies. If this keyword is not specified then the entry is applicable to all the local domains of type TOPEND defined in the DM_LOCAL_DOMAINS section.

RDOM = identifier1[,identifier2][,identifier3]

specifies the name of the remote domain providing this service or RTQ queue. The remote domain must be of type TOPEND and it must be part of the same TP_SYSTEM as the local domain to which this entry applies. If this parameter is not specified and a routing criteria is not specified, the local domain assumes that any remote domain of type TOPEND with the same TP_SYSTEM value as the local domain provides the service or RTQ queue.

If you want to configure alternate remote domains with the identifier2 and identifier3 arguments, then you must specify ON_STARTUP as the value of the CONNECTION_POLICY parameter. 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 domains specified by identifier1 and identifier2 are unavailable, the remote domain specified by identifier3 is used.) Note that both load balancing (multiple remote service entries) and domains failover (using alternate remote domains specified with this parameter) may be used for a remote 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 this parameter is not specified, data-dependent routing is not used for this service. The value of identifier may contain up to 15 characters. If multiple entries for the same service or queue space name are included with different RDOM parameters, the value of the ROUTING parameter should be the same for all of these entries. Additionally, the remote domains configured (with RDOM) in the referenced routing criteria must be part of the same TP_SYSTEM as the local domain to which this entry applies.

INBUFTYPE = type[:subtype]

restricts the input buffer type allowed for this service or queue name to a single buffer type. For BEA TOP END service and queue name entries, the valid values for type are: FML32, CARRAY, and X_OCTET.

OUTBUFTYPE = type[:subtype]

restricts the output buffer type accepted from this service to a single buffer type. For BEA TOP END service entries, the valid values for type are: FML32, CARRAY, and X_OCTET.

CONV = {Y | N}

must be set to Y if a pseudo-conversation is to be managed by a BEA TOP END server application that may or may not maintain application context. If CONV is set to Y, the XATMI functions for conversation (tpconnect, tpsend, and tpdiscon) must be used. If CONV is set to N, the request/reply XATMI functions (tpcall, tpacall) must be used with this service. The default is N.

TRANTIME = integer

specifies (in seconds) the default interval (or timeout) 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 indicates the maximum timeout value for the machine, or 2147483648-1.

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 FML32. This description only applies to gateways of type TOPEND. For routing information for gateways of type TDOMAIN, refer to the DMCONFIG(5) reference page.

Lines within the DM_ROUTING section have the following form.

CRITERION_NAME required_parameters

where CRITERION_NAME is the identifier name of the routing entry that was specified in the services entry. The value of CRITERION_NAME may contain up to 15 characters.

The following parameters are required.

FIELD = identifier

specifies the name of the routing field, which may contain up to 30 characters. It is assumed that the value of this parameter is a field name identified in an FML field table (for FML32 buffers). The FLDTBLDIR32 and FIELDTBLS32 environment variables are used to locate FML field tables. If a field in an FML32 buffer is used for routing, the number of the field must be less than or equal to 8191.

RANGES = "string"

specifies the ranges and associated remote domain names (RDOM) for the routing field. string must be enclosed in double quotes. The value of string must be a comma-separated ordered list of range/RDOM pairs (see the "Example" section later in this reference page).

A range is 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). Note that the value of lower must be less than or equal to the value of upper.

To embed a single quote in a character string value (as in O'Brien, for example), you must precede it with 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, the value of the string "MIN - -5" is the set of all numbers less than or equal to -5 and the value of the string "6 - MAX" is the set of 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 wild-card range is allowed per entry and it should be listed last (ranges following it are ignored).

The routing field can be of any data type supported in FML. 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 (:).

BUFTYPE = "type1[:subtype1[,subtype2 . . . ]][;type2[:subtype3[, . . . ]]] . . ."

is a list of types and subtypes of data buffers for which this routing entry is valid. For TOP END domain gateways, the type is restricted to FML32. No subtype can be specified for type FML32. This parameter is required.

If the field value is not set (for FML32 buffers), or does not match any specific range and a wild-card range has not been specified, an error is returned to the application process that requested the execution of the remote service.

Files

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

Example

The following configuration file example is based on Example 1 in the core BEA Tuxedo DMCONFIG(5) reference page. The example has been extended to include a TOP END domain gateway with a single connection to a BEA TOP END system. In this scenario the BEA TOP END system is also running a banking application that offers services needed by users of a BEA Tuxedo application. Conversely, certain BEA Tuxedo services need to be available to the BEA TOP END system for use by modified client programs. A simple queuing example is also included.

The DMCONFIG file for this configuration is shown below. Changes from the original example in the core DMCONFIG(5) file are shown in bold.

# 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>]
# [<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"

c03 GWGRP = bankg3
TYPE = TOPEND
DOMAINID = "CENTRALBKGW"
DMTLOGDEV = "/usr/apps/bank/DMTLOG"
DMTLOGNAME = "DMTLG_C03"
SECURITY = CLEAR

#
*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"

b05 TYPE = TOPEND
DOMAINID = "BANK05"

*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.CENTRAL02"
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_TOPEND
#Local network addresses
c03 NWADDR = "//newyork.acme.com:65434"
TP_SYSTEM = "BANKSYS"
#Remote network addresses
b05 NWADDR = "//sandiego.acme.com:65434"
TP_SYSTEM = "BANKSYS"

*DM_LOCAL_SERVICES
#<service_name> [<Local Domain name>] [<access control>] [<exported svcname>]
# [<inbuftype>] [<outbuftype>]
#
#Not available to TOP END, no mapping
open_act ACL = branch LDOM=c01
close_act ACL = branch LDOM=c01
credit LDOM=c01
debit LDOM=c01
loan LDOM = c02 ACL = loans

#Services exported to TOP END and other domains
balance TYPE=SERVICE TE_PRODUCT="TUX" TE_FUNCTION="BALANCE" LDOM=c03

#Queues available to TOP END
qspace TYPE=QSPACE TE_RTQGROUP="TUXQUEUE" TE_RTQNAME="TUXQ" LDOM=c03
qname TYPE=QNAME TE_PRODUCT="TUX" TE_FUNCTION="QSERV" LDOM=c03

*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

Network Addresses

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

//155.2.193.18:bankapp-gwaddr

//155.2.193.18:2334

//backus.company.com:bankapp-gwaddr

//backus.company.com:2334

0x0002091E9B02C112

The last of these representations is written in hexadecimal format. The string 0002 is the first part of a TCP/IP address. 091E is the port number 2334 translated into a hexadecimal number. The rest of the address (9B02C112) consists of hexadecimal translations of each element of the IP address (155.2.193.12): 9B is translated from 155, 02 is translated from 2, and so on.

See Also

dmadmin(1), dmloadcf(1), dmunloadcf(1), tmboot(1), tmshutdown(1), DMADM(5), GWADM(5), GWTOPEND(5)

BEA TOP END Programmer's Reference Manual: tp_intro(3T), ni_config(4T), nm_config(4T), nm_script(4T)

Administering a BEA Tuxedo Application at Run Time

Setting Up a BEA Tuxedo Application

Programming a BEA Tuxedo Application Using C

Using the BEA Tuxedo Domains Component

Using the BEA Tuxedo TOP END Domain Gateway