Configuring Oracle TMA TCP Gateway

5 Configuring Oracle TMA TCP Gateway

The following configuration files must be set up prior to running Oracle Tuxedo Mainframe Adapter for TCP Gateway (hereafter referenced as TMA TCP Gateway):

UBBCONFIG
GWICONFIG
DMCONFIG

This document explains the following tasks for configuring TMA TCP Gateway:

5.1 Updating the Oracle Tuxedo UBBCONFIG File

As with any Tuxedo server, you must establish a server group for TMA TCP Gateway by adding entries for TMA TCP Gateway in the UBBCONFIG file for the local region. Specifically, you must add records to:

The GROUPS section
The SERVERS section
The SERVICES section

See the Oracle Tuxedo Administrator’s Guide for more information about the UBBCONFIG file. See UBBCONFIG(5) for more information about the UBBCONFIG file. For information about the UBBCONFIG file specific to the gateway, refer to the Updating the GROUPS Section to Establish a Server Group and Updating the SERVERS Section

Note:

Lines beginning with an asterisk (*) indicate the beginning of a specification section. Each such line contains the name of the section immediately following the *. The asterisk is required when specifying a section name.

Parent topic: Configuring Oracle TMA TCP Gateway

5.1.1 Updating the GROUPS Section to Establish a Server Group

To establish a server group for TMA TCP Gateway, you must add the following items to the GROUPS section of the Oracle Tuxedo UBBCONFIG file:

A name for the TMA TCP Gateway server group using the groupname variable
The logical machine name for the system on which TMA TCP Gateway is installed using the LMID parameter

Note:
For Windows NT, the LMID must be in uppercase
A group number for the TMA TCP Gateway server group using the GROUPNO parameter

Parent topic: Updating the Oracle Tuxedo UBBCONFIG File

5.1.1.1 Syntax

The syntax of the configuration file entry is as follows:

Listing 5‑1 Syntax for GROUPS Section of UBBCONFIG File

groupname LMID=logical_machine_identifier
GROUPNO=group_number

The variable definitions follow.

Variable	Description
`groupname`	Specifies the name you select for the TMA TCP Gateway server group.
`logical_machine_identifier`	Specifies the logical machine identifier for the system on which TMA TCP Gateway is installed.
`group_number`	Specifies the number you assign to the TMA TCP Gateway server group.

Parent topic: Updating the GROUPS Section to Establish a Server Group

5.1.1.2 Example

Here is an example of a UBBCONFIG entry that establishes a server group.

Listing 5‑2 Establishing a Server Group

NODE2GATE LMID=NODE2
GROUPNO=1

Parent topic: Updating the GROUPS Section to Establish a Server Group

5.1.2 Updating the SERVERS Section

This section explains how to specify TMA TCP Gateway servers in the Oracle Tuxedo configuration.

The TMA TCP Gateway product provides the gateway you need to list in the SERVERS section of the Oracle Tuxedo UBBCONFIG configuration file.

For each TMA TCP Gateway server group, you can specify one gateway. There must also be entries for domain administration (DMADM) and gateway administration (GWADM) servers.

Parent topic: Updating the Oracle Tuxedo UBBCONFIG File

5.1.2.1 Syntax

The syntax of each configuration file entry is as follows.

Listing 5‑3 Syntax for SERVER Section of UBBCONFIG File

DMADM SVRGRP=groupname SRVID=integer
GWADM SVRGRP=groupname SRVID=integer
GWIDOMAIN SVRGRP=groupname SRVID=integer
CLOPT="-A -- -r -p <protocol>"

The following table describes the parts of the syntax.

Part	Description
`GWIDOMAIN`	Specifies the name of the TMA TCP Gateway.
`DMADM`	Specifies the name of the Oracle Tuxedo supplied domain administration server.
`GWADM`	Specifies the name of the Oracle Tuxedo supplied gateway administration server.
`groupname`	Specifies the name you select for the TMA TCP Gateway server group. This is the group with which the server in question is associated.
`integer`	Specifies the number you assign to the TMA TCP Gateway server.
`CLOPT="-A -- -r -p <protocol>"`	`-A` specifies the command line option string that is used to initialize TMA TCP Gateway when it is invoked. This is the default for Oracle Tuxedo server processes. `-r` after the double dashes specifies that the server should record, in its standard error file, a log of services performed. This log may be analyzed by the `txrpt` command. When using this option, ensure that the `ULOGDEG` variable is not set to “`y`”. `-p` after the double dashes specified the network protocol used between TMA TCP Gateway and TMA TCP for CICS or TMA TCP for IMS. The supported values are: TCP SSL SSL_ONE_WAY.

For more information about Oracle Tuxedo servers and related configuration parameters, see Oracle Tuxedo Administrator’s Guide documentation.

Parent topic: Updating the SERVERS Section

5.1.2.2 Using the Request Logging Option

