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:

•	Updating the Oracle Tuxedo UBBCONFIG File

•	Specifying Parameters in the GWICONFIG File

•	Defining Domain Configurations in the DMCONFIG File

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

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.

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

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.

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

 

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.

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"

 

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

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

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.

Notes:

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.

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 the Oracle Tuxedo Administrator’s Guide.

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:

 

Table 5‑1 Required GWICONFIG File 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 5‑4. 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="//beasun2"
TCP_PORT=9002
IDLE_TIME=20

*FOREIGN
RIGHTY WRAP="TPS"
TYPE="MVS"
IPADDR="//beasun2"
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.

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.

 

Table 5‑2 Parameters for 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.”

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.

 

Table 5‑3 Parameters for 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.

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.

 

Table 5‑4 Parameters for 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.
PASSWORD=”password”	Optional	" "	Specifies the password associated with the user ID for gateway-level security on the foreign system.
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.

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.

 

Table 5‑5 Parameters for 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	Specifies 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.

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.

 

Table 5‑6 Parameters for 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.

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.

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.

 

Table 5‑7 Parameters for 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 ASCII to EBCDIC conversion 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 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.”
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.

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.

 

Table 5‑8 Parameters for 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 ASCII to EBCDIC conversion 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 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.”

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.

 

Table 5‑9 Parameters for DM_ACCESS_CONTROL Section

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.

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.

 

Table 5‑10 Parameters for DM_LOCAL_SERVICES Section

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.

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.

 

Table 5‑11 Parameters for DM_REMOTE_SERVICES Section

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.

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.

 

Table 5‑12 Parameters for DM_ROUTING Section

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.

Sample DMCONFIG File

Listing 5‑16 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” section.

Listing 5‑16 Sample DMCONFIG File

#
# Copyright (c) 2008 Oracle Systems, Inc
# All Rights Reserved
#
# THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF
# Oracle Systems, Inc.
# The copyright notice above does not evidence any
# actual or intended publication of such source code.
#
#
*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"