Understanding the DMCONFIG File

Before you configure Oracle Tuxedo Mainframe Adapter for OSI TP and set up the gateway configuration, it is helpful to understand the DMCONFIG file.

This section covers the following topics:

•	“Overview of the DMCONFIG File”

•	“DMCONFIG File Format”

•	“DMCONFIG File Sections”

•	“Methods for Modifying Configurations”

For detailed instructions on how to configure TMA OSI TP by modifying the DMCONFIG file, refer to “Configuring Oracle Tuxedo Mainframe Adapter for OSI TP.”

Overview of the DMCONFIG File

The configuration specified in the DMCONFIG file controls much of the operation of the TMA OSI TP gateway. A sample of this file is provided in the installation directory of your TMA OSI TP product software.

DMCONFIG is the ASCII version of a Tuxedo System/Domain domain configuration file. The DMCONFIG file is parsed and loaded into a binary version by the dmloadcf utility. The binary configuration file, called the BDMCONFIG, contains information used by domain gateways to initialize the context required for communications with other domains. In its monitoring activity, dmadmin uses the binary file (or a copy of it). There is one BDMCONFIG file for each Tuxedo System/Domain application that uses the /Domain feature. Refer to Processing a Configuration File with the dmloadcf Utility for more information about the binary configuration files.

A DMCONFIG file, and its binary BDMCONFIG counterpart, are analogous to the UBBCONFIG and TUXCONFIG files of a non-/Domain System/T application. The DMCONFIG file extends the definition of a non-/Domain System/T application so that the application becomes a domain.

OSI TP Application Addresses Used in the DMCONFIG File

OSI TP application address information is used for several parameters in the DMCONFIG file. The address of a Tuxedo application using OSI TP consists of a collection of the names of each of the components described in Table 3‑1. These names must coordinate with the remote domain OSI TP implementation.

Starting with eLink OSI TP 4.0, the OSI TP implementation is optimized to eliminate several layers of the protocol stack. As a result, the P_SEL, S_SEL, and T_SEL are not used for routing connections. Connections are routed solely based on the NWADDR parameter. Therefore, TMA OSI TP requires the NWADDR parameter be unique.

•	Multiplexed Protocol

The multiplexed protocol uses a TCP/IP connection. Therefore, if the multiplexed protocol is in use, P_SEL, S_SEL, and T_SEL parameters do not apply and are ignored if configured.

•	Non-multiplexed Protocol

The non-multiplexed protocol sends messages using OSI over TCP/IP (as implemented in RFC1006). When using the non-multiplexed protocol, you may need to specify the P_SEL, S_SEL, and/or T_SEL parameters, depending on the addressing requirements of the remote system. If the P_SEL, S_SEL, and/or T_SEL are configured, TMA OSI TP encodes the selectors for outgoing connections and TMA OSI TP validates incoming connections to verify the selectors are correct. However, TMA OSI TP does not require the use of P_SEL, S_SEL, and T_SEL.

 

Table 3‑1 OSI TP Application Components

Component	Description
Application Entity Title (AET)	A dotted integer based on the ISO Object Identifier Based NameForm that uniquely identifies the OSI TP node. See the following description of the AET, “Creating an Application Entity Title.”
* Presentation Selector (P_SEL)	A logical name for the address of the software that provides the presentation layer services for OSI protocols.
* Session Selector (S_SEL)	A logical name for the address of the software that provides the session layer services for OSI protocols.
* Transport Selector (T_SEL)	A logical name for the address of the software that provides the transport layer services for OSI protocols.
Network Address (NWADDR)	A globally unique computer system address used to identify the OSI TP node.

* Application components only valid for non-multiplexing communications.

Creating an Application Entity Title

The Application Entity Title equals the APT (application process title) plus the AEQ (application entity qualifier). Each OSI TP node in your network must have a unique AET. If your site is participating in a global OSI network, you need to contact the OSI registration authority for a valid OSI Object-ID, otherwise, create your own unique AET as described below.

If your site is in a closed network, create an Object ID with at least three “arcs”. Each arc is a dotted integer and represents an identifier for the Object ID. A valid OSI TP Object ID has either 0 or 1 for the first arc, and 0,1,2,or 3 for the second arc.

One suggested convention is to set APT to 1.3, followed by the IP address specified in the corresponding NWADDR parameter and set the AEQ to the port number specified in the NWADDR parameter. For example:

domain1
AET="{1.3.123.55.222.51},{12344}"
NWADDR="123.55.222.51:12344"

DMCONFIG File Format

The format of a domain configuration file is as follows:

•

The file is made up of eight possible specification sections. Lines beginning with an asterisk (*) indicate the beginning of a specification section. Each such line contains the name of the section immediately following the *. Refer to “DMCONFIG File Sections” for more information about the sections.

•	Parameters are generally specified by: KEYWORD = value. This sets KEYWORD to value. Valid keywords are described in the following sections. KEYWORDs are reserved; they cannot be used as values unless they are enclosed in quotes.

Caution:

Enter all parameters on separate lines. The NWADDR parameter is the only exception; multiple network address values may be listed in a single line.

•

