		BEA eLink TCP for TUXEDO 3.1 Information Center
		HOME \| SEARCH \| CONTACT \| PDF FILES \| WHAT'S NEW
		TABLE OF CONTENTS \| PREVIOUS TOPIC \| NEXT TOPIC \| INDEX

Configuring BEA eLink TCP for TUXEDO

The following configuration files must be set up prior to running BEA eLink for Mainframe TCP for TUXEDO (hereafter referenced as eLink TCP for TUXEDO):

UBBCONFIG
GWICONFIG
DMCONFIG

This document explains the following tasks for configuring eLink TCP for TUXEDO:

Updating the BEA TUXEDO UBBCONFIG File

As with any TUXEDO server, you must establish a server group for eLink TCP for TUXEDO by adding entries for eLink TCP for TUXEDO 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 BEA TUXEDO Administrator's Guide for more information about the UBBCONFIG file. For information about the UBBCONFIG file specific to the gateway, refer to "Updating the GROUPS Section to Establish a Server Group," and "Updating the SERVERS Section." For advertising services for alternate data mapping, refer to "Updating the SERVICES 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.

Updating the GROUPS Section to Establish a Server Group

To establish a server group for eLink TCP for TUXEDO, you must add the following items to the GROUPS section of the BEA TUXEDO UBBCONFIG file:

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

Note: For Windows NT, the LMID must be in uppercase
A group number for the eLink TCP for TUXEDO 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 eLink TCP for TUXEDO server group.
`logical_machine_identifier`	Specifies the logical machine identifier for the system on which eLink TCP for TUXEDO is installed.
`group_number`	Specifies the number you assign to the eLink TCP for TUXEDO 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 eLink TCP for TUXEDO servers in the BEA TUXEDO configuration.

The eLink TCP for TUXEDO product provides the gateway you need to list in the SERVERS section of the BEA TUXEDO UBBCONFIG configuration file.

For each eLink TCP for TUXEDO 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 -- -e<type>"

The following table describes the parts of the syntax.


Part	Description
`GWIDOMAIN`	Specifies the name of the eLink TCP for TUXEDO gateway.
`DMADM`	Specifies the name of the BEA TUXEDO supplied domain administration server.
`GWADM`	Specifies the name of the BEA TUXEDO supplied gateway administration server.
`groupname`	Specifies the name you select for the eLink TCP for TUXEDO server group. This is the group with which the server in question is associated.
`integer`	Specifies the number you assign to the eLink TCP for TUXEDO server.
`CLOPT="-A -- -e<type> "`	`-A` specifies the command line option string that is used to initialize eLink TCP for TUXEDO when it is invoked. This is the default for BEA TUXEDO server processes. `-e<type>` after the double dashes specifies the alternate data mapping product to use for data conversion. The only valid type value is `MERC`. This option must be entered to the right of the double dashes (--) as a gateway option.

For more information about BEA TUXEDO servers and related configuration parameters, see the BEA TUXEDO Administrator's Guide.

Other Options for Configuring Servers

As with other TUXEDO servers, you can use the full range of BEA TUXEDO system server boot options with eLink TCP for TUXEDO servers.

The -r option may be particularly useful. Using this timestamp recording option, together with the txrpt report command, you can analyze remote service response times. Of course, the process of gathering statistics creates overhead. Consequently, you should use this option selectively.

The RQADDR parameter is also helpful. It enables you to simplify system administration tasks by assigning intuitive names to eLink TCP for TUXEDO server queues. To do so, specify the nodename, LMID or SRVGRP value as part of the queue name (as shown in the following example). Each server entry must have a unique RQADDR value. Also, you cannot use the RQADDR parameter if the BEA TUXEDO MIN or MAX parameters are set to values that are greater than 1.

Here are two final points about boot options:

Boot options must be specified with the CLOPT parameter (before the CLOPT double-dash separator).
Because eLink TCP for TUXEDO 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 BEA TUXEDO Administrator's Guide.

Example

Here is an example of a UBBCONFIG entry that configures an eLink TCP for TUXEDO gateway.

Listing 5-4 Configuring a eLink TCP for TUXEDO Gateway