Output from the -r command line option should be capable of being processed by txrpt command. The txrpt command analyzes the standard error output of a Oracle Tuxedo server and provides a summary of service processing time within the server. The report shows the number of times each service was dispatched and the average amount of time it took for each service to process a request during the specified period. txrpt takes its input from the standard input or from a standard error file redirected as input.

Note:

The process of gathering statistics creates overhead. Use this option selectively.

The -r option applies to servers but does not apply to GWIDOMAIN because it is a Gateway.

Parent topic: Updating the SERVERS Section

5.1.2.3 Other Options for Configuring Servers

As with other Tuxedo servers, you can use some of Oracle Tuxedo system server boot options with TMA TCP Gateway servers. Boot options must be specified with CLOPT parameter (before the CLOPT double-dash separator).

Note:

Because TMA TCP Gateway dynamically advertises services that are listed in its initialization file, you should not advertise services by using the -s option.

For more information about these and other boot options, see servopts(5) in Oracle Tuxedo Administrator’s Guide.

Parent topic: Updating the SERVERS Section

5.2 Specifying Parameters in the GWICONFIG File

The GWICONFIG file is the mechanism that system administrators use to configure TMA TCP Gateway. The particular file the gateway uses is determined by the environment variable GWICONFIG. The configuration file is similar to the Tuxedo Transaction Manager UBBCONFIG file, both in structure and in composition. This makes it possible for experienced Oracle Tuxedo administrators to configure TMA TCP Gateway without extensive training.

Note:

GWICONFIG is a generic filename. You are free to choose other filenames just as with the Tuxedo UBBCONFIG file and DMCONFIG file. Be sure that the name of the GWICONFIG file is specified in the GWICONFIG environment variable. Also, the GWICONFIG file should be saved to the application directory.

The GWICONFIG file is divided into the following required sections:

Section	Description
`GLOBAL`	Describes certain general characteristics of all TMA TCP Gateways.
`NATIVE`	Describes all native systems. Use the gateway name, specified in the `GWI_GWNAME` environment variable, to distinguish different gateways in the same configuration file.
`FOREIGN`	Describes all foreign systems.
`LOCAL_SERVICES`	Describes local services that are accessible in the Oracle Tuxedo domain through the TMA TCP Gateway. Each local service is linked to a native system using the `NATIVE` parameter. For each local service, TMA TCP Gateway uses the TCP port number and IP address of the corresponding native system to establish a TCP listening endpoint.
`REMOTE_SERVICES`	Describes remote services that are accessible from the Oracle Tuxedo domain. Each remote service describes a TCP service on a foreign system. For each remote service, the `FOREIGN` parameter defines the name of the foreign system. TMA TCP Gateway uses the TCP port number and IP address of the foreign system to connect to the remote TCP service.

WARNING: The GWICONFIG file must contain the required sections in the order shown in Listing below. Each section requires the asterisk (*) in the name.

Listing 5‑4 Sample GWICONFIG File

*GLOBAL
NWDEVICE="/dev/tcp"
CONNECT_TIME=20
OUTREQ_TIME=20
LATENCY=-2
SECURE=N
MULTIPLEX=2
DFLTWRAP="TPS"
DFLTTYPE="MVS"
*NATIVE
LOCAL IPADDR="//hostname1"
TCP_PORT=9002
IDLE_TIME=20

*FOREIGN
RIGHTY WRAP="TPS"
TYPE="MVS"
IPADDR="//hostname2"
TCP_PORT=9004
MULTIPLEX=2
IDLE_TIME=30
RMTACCT="zeke"
PASSWORD="maple"

MIKE WRAP="TPS"
TYPE="MVS"
IPADDR="//dalvs3"
TCP_PORT=9001
MULTIPLEX=6

*LOCAL_SERVICES
TUXTOUPPER

ECHO

*REMOTE_SERVICES
TUXTOLOWER
OUTREQ_TIME=20

BEASVR07
OUTRECTYPE="VIEW:weird"

TST1V

Note:

Changes to the GWCONFIG file must be made when upgrading from previous releases of TMA TCP. See the Oracle Tuxedo Mainframe Adapter for TCP Release Notes for specific upgrade information.

Parent topic: Configuring Oracle TMA TCP Gateway

5.2.1 Defining the GLOBAL Section of the GWICONFIG File

The following sections describe parameters that are associated with the GLOBAL section of the GWICONFIG file. These parameters describe global characteristics for the gateway.

The format of the GLOBAL section of the GWICONFIG file is shown in the following listing.

Listing 5‑5 Syntax for GLOBAL Section of GWICONFIG File