Lines beginning with the reserved word, DEFAULT:, contain parameter specifications that apply to all the lines that follow in the section in which they appear. Default specifications can be used in any of the sections. Defaults 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 by specifying another value for the parameter on a non-DEFAULT: line. The override parameter setting is valid for that line only; lines that follow revert to the default setting. If DEFAULT: appears on a line without any keywords or values, 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 in the description of that parameter.

•

If a value is an identifier, standard C rules are used. An identifier must start with an alphabetic character or underscore and contain only alphanumeric characters or underscores. The maximum allowable length of an identifier is 30 (not including the terminating null). An identifier cannot be the same as any KEYWORD.

•	A value that is neither an integer number nor an identifier must be enclosed in double quotes. Certain special characters can be included in a string by preceding them with a backslash.

•	“\\” translates to a single backslash

•	“\”\”” translates to a double quote

•	“\n” translates to a new line

•	“\t” translates to a tab

•	“\f” translates to a form feed

•	“\x” (where x is any character other than one of the previously mentioned special characters) translates to x

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

•	“#” introduces a comment. A new line 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 new line. Comments cannot be continued

DMCONFIG File Sections

The DMCONFIG file consists of the following sections and parameters that define new gateway configurations.

•	DM_LOCAL_DOMAINS Section

Note:

The DM_LOCAL_DOMAINS section must precede the DM_REMOTE_DOMAINS section.

•	DM_REMOTE_DOMAINS Section

•	DM_OSITPX Section

•	DM_ACCESS_CONTROL Section

•	DM_LOCAL_SERVICES Section

•	DM_REMOTE_SERVICES Section

•	DM_ROUTING Section

Following is a sample configuration file and detailed descriptions of the DMCONFIG file sections and the parameters applicable to each section.

Sample Configuration File

The following sample DMCONFIG file represents non-multiplexing communication.

Listing 3‑1 Sample DMCONFIG File (Non-multiplexing)

*DM_LOCAL_DOMAINS

dalnt8
GWGRP = OSIGRP
TYPE = OSITPX
DOMAINID = "dalnt8"
BLOCKTIME = 30
DMTLOGDEV = "D:\tuxedo\log\DMLOG"
SECURITY = DM_PW # turns link layer security on
DMTLOGNAME = DMLOG


*DM_REMOTE_DOMAINS

dal2200 TYPE=OSITPX DOMAINID="dal2200"
openti TYPE=OSITPX DOMAINID="openti"
icl2 TYPE=OSITPX DOMAINID="icl2"
aseries1 TYPE=OSITPX DOMAINID="aseries1"

*DM_OSITPX

dalnt8
AET="{1.3.132.61.146},{3}"
TAILOR_PATH="d:\tuxedo\configs\tailor.txt"
NWADDR="//dalnt8:102"
DNS_RESOLUTION=STARTUP # this is the default

dal2200
AET="{1.3.132.61.46},{3}"
XATMI_ENCODING="OLTP_TM2200"
NWADDR="132.61.46.3;132.61.147.1" #redundant IP addresses
T_SEL="OSITP"

openti
AET="{1.3.122.62.103},{209}"
NWADDR="122.62.103.209:2001"
OPTIONS=SECURITY_SUPPORTED

icl2
AET="{1.3.142.60.203},{4}"
NWADDR="142.60.203.4"
T_SEL="ICLTP"
S_SEL="SSEL"
P_SEL="PSEL"

aseries1
AET="{1.3.123.55.222},{51}"
NWADDR="123.55.222.51"
XATMI_ENCODING="PRELIMINARY"
T_SEL="0x5453"
S_SEL="0x3F5C3F"

*DM_ACCESS_CONTROL
mylist ACLIST = dalnt8, dal2200

*DM_LOCAL_SERVICES
TOUPPERF
INRECTYPE="VIEW:view10"
OUTBUFTYPE="FML:"
COUPLING=LOOSE #this is the default

TOUPPERF32
INRECTYPE="VIEW:view10a"
OUTBUFTYPE="FML32:"
COUPLING=TIGHT


TOUPPERV
INBUFTYPE="X_C_TYPE:v10"
INRECTYPE="VIEW:upper"
COUPLING=LOOSE

TOUPPERC OUTRECTYPE="X_OCTET" OUTBUFTYPE="CARRAY"
INRECTYPE="X_OCTET"
COUPLING=TIGHT

TOUPPERS OUTRECTYPE="X_OCTET" OUTBUFTYPE="STRING"
INRECTYPE="X_OCTET"

TOUPPERX OUTRECTYPE="STRING" OUTBUFTYPE="STRING"
INRECTYPE="X_OCTET"

*DM_REMOTE_SERVICES
DEFAULT: TRANTIME=300

ECHOXOCT RNAME="ECHOSRVR" OUTBUFTYPE="X_COMMON:ECHOVIEW" RDOM=aseries1 LDOM=dalnt8
ECHOXCOM RNAME="ECHOSRVR" RDOM=openti LDOM=dalnt8 AUTOPREPARE=Y