SERVERS
DMADM      SRVGRP=LIAISON  SRVID=1
GWADM      SRVGRP=REQIMS   SRVID=2
GWIDOMAIN  SRVGRP=REQCICS  SRVID=3  
      CLOPT="-A"

Define the elinkmerc Server as an Alternate Data Mapping Tool (Optional)

The eLink Adapter for Mercator is one choice for an alternate data mapping tool. If you are using the eLink Adapter for Mercator component for data translation, define the elinkmerc server as the server responsible for the data mapping operation. To define this server, add the elinkmerc information in the SERVER section of the UBBCONFIG file. The following parameters are required for defining the elinkmerc server.

Note: You must specify elinkmerc as the file to execute for the data mapping process. Within this server definition, you must also specify the -s option in the CLOPT parameter.

Listing 5-5 Syntax for elinkmerc Server Definition in the UBBCONFIG File

*SERVERS

elinkmerc
	SRVGRP=groupname			SRVID=n
	CLOPT="-s servicename1:XLATE_SERVICE 
              -s servicename2:XLATE_SERVICE -- -WUD -TIO -AE"

For information about the SRVGRP, SRVID, and CLOPT parameter syntax and definitions, refer to the BEA TUXEDO Reference Manual. The definition of the -s option in the CLOPT parameter follows and is required for the data mapping process.

CLOPT="-s servicename: specifies the services to advertise. In this case, the servicename is the advertised service to use for the data conversion. It is the name of the Mercator map files, such as fml2cob.mmc and cob2fml.mmc.
Note: The servicename specified in the CLOPT parameter must also be defined in the SERVICE section.

Updating the SERVICES Section

This section explains how to specify services in the BEA TUXEDO configuration.

Advertise the Services for Data Mapping

Advertise the service for data mapping by defining it in the SERVICES section of the UBBCONFIG file.

Listing 5-6 Syntax for Advertising the Mapping Service

*SERVICES

servicename1
servicename2

servicename: specifies a 1-15 character name of the service for data mapping. An example would be fml2cob and cob2fml.
Note: The name of each of the services must match the map names in the CLOPT parameter in the elinkmerc server definition. For more information about defining services, refer to the BEA TUXEDO documentation about the UBBCONFIG.

Specifying Parameters in the GWICONFIG File

The GWICONFIG file is the mechanism that system administrators use to configure eLink TCP for TUXEDO. 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 BEA TUXEDO administrators to configure eLink TCP for TUXEDO 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:

GLOBAL

Describes certain general characteristics of all eLink TCP for TUXEDO 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 BEA TUXEDO domain through the eLink TCP for TUXEDO gateway. Each local service is linked to a native system using the NATIVE parameter. For each local service, eLink TCP for TUXEDO 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 BEA 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. eLink TCP for TUXEDO 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-7. Each section requires the asterisk (*) in the name.

Listing 5-7 Sample GWICONFIG File

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

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

HP10		WRAP="TPS"
		TYPE="MVS"
		IPADDR="//dalhp10"
		TCP_PORT=0x7000
		RMTACCT="zeke"
		PASSWORD="maple"
#		IDLE_TIME=60

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

CURTIS		WRAP="TPS"
		TYPE="MVS"
		IPADDR="//dalvs2"
		TCP_PORT=9002
		CICS=Y

*LOCAL_SERVICES
TUXTOUPPER    NATIVE="LOCAL"
#		SECURE=Y

ECHO		NATIVE="LOCAL"

*REMOTE_SERVICES
TUXTOLOWER    FOREIGN="RIGHTY"
#TUXTOLOWER   FOREIGN="HP10"
		OUTREQ_TIME=20

BEASVR07		FOREIGN="MIKE"
		OUTRECTYPE="VIEW:weird"

TST1V         FOREIGN="HP10"

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.

Syntax

The format of the GLOBAL section of the GWICONFIG file follows.

Listing 5-8 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 ]

Listing 5-9 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]

Required Parameters

The required parameter described in this section must be set for each local system that you specify in the NATIVE section.

<GATEWAY_NAME>: a 1-78 alphanumeric character string that represents the gateway identification passed in the GWINAME environment variable.
Note: If this local gateway is using code page mapping, the GATEWAY_NAME parameter must match an entry in the DM_LOCAL_DOMAINS section of the DMCONFIG file with the necessary CODEPAGE entry.