[ # A comment (from "#" to end of line)]

*GLOBAL
[ NWDEVICE=TCP_device ]
[ CONNECT_TIME=n]
[ IDLE_TIME=n]
[ OUTREQ_TIME=n]
[ LATENCY=n|1 ]
[ SECURE=Y|N ]
[ MULTIPLEX=n|1 ]
[ DFLTWRAP=wrapper name ]
[ DFLTTYPE=translation type ]

The following table describes the parameters that are set in the GLOBAL section.

Parameter	Required/Optional	Default	Description
`NWDEVICE=`" `TCP_device` "	Optional	`“/dev/tcp”`	Specifies the network device to be used for communication with remote gateways.
`CONNECT_TIME`= `n` `seconds`	Optional	No timeout	Specifies the number of seconds the gateway waits to establish a connection.
`IDLE_TIME=` `n seconds`	Optional	No idle timeout	Specifies the number of seconds a connection can be idle before timing out.
`OUTREQ_TIME=` `n` `seconds`	Optional	None	Specifies the default timeout value, in seconds, for requests sent to foreign gateways.
`LATENCY=` `n` `seconds`	Optional	`1`	Specifies the number of seconds to be deducted from the timeout value sent to a remote gateway for a Tuxedo client request. This increases the likelihood that the remote gateway detects a timeout before the local gateway.
`SECURE=Y \| N`	Optional	`N`	Specifies whether the TMA TCP Gateway supplies user information to local and remote services. If `SECURE=Y`, then the TMA TCP Gateway supplies user information to remote services and applies remote user information to local services using the `appkey`. If `SECURE=N`, then the TMA TCP Gateway does not supply user information to remote services and does not apply remote user information to local services using the `appkey`. If `SECURE=N` and the Tuxedo domain is set with `SECURITY=ACL` in the `UBBCONFIG` file, a request to a local service can fail even if ACLs are in place.
`MULTIPLEX=` `n`	Optional	`1`	Specifies the maximum number of outstanding requests per connection that the local gateway can support.
`DFLTWRAP=` `wrapper name`	Optional	`TPS`	Specifies the name of the default wrapping library to use for wrapping and unwrapping messages for machines without a `FOREIGN` section or without a `WRAP` parameter in the `FOREIGN` section. A corresponding wrapper object `WRAP<` `wrapper name` `>` must exist. The wrapper name `TPS` is used in most cases. Specify `TPSD` if data area security is used. For more information about data area security, refer to Setting Up Security for Oracle TMA TCP Gateway
`DFLTTYPE=system type`	Optional	`DFLTYPE=MVS`	Specifies the default foreign system type for encoding and decoding message buffers. If you specify `TYPE` in the `FOREIGN` section, that `TYPE` definition overrides this default value. For normal C-to-COBOL encoding, specify `DFLTYPE="MVSC"` to enable COBOL data encoding.For more information about `DFLTYPE` values MVS and MVSC, refer to Configuring Oracle TMA TCP Gateway for Data Mapping

Parent topic: Specifying Parameters in the GWICONFIG File

5.2.2 Defining the NATIVE Section of the GWICONFIG File

The following sections describe parameters that are associated with the NATIVE section of the GWICONFIG file. These parameters are specific to the local system. You can specify multiple native systems in the same configuration file allowing multiple gateway processes to access the same configuration file. This makes a single repository of connectivity services. The link between the gateway process and the native system entry is made through the GWINAME environment variable.

The format of the NATIVE section of the GWICONFIG file is illustrated in the following listing.

Listing 5‑6 Syntax for NATIVE Section of GWICONFIG File

[ # A comment (from "#" to end of line)]
*NATIVE
<GATEWAY_NAME>
[ IPADDR=ip_address ]
[ TCP_PORT=port number ]
[ IDLE_TIME=n]
[ MULTIPLEX=n]
[ POLL_TIME=n]
[ MAXCONNECT=n]

The following table describes for each local system that are specified in the NATIVE section.

Parameter	Required/Optional	Default	Description
< `GATEWAY_NAME`>	Required	None	This parameter is a 1-78 alphanumeric character string that represents the gateway identification passed in the `GWINAME` environment variable.The `GATEWAY_NAME` parameter must match an entry in the `DM_LOCAL_DOMAINS` section of the `DMCONFIG` file.
`IPADDR=` `ip_address`	Optional	IP address of the local host machine	Specifies the IP address for the local system. The `IPADDR` can be in the hexadecimal format `0xaaaaaaaa`, the dotted decimal format `//#.#.#.#`, or the DNS format //`host[.domainname]`.
`TCP_PORT=` `port number`	Optional	None	Specifies the local port number used for listening for services. This parameter is optional if no local services are advertised. If you do not specify TCP_PORT, a listener port is not created.
`IDLE_TIME=` `n`	Optional	No idle time value	Specifies the number of seconds a connection can remain idle before being disconnected.
`MULTIPLEX=` `n`	Optional	1	Specifies the number of outstanding requests per connection that the local gateway can support.
`POLL_TIME=` `n`	Optional	250,000 micro seconds	Specifies the polling timeout (in microseconds) to be used in polling for Tuxedo messages. The range of values for this parameter is 100,000-10,000,000.
`MAXCONNECT=` `n`	Optional	No maximum	Specifies the number of connections into the gateway from remote hosts. If the remote system attempts more connections than this parameter specifies, the remote systems are disconnected.

Parent topic: Specifying Parameters in the GWICONFIG File

5.2.3 Defining the FOREIGN Section of the GWICONFIG File

The FOREIGN section of the GWICONFIG file contains parameters that collectively describe foreign systems.

The format of the FOREIGN section of the GWICONFIG file is illustrated in the following listing.

Listing 5‑7 Syntax for FOREIGN Section of GWICONFIG File

[ # A comment (from "#" to end of line)]
*FOREIGN
<SYSTEM_NAME>
IPADDR=ip_address
[TYPE=system_type]
[WRAP=wrapper name]
[TCP_PORT=port number]
[MULTIPLEX=n sessions]
[IDLE_TIME=n seconds]
[RMTACCT=”userid”]
[PASSWORD=”password”]
[CICS=Y | N]
[CICSHAND=<name>]
[MAXCONNECT=n]
[CONNSYNC=Y|N]
[CONNECT_TIME=n]
[CICSDATA="string"]

The following table describes the parameters that are set for the each foreign system that you specify in the FOREIGN section.

The following table describes the parameters that are specified in the FOREIGN section.

Parameter	Required/Optional	Default	Description
< `SYSTEM_NAME` >	Required	None	This parameter is a 1-78 alpha-numeric character string that represents the foreign system name. The `SYSTEM_NAME` parameter must match an entry in the `DM_REMOTE_DOMAINS` section of the `DMCONFIG` file.
`IPADDR=` `ip_address`	Required	None	Specifies the IP address for the remote system. The `IPADDR` can be in the hexadecimal format `0xaaaaaaaa`, the dotted decimal format `//#.#.#.#`, or the DNS format //`host[.domainname]`.
`TYPE=` `system type`	Optional	`“MVS”`	Specifies the foreign system type for encoding and decoding the Tuxedo buffers (application data). `TYPE` values of MVS and MVSC support C-to-COBOL or COBOL data encoding. If you do not specify `TYPE`, the value in `DFLTYPE` in the `GLOBAL` section is used. For more information about MVS and MVSC `TYPE` values, refer to Configuring Oracle TMA TCP Gateway for Data Mapping.
`WRAP=` `wrapper name`	Optional	`“TPS”`	Specifies the name of the wrapping entry to use for wrapping and unwrapping messages for this host. A corresponding wrapper object `wrap<wrapper name>` must exist. The wrapper name `TPS` is used in most cases. Specify `TPSD` if data area security is used. For more information about data area security, refer to Setting Up Security for Oracle TMA TCP Gateway. If `WRAP` is not specified in the `FOREIGN` section, the value for `DFLTWRAP` in the `GLOBAL` section is used.
`TCP_PORT=` `port number`	Optional	No port number	Specifies the port number of the foreign gateway. This parameter is optional if remote services are not defined for this foreign system.
`MULTIPLEX=` `n` sessions per connection	Optional	1 session per connection	Specifies the maximum number of sessions per connection that the local gateway can support.
`IDLE_TIME=` `n` seconds	Optional	No idle timeout	Specifies the number of seconds a connection can remain idle before being disconnected.
`CICS=Y \| N`	Optional	N	Specifies whether to send control information to the IBM TCP/IP listener for use with the TMA TCP for CICS gateway. If `CICS=Y` and you are not using IBM TCP/IP or your remote gateway is not TMA TCP for CICS, the transaction does not process correctly.
`CICSHAND=` `<name>`	Optional	BEAH	Specifies the name of the handler transaction to be passed to the IBM TCP/IP listener for use with TMA TCP for CICS.
`RMTACCT=` `”userid”`	Optional	""	Specifies the user ID for gateway-level security on the foreign system. The user ID for connection validation is obsolete.
`PASSWORD=` `”password”`	Optional	""	Specifies the password associated with the user ID for gateway-level security on the foreign system. The password for connection validation is obsolete.
`MAXCONNECT=` `n`	Optional	No limit	Specifies the maximum number of connections to the specified host.
`CONNSYNC=Y\|N`	Optional	`N`	Specifies whether to force the gateway to establish connections to the specified host in a synchronous manner.
`CONNECT_TIME=` `n`	Optional	Value from `GLOBAL` section	Specifies the number of seconds the gateway waits to establish a connection. If you do not specify this parameter, the value of `CONNECT_TIME` in the `GLOBAL` section is used.
`CICSDATA=` `”string”`	Optional	""	Specifies a string to be passed to the IBM TCP/IP listener for use with the TMA TCP for CICS gateway.

Parent topic: Specifying Parameters in the GWICONFIG File

5.2.4 Defining the LOCAL_SERVICES Section of the GWICONFIG File

The LOCAL_SERVICES section of the GWICONFIG file contains parameters for each local service specified in the DMCONFIG file. Each service entry name matches the remote name of the service in the DM_LOCAL_SERVICES section.

The format of the LOCAL_SERVICES section of the GWICONFIG file is illustrated in the following listing.

Listing 5‑8 Syntax for LOCAL_SERVICES Section of GWICONFIG File

[ # A comment (from "#" to end of line)]
*LOCAL_SERVICES
<SERVICE_NAME>
[INRECTYPE=”foreign_incoming_buffer_type”]
[OUTRECTYPE=”foreign_outgoing_buffer_type”]
[SECURE=Y | N]
[CONV=Y | N]

The following section describes the parameters set for each service you specify in the LOCAL_SERVICES section.

Parameter	Required/Optional	Default	Description
< `SERVICE_NAME` >	Required	None	This parameter is a 1-78 alphanumeric character string that represents the local service name that matches the service name value in the `DM_LOCAL_SERVICES` section of the `DMCONFIG` file.
`INRECTYPE`= `”foreign_incoming_buffer_type”`	Optional	None	`S`pecifies the foreign buffer type for replies to remote clients. If you do not specify INRECTYPE, the default is no type. In this case, the type of buffer is unchanged.
`OUTRECTYPE`= `”foreign_outgoing_buffer_type”`	Optional	Match the `INRECTYPE` value	Specifies the foreign buffer type for requests from remote clients. If you do not specify `OUTRECTYPE`, the default is to match the `INRECTYPE` value.
`SECURE=Y \| N`	Optional	`N`	Specifies whether the TMA TCP Gateway applies remote user information to local services. If `SECURE=Y`, then the TMA TCP Gateway applies remote user information to local services using the `appkey`. If `SECURE=N`, then the TMA TCP Gateway does not apply remote user information to local services using the `appkey`. If `SECURE=N` and the Tuxedo domain is set with `SECURITY=ACL` in the `UBBCONFIG` file, a request to a local Tuxedo service can fail even if ACLs are in place.
`CONV=Y \| N`	Optional	`N`	Specifies whether service is conversational. Conversational mode is not currently supported, so `Y` returns an error message and the gateway does not start.

Parent topic: Specifying Parameters in the GWICONFIG File

5.2.5 Defining the REMOTE_SERVICES Section of the GWICONFIG File

The REMOTE_SERVICES section of the GWICONFIG file contains parameters for each remote service specified in the DMCONFIG file. Each service entry name matches the remote name of the service in the DM_REMOTE_SERVICES section.

The format of the REMOTE_SERVICES section of the GWICONFIG file is illustrated in the following listing.

Listing 5‑9 Syntax for REMOTE_SERVICES Section of GWICONFIG File

[ # A comment (from "#" to end of line)]
*REMOTE_SERVICES
<SERVICE_NAME>
[INRECTYPE=”foreign_outgoing_buffer_type”]
[OUTRECTYPE=”foreign_incoming_buffer_type”]
[OUTREQ_TIME=n]
[SECURE=Y | N]
[CONV=Y | N]

The following table describes the parameters set for each service you specify in the REMOTE_SERVICES section.

Parameter	Required/Optional	Default	Description
< `SERVICE_NAME` >	Required	-	This parameter is a 1-78 alphanumeric character string that represents the local service name that matches the `RNAME` value in the `DM_REMOTE_SERVICES` section of the `DMCONFIG` file. If `RNAME` is not specified, this name matches the Tuxedo service name.
`INRECTYPE`= `”foreign_outgoing_buffer_type”`	Optional	None	Specifies the foreign buffer type for requests to remote servers. If you do not specify `INRECTYPE`, the default is no type. In this case, the type of buffer is changed.
`OUTRECTYPE`= `”foreign_incoming_buffer_type”`	Optional	Match the `OUTBUFTYPE` value	Specifies the foreign buffer type for replies from remote servers. If you do not specify `OUTRECTYPE`, the default is no type. In this case, the type of buffer is unchanged.
`OUTREQ_TIME`= `n`	Optional	Value from `GLOBAL` section	Specifies the timeout value, in seconds, for requests sent to this service. If you do not specify this parameter, the value for `OUTREQ_TIME` in the `GLOBAL` section is used. If `OUTREQ_TIME` is not specified in this section or the `GLOBAL` section, an error message occurs.
`SECURE=Y \| N`	Optional	`N`	Specifies whether the TMA TCP Gateway supplies local user information to remote services. If `SECURE=Y`, then the TMA TCP Gateway supplies user information to remote services. If `SECURE=N`, then the TMA TCP Gateway does not supply user information to remote services.
`CONV=Y \| N`	Optional	`N`	Specifies whether the service is conversational. Conversational mode is not currently supported, so `Y` returns an error message and the gateway does not start.

Parent topic: Specifying Parameters in the GWICONFIG File

5.3 Defining Domain Configurations in the DMCONFIG File

The domain configuration file (DMCONFIG) is made up of 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 *. The asterisk is required when specifying a section name. Allowable section names are: DM_LOCAL_DOMAINS, DM_REMOTE_DOMAINS, DM_LOCAL_SERVICES, DM_REMOTE_SERVICES, DM_ROUTING, and DM_ACCESS_CONTROL.

Note:

The DM_LOCAL_DOMAINS section must precede the DM_REMOTE_DOMAINS

The following paragraphs describe the significant parameters within specific sections of the DMCONFIG file that define new gateway configurations.

Parent topic: Configuring Oracle TMA TCP Gateway

5.3.1 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 format of the DM_LOCAL_DOMAINS section of the DMCONFIG file is illustrated in the following listing.

Listing 5‑10 Syntax for DM_LOCAL_DOMAINS Section of DMCONFIG File

LDOM required parameters [optional parameters]

LDOM is an identifier value used to name each local domain and must be unique within a particular configuration. In the description of the DM_LOCAL_SERVICES section, LDOM is the identifier that connects local services with a particular gateway group.

The following table describes the parameters that are set in the DM_LOCAL_SERVICES section.

Parameter	Required/Optional	Default	Description
`GWGRP` = identifier	Required	None	Specifies the name of the gateway server group (the name provided in the `TUXCONFIG` file) representing this local domain. A one-to-one relationship must exist between a `DOMAINID` and the name of the gateway server group; each `GWGRP` must have its own unique `DOMAINID`.
`TYPE` = identifier	Required	None	Is used for grouping local domain into classes. `TYPE` can be set to `TDOMAIN` or any other domain gateway type. The `TDOMAIN` value indicates that this local domain can only communicate with another Tuxedo System/Domain. For use with TMA TCP Gateway, specify `TYPE=IDOMAIN`. Domain types must be defined in the `$TUXDIR/udataobj/DMTYPE` file.
`DOMAINID` = string	Required	None	Is used to identify the local domain. `DOMAINID` must be unique across both local and remote domains. The value of string can be a sequence of characters (for example, "`BA.CENTRAL01`"), or a sequence of hexadecimal digits preceded by "0x" (for example, "`0x0002FF98C0000B9D6`"). `DOMAINID` must be 32 octets or fewer in length. If the value is a string, it must be 31 characters or fewer.
`AUDITLOG` = string	Optional	None	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	Optional	The value of `BLOCKTIME` parameter specified in the `TUXCONFIG` file	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. 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.
`CODEPAGE` = table-identifier	Optional	None	Specifies the mapping to use with remote hosts that are not specified in the `DMCONFIG` file. `CODEPAGE` designates a bidirectional translation table for SBCS (ASCII to EBCDIC) conversion or designates multibyte character set (MBCS) encoding or decoding between a local Tuxedo application and a remote mainframe application. The table-identifier describes a file containing a translation table. The name of the file, located in the `$TUXDIR/udatajobj/codepage` directory, is a composite of the code page numbers used for the translation. This parameter specifies the mapping to use with remote hosts that are not specified in the `DMCONFIG` file. For SBCS (ASCII to EBCDIC), for example, specifying `CODEPAGE=00819x00297` designates the translation table for converting ASCII CP-00819 characters to French EBCDIC CP-00297 characters, and vice versa. The translation tables can be modified. For complete character listings, refer to “Code Page Translation Tables.” For MBCS, for example, specifying `CODEPAGE="UTF-8:ibm-1388"` designates MBCS encoding or decoding for converting UTF-8 characters to Simplified Chinese Mixed EBCDIC ibm-1388 characters, and vice versa. For more information, see Using Multibyte Character Set (MBCS) Translations.
`DMTLOGDEV` = string	Optional	None	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` = identifier	Optional	“`DMTLOG`”	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. The name must be 30 characters or less.
`DMTLOGSIZE` = numeric	Optional	100 pages	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.
`MAXDATALEN` = numeric	Optional	None	Specifies a maximum amount of data (in bytes) that can be sent to or from any services advertised by this local domain. There is no limit if this parameter is not specified.
`MAXRDOM` = numeric	Optional	None	Specifies the maximum number of connections (or dialogs if the domain is of type OSITP) allowed per gateway. There is no limit if this parameter is not specified.
`MAXRDTRAN` = numeric	Optional	16	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.
`MAXTRAN` = numeric	Optional	The value of `MAXGTT`	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`.
`MAXSENDLEN` = numeric	Optional	None	Specifies the maximum length (in bytes) of messages sent or received by this local domain. If this parameter is set, all messages sent or received are broken up into packets of no more than `MAXSENDLEN` bytes. There is no limit if this parameter is not specified.

Parent topic: Defining Domain Configurations in the DMCONFIG File

5.3.2 DM_REMOTE_DOMAINS Section

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

The format of the DM_REMOTE_DOMAINS section of the DMCONFIG file is illustrated in the following listing.

Listing 5‑11 Syntax for DM_REMOTE_DOMAINS Section of DMCONFIG


            RDOM required parameters [optional
            parameters]

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

The following table describes the parameters that are set in the DM_REMOTE_DOMAINS section.

Parameter	Required/Optional	Default	Description
`TYPE` = identifier	Required	None	Is used for grouping remote domain into classes. `TYPE` can be set to `TDOMAIN` or any other domain gateway type. The `TDOMAIN` value indicates that this remote domain can only communicate with another Tuxedo System/Domain. The `OSITP` value indicates that this remote domain communicates with another TP domain via the OSI-TP protocol. For use with TMA TCP Gateway, specify `TYPE=IDOMAIN`.
`DOMAINID` = string	Required	None	Is used to identify 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".
`CODEPAGE` = table-identifier	Optional	None	Is used to designate a bidirectional translation table for SBCS (ASCII to EBCDIC) conversion or designate multibyte character set (MBCS) encoding or decoding between a local Tuxedo application and a remote mainframe application. The table-identifier describes a file containing a translation table. The name of the file, located in the `$TUXDIR/udatajobj/codepage` directory, is a composite of the code page numbers used for the translation. For SBCS (ASCII to EBCDIC), for example, specifying `CODEPAGE=00819x00297` designates the translation table for converting ASCII CP-00819 characters to French EBCDIC CP-00297 characters, and vice versa. The translation tables can be modified. For complete character listings, refer to “Code Page Translation Tables.” For MBCS, for example, specifying `CODEPAGE="UTF-8:ibm-1388"` designates MBCS encoding or decoding for converting UTF-8 characters to Simplified Chinese Mixed EBCDIC ibm-1388 characters, and vice versa. For more information, see Using Multibyte Character Set (MBCS) Translations.

Parent topic: Defining Domain Configurations in the DMCONFIG File

5.3.3 DM_ACCESS_CONTROL Section

This section is optional in the DMCONFIG file and specifies the access control lists used by local domain.

The format of the DM_ACCESS_CONTROL section of the DMCONFIG file is illustrated in the following listing.

Listing 5‑12 Syntax for DM_ACCESS_CONTROL Section of DMCONFIG

ACL_NAME required parameters

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

Parameter	Required/Optional	Default	Description
`ACLIST` = identifier [,identifier]	Required	None	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.

Parent topic: Defining Domain Configurations in the DMCONFIG File

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

The format of the DM_LOCAL_SERVICES section of the DMCONFIG file is illustrated in the following listing.

Listing 5‑13 Syntax for DM_LOCAL_SERVICES Section of DMCONFIG File

service [optional parameters]

service is the local name (identifier) 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.

Parameter	Required/Optional	Default	Description
`ACL` = identifier	Optional	None	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.
`LDOM` = identifier	Optional	None	Specifies the name identifying the local domain exporting this service. If this keyword is not specified, then all the local domains defined in the `DM_LOCAL_DOMAINS` section accept requests to this local service.
`RNAME` = string	Optional	The service name in the `GWICONFIG`	Specifies the name exported to remote domains. The remote domains use this name for request to this service. If this parameter is not specified, the local service name is supposed to be the name used by any remote domain. For TMA TCP, this should match the service name in the `GWICONFIG`.
`INBUFTYPE= ”type:subtype \| FML:servicename”`	Optional	None	Specifies the Tuxedo buffer type for replies from local servers. To use an alternate data mapping product, specify FML as the buffer type (regardless of the actual Tuxedo buffer type being passed) and the encoding service name as the subtype. Because the gateway does not do the encoding, the FML buffer type in the `DMCONFIG` file is a flag for alternate data mapping only. The Tuxedo server and the alternate data mapping product should be configured with the actual Tuxedo buffer type.
`OUTBUFTYPE= ”type:subtype \| FML:servicename”`	Optional	None	Specifies the Tuxedo buffer type for requests to local servers. To use an alternate data mapping product, specify FML as the buffer type (regardless of the actual Tuxedo buffer type being passed) and the decoding service name as the subtype. Because the gateway does not do the decoding, the FML buffer type in the `DMCONFIG` file is a flag for alternate data mapping only. The Tuxedo server and the alternate data mapping product should be configured with the actual Tuxedo buffer type.

Parent topic: Defining Domain Configurations in the DMCONFIG File

5.3.5 DM_REMOTE_SERVICES Section

This section provides information on services “imported” and available on remote domains. The format of the DM_REMOTE_SERVICES section of the DMCONFIG file is illustrated in the following listing.

Listing 5‑14 Syntax for DM_REMOTE_SERVICES Section of DMCONFIG

service [optional parameters]

service is the name (identifier) used by the local Tuxedo System/Domain application for a particular remote service. Remote services are associated with a particular remote domain.

Parameter	Required/Optional	Default	Description
`CONV = {Y \| N}`	Optional	N	Specifies whether 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.
`LDOM` = identifier	Optional	None	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 redirected to a remote domain of the same type (see the following definition for `RDOM` keyword).
`RDOM` = identifier	Optional	None	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.
`RNAME` = string	Optional	The service name in the `GWICONFIG`	Specifies the actual service name expected by the remote domain. If this parameter is not specified, the remote service name is the same as the name specified in service. For TMA TCP, this name should match the service name in the `GWICONFIG` file.
`ROUTING` = identifier	Optional	None	When more than one remote domain offers the same service, a local domain can perform data-dependent routing if this optional parameter is specified. The identifier specifies the name of the routing criteria used for this data-dependent routing. If not specified, data-dependent routing is not done for this service. `identifier` must be 15 characters or less in length. If multiple entries exist for the same service name but with different `RDOM` parameters, the `ROUTING` parameter should be the same for all of these entries.
`TRANTIME` = integer	Optional	30 seconds	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. A value of 0 implies the maximum time-out value for the machine.
`INBUFTYPE=”type: subtype \| FML: servicename”`	Optional	None	Specifies the Tuxedo buffer type for requests from local clients. To use an alternate data mapping product, specify FML as the buffer type (regardless of the actual Tuxedo buffer type being passed) and the encoding service name as the subtype. Because the gateway does not do the encoding, the FML buffer type in the `DMCONFIG` file is a flag for alternate data mapping only. The Tuxedo application and the alternate data mapping product should be configured with the actual Tuxedo buffer type.
`OUTBUFTYPE=”type: subtype \| FML:servicename”`	Optional	None	Specifies the Tuxedo buffer type for replies to local clients To use an alternate data mapping product, specify FML as the buffer type (regardless of the actual Tuxedo buffer type being passed) and the decoding service name as the subtype. Because the gateway does not do the decoding, the FML buffer type in the `DMCONFIG` file is a flag for alternate data mapping only. The Tuxedo application and the alternate data mapping product should be configured with the actual Tuxedo buffer type.

Parent topic: Defining Domain Configurations in the DMCONFIG File

5.3.6 DM_ROUTING Section

This section is optional in the DMCONFIG file and provides information for data-dependent routing of service requests using FML, VIEW, X_C_TYPE, and X_COMMON typed buffers.

The format of the DM_ROUTING section of the DMCONFIG file is illustrated in the following listing.

Listing 5‑15 Syntax for DM_ROUTING Section of DMCONFIG File

CRITERION_NAME required parameters

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.

Parameter	Required/Optional	Default	Description
`FIELD` = identifier	Required	None	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	Required	None	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. A `RDOM` value of ‘‘’’ indicates that the request can go to any remote domain known by the gateway group. Within a range/`RDOM` pair, the range is separated from the `RDOM` by a ‘‘:’’.
`BUFTYPE` = ~type1[:subtype1[,subtype2 . . . ]][;type2[:subtype3[, . . . ]]] . . .~	Required	None	Is a list of 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. If multiple buffer types are specified for a single routing entry, the data types of the routing field for each buffer type must be the same. If the field value is not set (for FML buffers), or does not match any specific range and a wildcard range has not been specified, an error is returned to the application process that requested the execution of the remote service.

Parent topic: Defining Domain Configurations in the DMCONFIG File

5.3.7 Sample DMCONFIG File

The following listing is a sample DMCONFIG file and must be set up prior to running the TMA TCP Gateway product. For a sample DMCONFIG file that uses alternate data mapping tools, refer to the “Configuring Oracle TMA TCP Gateway for Data Mapping

Listing 5‑16 Sample DMCONFIG File

#
# Copyright (c) 2023 Oracle Systems, Inc
# All Rights Reserved

*DM_LOCAL_DOMAINS
LOCAL GWGRP=GROUP
TYPE=IDOMAIN
DOMAINID="LOCAL"

#
*DM_REMOTE_DOMAINS
REMOTE TYPE=IDOMAIN
DOMAINID="REMOTE"

#
*DM_LOCAL_SERVICES
ECHOX RNAME="ZECHOSV4"
TOLOWER RNAME="TUXTOLOWER"
INBUFTYPE=string
OUTBUFTYPE=string

#
*DM_REMOTE_SERVICES
TOUPPER RDOM=REMOTE
LDOM=LOCAL
RNAME="TUXTOUPPER"


ECHOFAR RDOM=REMOTE
LDOM=LOCAL
RNAME="BEASVR07"
INBUFTYPE="VIEW:myview"
OUTBUFTYPE="FML"

NORMAL RDOM=REMOTE
LDOM=LOCAL
RNAME="TST1V"

Parent topic: Defining Domain Configurations in the DMCONFIG File