ECHOXCTYPE RNAME="ECHOSRVR"
INBUFTYPE="X_C_TYPE:ECHOVIEW"
INRECTYPE="X_COMMON:ECHOVIEW"
OUTBUFTYPE="X_C_TYPE:ECHOVIEW"
OUTRECTYPE="X_COMMON:ECHOVIEW"
RDOM=aseries1
LDOM=dalnt8
CONV=Y
ECHOVIEW RNAME="ECHOSRVR"
INBUFTYPE="VIEW:ECHOVIEW"
INRECTYPE="X_COMMON:ECHOVIEW"
OUTBUFTYPE="VIEW:ECHOVIEW"
OUTRECTYPE="X_COMMON:ECHOVIEW"
RDOM=openti
LDOM=dalnt8
TPSUT_TYPE = "PRINTABLESTRING"
REM_TPSUT="tpmvs"

*DM_ROUTING
ACCOUNT FIELD = branchid BUFTYPE = "View:account"
RANGE = "MIN - 1000:aseries1, 1001-3000:openti"

 

The following sample DMCONFIG file represents multiplexing communication.

Listing 3‑2 Sample DMCONFIG File (Multiplexing)

*DM_LOCAL_DOMAINS

dalnt8
GWGRP = OSIGRP
TYPE = OSITPX
DOMAINID = "dalnt8"
BLOCKTIME = 30
DMTLOGDEV = "D:\tuxedo\log\DMLOG"
SECURITY = DM_PW # turns link layer security on
DMTLOGNAME = DMLOG


*DM_REMOTE_DOMAINS

openti TYPE=OSITPX DOMAINID="openti"
aseries1 TYPE=OSITPX DOMAINID="aseries1"

*DM_OSITPX

dalnt8
EXTENSIONS="MULTIPLEX_POLICY=DEMAND"
AET="{1.3.132.61.146},{3}"
TAILOR_PATH="d:\tuxedo\configs\tailor.txt"
NWADDR="//dalnt8:2020"
DNS_RESOLUTION=STARTUP # this is the default

openti
EXTENSIONS="MULTIPLEX=Y"
AET="{1.3.122.62.103},{209}"
NWADDR="122.62.103.209:2001"
OPTIONS=SECURITY_SUPPORTED

aseries1
EXTENSIONS="MULTIPLEX=Y"
AET="{1.3.123.55.222},{51}"
NWADDR="123.55.222.51:12344"
XATMI_ENCODING="NATIVE_A_SERIES"

*DM_ACCESS_CONTROL
mylist ACLIST = dalnt8, openti

*DM_LOCAL_SERVICES
TOUPPERF
INRECTYPE="VIEW:view10"
OUTBUFTYPE="FML:"
COUPLING=LOOSE #this is the default

TOUPPERF32
INRECTYPE="VIEW:view10a"
OUTBUFTYPE="FML32:"
COUPLING=TIGHT


TOUPPERV
INBUFTYPE="X_C_TYPE:v10"
INRECTYPE="VIEW:upper"
COUPLING=LOOSE

TOUPPERC OUTRECTYPE="X_OCTET" OUTBUFTYPE="CARRAY"
INRECTYPE="X_OCTET"
COUPLING=TIGHT

TOUPPERS OUTRECTYPE="X_OCTET" OUTBUFTYPE="STRING"
INRECTYPE="X_OCTET"

TOUPPERX OUTRECTYPE="STRING" OUTBUFTYPE="STRING"
INRECTYPE="X_OCTET"

*DM_REMOTE_SERVICES
DEFAULT: TRANTIME=300

ECHOXOCT RNAME="ECHOSRVR" OUTBUFTYPE="X_COMMON:ECHOVIEW" RDOM=dal2200 LDOM=dalnt8
ECHOXCOM RNAME="ECHOSRVR" RDOM=openti LDOM=dalnt8 AUTOPREPARE=Y

ECHOXCTYPE RNAME="ECHOSRVR"
INBUFTYPE="X_C_TYPE:ECHOVIEW"
INRECTYPE="X_COMMON:ECHOVIEW"
OUTBUFTYPE="X_C_TYPE:ECHOVIEW"
OUTRECTYPE="X_COMMON:ECHOVIEW"
RDOM=aseries1
LDOM=dalnt8
CONV=Y
ECHOVIEW RNAME="ECHOSRVR"
INBUFTYPE="VIEW:ECHOVIEW"
INRECTYPE="X_COMMON:ECHOVIEW"
OUTBUFTYPE="VIEW:ECHOVIEW"
OUTRECTYPE="X_COMMON:ECHOVIEW"
RDOM=icl2
LDOM=dalnt8
TPSUT_TYPE = "PRINTABLESTRING"
REM_TPSUT="tpmvs"

*DM_ROUTING
ACCOUNT FIELD = branchid BUFTYPE = "View:account"
RANGE = "MIN - 1000:aseries1, 1001-3000:openti, *:dal2200"

 

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.

Format

DM_LOCAL_DOMAINS entries have the following format.

LDOM required parameters [optional parameters]

where

LDOM is an identifier value used to name each local domain.

LDOM must be unique within a particular configuration. As described in the DM_LOCAL_SERVICES section, LDOM is the identifier that connects local services with a particular gateway group.

Valid Parameters

Following is a list of valid parameters for the DM_LOCAL_DOMAINS section:

 

Table 3‑2 Parameters for DM_LOCAL_DOMAINS