Optional Parameters

The optional parameters described in this subsection may be set for each local system that you specify in the NATIVE section.

IPADDR=ip_address: 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]. If you do not specify this parameter, the IP address of the local host machine is looked up and used.
TCP_PORT=port number: 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: specifies the number of seconds a connection can remain idle before being disconnected.
MULTIPLEX=n: specifies the number of outstanding requests per connection that the local gateway can support.
POLL_TIME=n: 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. The default timeout is 250,000 microseconds.
MAXCONNECT=n: 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. The default is no maximum.

Defining the FOREIGN Section of the GWICONFIG File

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

Syntax

The format of the FOREIGN section of the GWICONFIG file is as follows.

Listing 5-10 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"]

Required Parameters

The required parameters described in this subsection must be set for each foreign system that you specify in the FOREIGN section.

<SYSTEM_NAME>

a 1-78 alpha-numeric character string that represents the foreign system name.

Note: If the remote system is using code page mapping, the SYSTEM_NAME parameter must match an entry in the DM_REMOTE_DOMAINS section of the DMCONFIG file with the necessary CODEPAGE entry.

IPADDR=ip_address

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

Optional Parameters

The optional parameters described in this subsection may be set for each foreign system that you specify in the FOREIGN section.

TYPE=system type

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.

Note: For more information about MVS and MVSC TYPE values, refer to "Configuring BEA eLink TCP for TUXEDO for Data Mapping."

WRAP=wrapper name

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 BEA eLink TCP for TUXEDO." If WRAP is not specified in the FOREIGN section, the value for DFLTWRAP in the GLOBAL section is used.

TCP_PORT=port number

specifies the port number of the foreign gateway. This parameter is optional if remote services are not defined for this foreign system. The default is no port number.

MULTIPLEX=n sessions per connection

specifies the maximum number of sessions per connection that the local gateway can support. The default is 1 session per connection.

IDLE_TIME=n seconds

specifies the number of seconds a connection can remain idle before being disconnected. The default is no idle timeout.

CICS=Y | N

specifies whether to send control information to the IBM TCP/IP listener for use with the eLink TCP for CICS gateway. The default is N.

Warning: If CICS=Y and you are not using IBM TCP/IP or your remote gateway is not eLink TCP for CICS, the transaction does not process correctly.

CICSHAND=<name>

specifies the name of the handler transaction to be passed to the IBM TCP/IP listener for use with eLink TCP for CICS. The default is BEAH.

RMTACCT="userid"

specifies the userid for gateway-level security on the foreign system. The default is " ".

PASSWORD="password"

specifies the password associated with the userid for gateway-level security on the foreign system. The default is " ".

MAXCONNECT=n

specifies the maximum number of connections to the specified host. The default is no limit.

CONNSYNC=Y|N

specifies whether to force the gateway to establish connections to the specified host in a synchronous manner. The default is N.

CONNECT_TIME=n

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"

specifies a string to be passed to the IBM TCP/IP listener for use with the eLink TCP for CICS gateway. The default is " ".

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.

Syntax

The format of the LOCAL_SERVICES section of the GWICONFIG file follows.

Listing 5-11 Syntax for LOCAL_SERVICES Section of GWICONFIG File

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

Required Parameters

The required parameters described in this section must be set for each service you specify in the LOCAL_SERVICES section.

<SERVICE_NAME>: 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.
NATIVE="native_system": specifies the corresponding native system or gateway.

Optional Parameters

The optional parameters described in this section may be set for each service you specify in the LOCAL_SERVICES section.

INRECTYPE="foreign_incoming_buffer_type"

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"

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

specifies whether the eLink TCP for TUXEDO gateway applies remote user information to local services.

If SECURE=Y, then the eLink TCP for TUXEDO gateway applies remote user information to local services using the appkey.

If SECURE=N, then the eLink TCP for TUXEDO gateway does not apply remote user information to local services using the appkey. The default is N.

Note: 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

specifies whether service is conversational. Conversational mode is not currently supported, so Y returns an error message and the gateway does not start. The default is N.

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.

Syntax

The format of the REMOTE_SERVICES section of the GWICONFIG file is as follows.

Listing 5-12 Syntax for REMOTE_SERVICES Section of GWICONFIG File

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