Parameter	Required/Optional	Description
AUDITLOG	Optional	Name of the audit log
BLOCKTIME	Optional	Maximum wait time allowed for a blocking call
DMTLOGDEV	Optional	Tuxedo file system that contains the domain transaction log
DMTLOGNAME	Optional	Name of the domain transaction log
DMTLOGSIZE	Optional	Size of the domain transaction log
DOMAINID	Required	Local domain
GWGRP	Required	Name of gateway server group
MAXRDTRAN	Optional	Maximum number of remote domains that can be involved in a transaction
MAXTRAN	Optional	Maximum number of simultaneous global transactions allowed on local domain
SECURITY	Optional	Link-level of security for local domain
TYPE	Required	Classification of local domain

Parameter Definitions

Following is more detailed information about each of the DM_LOCAL_DOMAINS section parameters:

AUDITLOG = “string”

Specifies the name of the audit log file for this local domain. The audit log feature is activated from the dmadmin 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. BLOCKTIME may need to be increased due to remote network latency or if security is turned on. If this parameter is not specified, the default value 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 is always used when the request is issued within a transaction.

DMTLOGDEV= “string”

Specifies the Tuxedo file system that contains the Domain transaction log (DMTLOG) for this machine. The DMTLOG is stored as a 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 file system, but each local domain must have its own log (a table in the DMTLOGDEV) named as specified by the DMTLOGNAME keyword.

DMTLOGNAME = “string”

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

DOMAINID = “string”

identifies 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 32 octets or fewer in length. If the value is a string, it must be 31 characters or fewer.

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 and the name of the gateway server group, that is, each GWGRP must have its own, unique DOMAINID.

MAXRDTRAN = numeric

specifies the maximum number of remote 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.

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. MAXGTT is the maximum number of transactions for all the domains on a given machine. If not specified, the default is the value of MAXGTT.

SECURITY = {NONE | DM_PW}

specifies whether link-level security for the local domain is turned on. When this parameter is set to DM_PW, incoming connections from remote domains are authenticated using the passwords defined in the *DM_PASSWORDS section of the BDMCONFIG file. In order to pass userids to the remote domain for user authentication, SECURITY=DM_PW must be set. The default is NONE and indicates that no security is used.

Note:

This parameter must appear AFTER the TYPE=OSITPX parameter.

TYPE = identifier

groups local domains into classes. TYPE can be set to one of the following values: TDOMAIN or OSITPX. The TDOMAIN value indicates that this local domain can only communicate with another Tuxedo System/Domain. The OSITPX 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. The TMA OSI TP install automatically updates the DMTYPE file with the required type needed.

See Also

Refer to Table A‑1 “DM_LOCAL_DOMAINS SECTION” for more information about setting these parameters through the dmadmin utility.

DM_REMOTE_DOMAINS Section

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

Format

DM_REMOTE_DOMAINS entries have the following format:

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.

Valid Parameters

Following is a list of valid parameters for the DM_REMOTE_DOMAINS section:

 

Table 3‑3 Parameters for DM_REMOTE_DOMAINS

Parameter	Required/Optional	Description
DOMAINID	Required	ID of remote domain.
TYPE	Required	Class of remote domain
CODEPAGE	Optional	Codepage translation table for NATIVE_A_SERIES encoding.

Parameter Definitions

Following is more detailed information about each of the DM_REMOTE_DOMAINS section parameters:

DOMAINID = “string”

identifies a remote domain. DOMAINID must be 32 octets or fewer in length. If the value is a string, it must be 31 characters or fewer. 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”.

TYPE = identifier

groups remote domains into classes. TYPE can be set to one of the following values: TDOMAIN or OSITPX. The TDOMAIN value indicates that this remote domain can only communicate with another Tuxedo System/Domain Domain. The OSITPX value indicates that this remote domain communicates with another TP domain via the OSI TP protocol.

CODEPAGE = CPNAME

specifies the codepage translation table for NATIVE_A_SERIES encoding. The cpname keyword is case sensitive. This parameter is only valid when XATMI_ENCODING=NATIVE_A_SERIES. Refer to Implementing NATIVE-A Encoding for more information.

See Also

Refer to Table A‑2 “DM_REMOTE_DOMAINS SECTION” for more information about setting these parameters through the dmadmin utility.

DM_OSITPX Section

This section defines the addressing information required by domains of type OSITPX. This section should have at least one entry per gateway group (local domain), and at least one entry per remote domain of type OSITPX. The bridged configuration can have multiple gateways in a local domain.

Format

DM_OSITPX entries have the following format.

DOM required parameters [optional parameters]

where

DOM is an identifier value used to identify 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 sections or RDOM in the DM_REMOTE_DOMAINS section.

Valid Parameters

Following is a list of valid parameters for the DM_OSITPX section:

 

Table 3‑4 Parameters for DM_OSITPX