Required Parameters

The required parameters described in this section must be set for each service you specify in the REMOTE_SERVICES section.

<SERVICE_NAME>: 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.
FOREIGN="foreign_system": specifies the corresponding foreign system or gateway.

Optional Parameters

The optional parameters described in this section may be set for each service you specify in the REMOTE_SERVICES section.

INRECTYPE="foreign_outgoing_buffer_type"

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 matches the INBUFTYPE value.

OUTRECTYPE="foreign_incoming_buffer_type"

specifies the foreign buffer type for replies from remote servers. If you do not specify OUTRECTYPE, the default is to match the OUTBUFTYPE value.

OUTREQ_TIME=n

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

specifies whether the eLink TCP for TUXEDO gateway supplies local user information to remote services.

If SECURE=Y, then the eLink TCP for TUXEDO gateway supplies user information to remote services.

If SECURE=N, then the eLink TCP for TUXEDO gateway does not supply user information to remote services.

CONV=Y | 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. The default is N.

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.

Syntax

The format of the DM_LOCAL_DOMAINS section of the DMCONFIG file follows.

Listing 5-13 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.

Required Parameters

The following parameters are required.

GWGRP = identifier: specifies the name of the gateway server group (the name provided in the TUXCONFIG file) representing this local domain. There is a one-to-one relationship between a DOMAINID and the name of the gateway server group, that is, each GWGRP must have its own, unique DOMAINID.
TYPE = identifier: 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 eLink TCP for TUXEDO, specify TYPE=IDOMAIN. Domain types must be defined in the $TUXDIR/udataobj/DMTYPE file.
DOMAINID = string: is used to identify the local domain. DOMAINID must be unique across both local and remote domains. 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.

Optional Parameters

The following optional parameters describe resources and limits used in the operation of domain gateways.

AUDITLOG = string: specifies the name of the audit log file for this local domain. The audit log feature is activated from the dmadmin command and records all the operations within this local domain. If the audit log feature is active and this parameter is not specified, the file DMmmddyy.LOG (where mm=month, dd=day, and yy=year) is created in the directory specified by the $APPDIR environment variable or the APPDIR keyword of the MACHINES section of the TUXCONFIG file.
BLOCKTIME = numeric: specifies the maximum wait time allowed for a blocking call. The value sets a multiplier of the SCANUNIT parameters specified in the TUXCONFIG file. The value SCANUNIT * BLOCKTIME must be greater than or equal to SCANUNIT and less than 32,768 seconds. If this parameter is not specified, the default value is set to the value of the BLOCKTIME parameter specified in the TUXCONFIG file. A timeout always implies a failure of the affected request. Notice that the timeout specified for transactions in the TUXCONFIG is always used when the request is issued within a transaction.
CODEPAGE = table-identifier: 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: 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: specifies the name of the domain transaction log for this domain. This name must be unique when the same DMTLOGDEV is used for several local domains. If not specified, the default is the string ``DMTLOG''. The name must be 30 characters or less.
DMTLOGSIZE = numeric: specifies the numeric size, in pages, of the Domain transaction log for this machine. It must be greater than 0 and less than the amount of available space on the TUXEDO file system. If not specified, the default is 100 pages.
MAXDATALEN = numeric: 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: 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: 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: 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: 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.

Syntax

The format of the DM_REMOTE_DOMAINS section of the DMCONFIG file is as follows.

Listing 5-14 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.

Required Parameters

The following parameters are required.

TYPE = identifier: 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 eLink TCP for TUXEDO, specify TYPE=IDOMAIN.
DOMAINID = string: 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".

Optional Parameters

The following optional parameter describes resources used in the operation of remote domain gateways.

CODEPAGE = table-identifier: 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.

Syntax

The format of the DM_ACCESS_CONTROL section of the DMCONFIG file follows.

Listing 5-15 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.

Required Parameters

The following parameter is required.

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

Optional Parameters

There are no optional parameters for this section.

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.

Syntax

The format of the DM_LOCAL_SERVICES section of the DMCONFIG file follows.

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

Required Parameters

There are no required parameters for DM_LOCAL_SERVICES.

Optional Parameters

The following parameters are optional.

ACL = identifier

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