Parameter	Required/ Optional	Description
AET	Required for LDOMs and RDOMs	Application entity title
DNS_RESOLUTION	Optional for LDOMs	Indicator for when DNS name is resolved
EXTENSIONS	Optional for LDOMs and RDOMs	Series of parameters to control operation of the LDOM and RDOM.
NWADDR	Required for LDOMs and RDOMs	List of IP addresses with their optional port numbers or a DNS name and its optional port number
OPTIONS	Optional for RDOMs	Optional flags to turn on OSI TP features such as security
P_SEL	Optional for LDOMs and RDOMs	Logical name of address for software that provides presentation layer services
S_SEL	Optional for LDOMs and RDOMs	Logical name of address for software that provides session layer services
T_SEL	Optional for LDOMs and RDOMs This parameter is ignored for multiplexed LDOMs.	Logical name of address for software that provides transport layer services
TAILOR_PATH	Optional for LDOMs	Path to optional OSI TP tailor file
XATMI_ENCODING	Optional for RDOMs	Version of XATMI protocol

Parameter Definitions

Following is more detailed information about each of the DM_OSITPX section parameters:

AET = “string”

indicates the application entity title that this LDOM or RDOM uses. This address must be unique among all hosts communicating in the OSI TP network. This number matches the local AE Title on the remote (OLTP) node. Refer to OSI TP Domains Components for more information about AETs.

The format accepted for the value of string is

“{object identifier}, {integer}”

The first element represents the APT defined as an object identifier (i.e., a sequence of integer values separated by periods) and the second element represents an AEQ defined as an integer constant, for example,
AET = “{1.3.15.0.3},{1}”.

For more information about creating an application entity Title, refer to “Creating an Application Entity Title.”

Note:

The braces are part of the syntax and must be included within the quotes.

DNS_RESOLUTION = {STARTUP | RUNTIME}

indicates whether the DNS name should be resolved when the gateway is started or at runtime. The DNS name is for the network address defined by NWADDR. The runtime option allows support of DHCP networks. When using DNS_RESOLUTION as a runtime option, failed services may occur due to delays in resolving the DNS names. DNS_RESOLTUTION, when configured for an LDOM, indicates the policy for the entire gateway process.

The default is STARTUP.

STARTUP

indicates the DNS name is resolved when the gateway is booted and never resolved again.

RUNTIME

indicates the DNS name is resolved again when needed. If three minutes of inactivity has elapsed, the DNS server is pinged for resolution (in case the address changes).

EXTENSIONS = "string"

controls operations. Valid parameters are separated by a semi-colon ";" and include the following:

For RDOMs, valid parameters are:

"MULTIPLEX={Y|N}"

The default is N.

Y indicates that this RDOM uses the multiplexed protocol.

N indicates that this RDOM uses the non-multiplexed protocol.

"MULTIPLEXCOMPRESS={Y|N}"

The default is N.

Y indicates that this RDOM enables data compression.

N indicates that this RDOM does not enable data compression.

"ONLINE={N|Y}"

The default is Y.

Y indicates that the RDOM is considered online initially. If MULTIPLEX=N and MULTIPLEX_POLICY=NONE for the corresponding LDOM, then a socket connection is established from the LDOM to the RDOM at startup to verify that the RDOM is available. If MUTLIPLEX=Y and MULTIPLEX_POLICY=STARTUP for the corresponding LDOM, then a socket connection is established from the LDOM to the RDOM at startup. If MUTLIPLEX=Y and MULTIPLEX_POLICY=DEMAND for the corresponding LDOM, then a socket connection is established from the LDOM to the RDOM the first time it is needed.

N indicates that the RDOM is considered to be offline initially. No socket connection is established from the LDOM to the RDOM at startup, even if MULTIPLEX_POLICY=STARTUP for the corresponding LDOM. No incoming socket requests are allowed from an offline RDOM.

"RDOMASSOCRETRY=n"

The default is given by the TAILOR parameter RdomAssocRetry (refer to “Tuning OSI TP-Specific Tables with the TAILOR File.”) n is a numeric value which represents the time in seconds between association retries for unavailable RDOMs. This value only applies if MULTIPLEX=N. If MULTIPLEX=Y, this value is ignored; the multiplex protocol has its own algorithm for determining how often to retry connection attempts.

For LDOMs, valid parameters are:

MULTIPLEX_POLICY={STARTUP|DEMAND|NONE}

The default is NONE.

NONE indicates that this LDOM uses the non-multiplexed protocol.

STARTUP indicates that this LDOM uses the multiplexed protocol and a single socket connection is established between the LDOM and each RDOM that has MULTIPLEX=Y and ONLINE=Y at startup.

DEMAND indicates the LDOM uses the multiplexed protocol and a single socket connection is established between the LDOM and an RDOM that has MULTIPLEX=Y the first time it is needed.

NWADDR = “string”

indicates the network address that this LDOM or RDOM uses and, optionally, the port number. The network address may be either an IP address, if using TCP|IP networks, or a DNS name. The default port number is port 102. For local domains, the NWADDR specifies which IP address TMA OSI TP will listen on. For remote domains, the NWADDR specifies which network messages will be sent on. You may list multiple network addresses by listing each individual address separated by semicolons if the machine is equipped with multiple network cards. Make sure to enter all the IP addresses on one line and separate them with a semi-colon (;). You may want to configure redundant network paths: up to 8 may be specified.

Note:

You must explicitly specify a port number greater than or equal to 1024 if all the following are true:

- the platform is Unix

- the userid running Tuxedo is not root

- this is an LDOM

- MULTIPLEX_POLICY is DEMAND or STARTUP (multiplexing is in use)

Examples:

“#.#.#.#:port-number” IP Address
“//host-name:port-number” DNS Name
"//host-name:port-number; //host-name:port-number" Redundant DNS Names

OPTIONS = SECURITY_SUPPORTED

indicates optional parameters for RDOMs. The SECURITY_SUPPORTED value indicates that this remote domain supports the OSITP security extension. This value provides backward compatibility and is valid only when describing an RDOM.

P_SEL = “string” or “hex digits"

specifies the logical name for the address of the software that provides the presentation layer services for OSI protocols. The value can be one to 4 ASCII non-control characters (those represented by the hexadecimal numbers 20 to 7E), one to 4 hexadecimal octets, or NONE (null). A value of NONE is the default. Examples: “PSEL”, “0x3F5C'

Note:

This value is ignored for multiplexed connections. For additional information about when to use this parameter for defining application addresses, refer to “OSI TP Application Addresses Used in the DMCONFIG File.”

S_SEL = “string” or “hex digits"

specifies the logical name for the address of the software that provides the session layer services for OSI protocols. The value can be one to 16 ASCII non-control characters (those represented by the hexadecimal numbers 20 to 7E), one to 16 hexadecimal octets, or NONE (null). A value of NONE is the default. Examples: “SSEL”, “0x3F5C3F'

Note:

This value is ignored for multiplexed connections. For additional information about when to use this parameter for defining application addresses, refer to “OSI TP Application Addresses Used in the DMCONFIG File.”

T_SEL = “string” or “hex digits"

represents the logical name for the address of the software that provides the transport layer services for OSI protocols. The value can be one to 32 ASCII non-control characters (those represented by the hexadecimal numbers 20 to 7E), one to 32 hexadecimal octets, or NONE (null). Examples: “OSITP”, “0x5453"

Note:

This value is ignored for multiplexed connections. For additional information about when to use this parameter for defining application addresses, refer to “OSI TP Application Addresses Used in the DMCONFIG File.”

TAILOR_PATH = “string”

indicates the full path to the optional OSI TP tailor file used for tuning OSI TP-specific tables. Double quotes are required. If not specified, preset defaults are used. This parameter is valid only when describing an LDOM. Refer to Tuning OSI TP-Specific Tables with the TAILOR File for more information.

XATMI_ENCODING = {CAE | PRELIMINARY | OLTP_TM2200 | NATIVE_A_SERIES}

specifies the version of the XATMI protocol used to communicate with a remote application. This parameter is only valid for an RDOM. Valid values are:

CAE (default)
PRELIMINARY (used specifically with Unisys MCP OLTP systems)
OLTP_TM2200 (used specifically with Unisys TM 2200 systems)
NATIVE_A_SERIES (used specifically with Unisys MCP OLTP systems that support this encoding type)

See Also

Refer to Table A‑3 “DM_OSITPX SECTION” for more information about setting these parameters through the dmadmin utility.

DM_ACCESS_CONTROL Section

This section specifies the access control lists used by local domain.

Format

DM_ACCESS_CONTROL entries have the following format.

ACL_NAME required parameters

where

ACL_NAME is a (identifier) name used to identify a particular access control list; it must be 15 characters or less in length.

Valid Parameters

Following is a list of valid parameters for the DM_ACCESS_CONTROL section:

 

Table 3‑5 Parameter for DM_ACCESS_CONTROL

Parameter	Required/Optional	Description
ACLIST	Required	List of remote domain names

Parameter Definitions

Following is more detailed information about the DM_ACCESS_CONTROL section parameter:

ACLIST = identifier [,identifier]

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

See Also

Refer to Table A‑7 “DM_ACCESS_CONTROL SECTION” for more information about setting these parameters through the dmadmin utility.

DM_LOCAL_SERVICES Section

This section provides information on the services exported by each local domain. This section is optional and 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 Tuxedo System/Domain application. If this section is defined then it should be used to restrict the set of local services that can be requested from a remote domain.

Format

DM_LOCAL_SERVICES entries have the following format.

service [optional parameters]

where

service is the (identifier) 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 Tuxedo System/Domain application. Notice that exported services inherit the default or special properties specified for the service in an entry in the SERVICES section of the TUXCONFIG file. Some of these parameters are: LOAD, PRIO, AUTOTRAN, ROUTING, BUFTYPE, and TRANTIME.

Valid Parameters

Following is a list of valid parameters for the DM_LOCAL_SEVICES section:

 

Table 3‑6 Parameters for DM_LOCAL_SERVICES

Parameter	Required/Optional	Description
ACL	Optional	Name of access control list
COUPLING	Optional	Indicator for type of coupling
INBUFTYPE	Optional	Type and subtype of buffer returned by local service
INRECTYPE	Optional	Type and format of the reply buffer expected by remote client
LDOM	Optional	Name of local domain exporting a service
OUTBUFTYPE	Optional	Type and format of request buffer expected by local service
OUTRECTYPE	Optional	Type and format of request buffer expected by local service
RNAME	Optional	Name of service exported to remote domains

Parameter Definitions

Following is more detailed information about the DM_LOCAL_SEVICES section parameters:

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 is not performed for requests to this service.

COUPLING = {TIGHT | LOOSE}