LDOM = identifier

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

RNAME = string

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 eLink TCP, this should match the service name in the GWICONFIG.

INBUFTYPE="type:subtype | FML:servicename"

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"

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.

Syntax

The format of the DM_REMOTE_SERVICES section of the DMCONFIG file follows.

Listing 5-17 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.

Required Parameters

There are no required parameters for the DM_REMOTE_SERVICES section.

Optional Parameters

The following parameters are optional.

CONV = {Y | 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. The default value is N.

LDOM = identifier

specifies the name of a local domain in charge of routing requests to this remote service. The gateway group associated with the local domain advertises service in the 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

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

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 eLink TCP, this should match the service name in the GWICONFIG file.

ROUTING = identifier

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

TRANTIME = integer

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

INBUFTYPE="type:subtype | FML:servicename"

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"

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.

Syntax

The format of the DM_ROUTING section of the DMCONFIG file follows.

Listing 5-18 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.

Required Parameters

The following parameters are required.

FIELD = identifier

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

RANGES = string

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

A range is either a single value (signed numeric value or character string in single quotes), or a range of the form ``lower - upper'' (where lower and upper are both signed numeric values or character strings in single quotes). Note that ``lower'' must be less than or equal to ``upper.'' To embed a single quote in a character string value (as in O'Brien, for example), it must be preceded by two backslashes ('O\\'Brien').

The value MIN can be used to indicate the minimum value for the data type of the associated FIELD; for strings and arrays, it is the null string; for character fields, it is 0; for numeric values, it is the minimum numeric value that can be stored in the field.

The value MAX can be used to indicate the maximum value for the data type of the associated FIELD; for strings and arrays, it is effectively an unlimited string of octal-255 characters; for a character field, it is a single octal-255 character; for numeric values, it is the maximum numeric value that can be stored in the field.

Thus, ``MIN - -5'' is all numbers less than or equal to -5 and ``6 - MAX'' is all numbers greater than or equal to 6. The meta-character ``*'' (wildcard) in the position of a range indicates any values not covered by the other ranges previously seen in the entry; only one wildcard range is allowed per entry and it should be last (ranges following it are ignored).

The routing field can be of any data type supported in FML. A numeric routing field must have numeric range values and a string routing field must have string range values.

String range values for string, array, and character field types must be placed inside a pair of single quotes and cannot be preceded by a sign. Short and long integer values are a string of digits, optionally preceded by a plus or minus sign. Floating point numbers are of the form accepted by the C compiler or atof(): an optional sign, then a string of digits optionally containing a decimal point, then an optional e or E followed by an optional sign or space, followed by an integer.

When a field value matches a range, the associated RDOM value specifies the remote domain to which the request should be routed. 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[, . . . ]]] . . .~

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. This parameter is required. If multiple buffer types are specified for a single routing entry, the data types of the routing field for each buffer type must be the same.

If the field value is not set (for FML 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.

Optional Parameters

There are no optional parameters for the DM_ROUTING section.

Sample DMCONFIG File

Listing 5-19 is a sample DMCONFIG file and must be set up prior to running the eLink TCP for TUXEDO product. For a sample DMCONFIG file that uses alternate data mapping tools, refer to Listing 3-5.

Listing 5-19 Sample DMCONFIG File

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

TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC | INDEX

Configuring BEA eLink TCP for TUXEDO

Updating the SERVERS Section

Define the elinkmerc Server as an Alternate Data Mapping Tool (Optional)

Updating the SERVICES Section

Specifying Parameters in the GWICONFIG File

Required Parameters

Defining the NATIVE Section of the GWICONFIG File

Required Parameters

Optional Parameters

Defining the FOREIGN Section of the GWICONFIG File

Required Parameters

Optional Parameters

Defining the LOCAL_SERVICES Section of the GWICONFIG File

Required Parameters

Optional Parameters

Defining the REMOTE_SERVICES Section of the GWICONFIG File

Required Parameters

Optional Parameters

Defining Domain Configurations in the DMCONFIG File

Optional Parameters

DM_REMOTE_DOMAINS Section

Optional Parameters

DM_ACCESS_CONTROL Section

Optional Parameters

DM_REMOTE_SERVICES Section

DM_ROUTING Section

Optional Parameters