specifies service (transaction) coupling to be tight or loose when requests for this local service come from the same remote domain. The default is LOOSE. This means data base updates made by the first request to this local service cannot be seen by the second request to the local service even though they are involved in the same global transaction. By making this value TIGHT, multiple calls to the same service from the same domain are tightly-coupled. Data base updates made by the first request can be seen by the second request. This option is only available when duplicate service requests come from the same RDOM. When the service requests are from different RDOMs, the requests are always loosely-coupled.

INBUFTYPE = type[:subtype]

specifies the type and subtype of the buffer. INBUFTYPE is used to enforce stronger type checking. In the DM_LOCAL_SERVICES section, the TYPE parameters are defined in reference to where the remote request originates. Refer to Managing Parameters for Buffer and Record Conversion for more information about these parameters.

INRECTYPE = type[:subtype]

specifies the type, and in some cases, the format of the reply buffer that a particular client requires. This parameter can be omitted if the local service sends a buffer that is identical in type and structure to the buffer the remote client expects. If you do not specify INRECTYPE, the type of buffer is unchanged. In the DM_LOCAL_SERVICES section, the TYPE parameters are defined in reference to where the remote request originates. Refer to Managing Parameters for Buffer and Record Conversion for more information about these parameters.

LDOM = identifier

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

OUTBUFTYPE = type[:subtype]

specifies the type, and in some cases, the format of the request buffer that a particular local service expects. This parameter can be omitted if the remote client sends a buffer that is identical in type and structure to the buffer the local service expects. If you do no specify OUTRECTYPE, the type of the buffer is unchanged. In the DM_LOCAL_SERVICES section, the TYPE parameters are defined in reference to where the remote request originates. Refer to Managing Parameters for Buffer and Record Conversion for more information about these parameters.

OUTRECTYPE = type[:subtype]

specifies the type and subtype of the buffer sent by the remote client. This parameter is used to enforce stronger type checking. In the DM_LOCAL_SERVICES section, the TYPE parameters are defined in reference to where the remote request originates. Refer to Managing Parameters for Buffer and Record Conversion for more information about these parameters.

RNAME = “string”

specifies the name of the service exported to remote domains. This name is used by the remote domains for request to this service. If this parameter is not specified, the local service name is used for the request.

See Also

Refer to Table A‑4 “DM_LOCAL_SERVICES SECTION” for more information about setting these parameters through the dmadmin utility.

DM_REMOTE_SERVICES Section

This section provides information on services imported and available on remote domains.

Format

DM_REMOTE_SERVICES entries have the following format.

service [optional parameters]

where

service is the (identifier) name used by the local Tuxedo System/Domain application for a particular remote service.

Remote services are associated with a particular remote domain.

Valid Parameters

Following is a list of valid parameters for the DM_REMOTE_SERVICES section:

 

Table 3‑7 Parameters for DM_REMOTE_SERVICES

Parameter	Required/Optional	Description
AUTOPREPARE	Optional	Indicator to automatically prepare calls from tpcall.
CONV	Optional	Indicator that remote service is conversational.
INBUFTYPE	Optional	Type and subtype of buffer sent to the remote service.
INRECTYPE	Optional	Type and format of the request buffer expected by remote service.
LDOM	Optional	Name of local domain exporting a service.
OUTBUFTYPE	Optional	Type and format of reply buffer expected by local client.
OUTRECTYPE	Optional	Type and format of reply buffer returned by remote client.
RDOM	Optional	Name of remote domain responsible for execution of service.
REM_TPSUT	Optional	TP service user title.
RNAME	Optional	Name of service exported to remote domains.
ROUTING	Optional	Routing criteria used for data-dependent routing.
TPSUT_TYPE	Optional	Type for which the remote TP service user title is to be encoded.
TRANTIME	Optional	Default time-out value in seconds for transaction automatically started for associated service.

Parameter Definitions

Following is more detailed information about the DM_REMOTE_SERVICES section parameters:

AUTOPREPARE = {N | Y}

allows a single tpcall() involved in a global transaction to this remote service to automatically prepare the call. This optimization reduces the two-phase commit process to a single step. The remote OSITP domain must support this feature. The default is N.

CONV = {Y | N}

specifies whether or not the remote service is a conversational service. Use Y to specify the remote service is a conversational service. Use N to specify the remote service is not a conversational service. The default value is N.

INBUFTYPE = type[:subtype]

specifies the type and subtype of the buffer allocated by the client. This parameter is used to enforce stronger type checking. In the DM_REMOTE_SERVICES section, the TYPE parameters are defined in reference to where the local request originates. Refer to Managing Parameters for Buffer and Record Conversion for more information about these parameters.

INRECTYPE = type[:subtype]

specifies the type, and in some cases, the format of the request buffer that a particular remote service requires. This parameter can be omitted if the local client sends a buffer that is identical in type and structure to the buffer the remote service expects. If you do not specify INRECTYPE, the type of buffer is unchanged. In the DM_REMOTE_SERVICES section, the TYPE parameters are defined in reference to where the local request originates. Refer to Managing Parameters for Buffer and Record Conversion for more information about these parameters.

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 Tuxedo System/Domain Bulletin Board. If this parameter is not specified, then all the local domains are able to accept requests to this remote service. The service request is then redirected to a remote domain of the same type (see the following definition for RDOM keyword).

OUTBUFTYPE = type[:subtype]

specifies the type, and in some cases, the format of the reply buffer that a particular local client expects. This parameter can be omitted if the remote service returns a buffer that is identical in type and structure to the buffer the local client expects. If you do no specify OUTRECTYPE, the type of the buffer is unchanged. In the DM_REMOTE_SERVICES section, the TYPE parameters are defined in reference to where the local request originates. Refer to Managing Parameters for Buffer and Record Conversion for more information about these parameters.

OUTRECTYPE = type[:subtype]

specifies the type and subtype of the buffer sent by the remote service. This parameter is used to enforce stronger type checking. In the DM_REMOTE_SERVICES section, the TYPE parameters are defined in reference to where the local request originates. Refer to Managing Parameters for Buffer and Record Conversion for more information about these parameters.

RDOM = identifier

specifies the name of the remote domain responsible for the actual execution of this service. If this parameter is not specified and a routing criteria (see the following definition for ROUTING keyword) is not specified, then the local domain assumes that any remote domain of the same type accepts this service and it selects a known domain (a domain to which a connection already exists) or remote domain from the DM_REMOTE_DOMAINS section.

REM_TPSUT = "string"

identifies the TP service user title for the remote system. Some users of OSI TP implementations require this field. It is not required for OS 2200 OLTP-TM2200, OpenTI, A Series Open/OLTP, or Oracle TMA OSI TP. If the TPSUT_TYPE value is PRINTABLESTRING, the maximum length is 60 characters, which must comply with Abstract Syntax Notation (ASN.1) type of PRINTABLESTRING. If the TPSUT_TYPE value is an INTEGER, the maximum length must fit into a LONG. The TPSUT_TYPE must be defined prior to defining the remote TPSUT.

RNAME = identifier

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

ROUTING = identifier

allows a local domain to perform data-dependent routing when more than one remote domain offers the same service. 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.

TPSUT_TYPE = {INTEGER | PRINTABLESTRING}

specifies the type of encoding to be performed on the REM_TPSUT parameter. The default type is PRINTABLESTRING. If TPSUT_TYPE is not specified, the default is used. The INTEGER and PRINTABLESTRING are ASN.1 types.

TRANTIME = integer

specifies the default time-out 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 time-out value for the machine.

See Also

Refer to Table A‑5 “DM_REMOTE_SERVICES SECTION” for more information about setting these parameters through the dmadmin utility.

DM_ROUTING Section

This section provides information for data-dependent routing of service requests using FML, VIEW, X_C_TYPE, and X_COMMON typed buffers.

Format

DM_ROUTING entries have the following format.

CRITERION_NAME required parameters

where

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

Valid Parameters

Following is a list of valid parameters for the DM_ROUTING section:

 

Table 3‑8 Parameters for DM_ROUTING

Parameter	Required/Optional	Description
BUFTYPE	Required	Types and subtypes of data buffers for which this routing entry is valid
FIELD	Required	Name of routing field
RANGES	Required	Ranges and associated remote domain names (RDOM) for routing field

Parameter Definitions

Following is more detailed information about the DM_ROUTING section parameters:

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

specifies types and subtypes of data buffers for which this routing entry is valid. The types are restricted to be either FML, VIEW, X_C_TYPE, or X_COMMON. No subtype can be specified for type FML and subtypes are required for the other types (“*” is not allowed). Duplicate type/subtype pairs cannot be specified for the same routing criterion name; more than one routing entry can have the same criterion 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.

For FML buffers, if the field value is not set 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.

FIELD = identifier

specifies the name of the routing field. It must be 30 characters or less. This field is assumed to be a field name that is identified in an FML field table (for FML buffers) or an FML view table (for VIEW, X_C_TYPE, or X_COMMON buffers). The FLDTBLDIR and FIELDTBLS environment variables are used to locate FML field tables, and the VIEWDIR and VIEWFILES environment variables are used to locate FML view tables.

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.

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 arrays, 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 arrays, 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 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, array, 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 “:”.

See Also

Refer to Table A‑6 “DM_ROUTING SECTION” for more information about setting these parameters through the dmadmin utility.

Methods for Modifying Configurations

The Oracle Tuxedo system provides three methods for modifying your TMA OSI TP configuration:

•	Oracle Administration Console

A Web-based graphical user interface (GUI) you can use to dynamically configure your application. You can display and change configuration information, determine the state of each component in the system, and obtain statistical information about items such as executed requests and queued requests.

•	Command-line utilities

Most of the functionality needed for dynamic modification is provided by two commands: dmadmin and dmconfig. dmadmin is a shell-level command with over 70 subcommands for performing various administrative tasks, including dynamic system modification. tmconfig is a shell-level command that you can use to add and modify configuration entries while your system is running.

Refer to the “Utilities Reference” section of this document for more information.

•

MIB API

A Management Information Base API that enables you to write your own programs to monitor your system and make dynamic changes to your system.

Refer to the "Dynamically Modifying an Application" section of your Oracle Tuxedo 9.1 or 10.0 documentation for ATMI Administration for more detailed information about modifying your configuration.