BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
eLink OSI TP Doc Home | User Guide | Previous Topic | Next Topic | Contents | Index | View as PDF

Configuring BEA eLink OSI TP

After the installation of BEA eLink OSI TP is complete, you must configure the software. The proper configuration of eLink OSI TP sets up the gateway configuration.

This section covers the following topics:

- Configuration Prerequisites

- Setting Environment Variables

- Defining Gateway Configurations.

- Defining eLink OSI TP Servers for BEA Tuxedo

- Setting up Security

- Implementing Native-A Encoding

- Processing a Configuration File with the dmloadcf Utility

- Tuning OSI TP-Specific Tables with the TAILOR File

Configuration Prerequisites

The eLink OSI TP product software must be installed and accessible to your text editor. You must have file permission to access the install directory and modify the sample DMCONFIG file.

In addition, the following prerequisites must be met to successfully complete the configuration procedure:

- The $TUXDIR/udataobj/DMTYPE file defining the valid domain types must exist so the dmloadcf utility can load the binary configuration file and must contain a domain type of OSITPX. During the installation process if the DMTYPE file does not contain an OSI TP entry, the DMTYPE file is automatically updated with the required OSITP domain type.

- The effective user identifier of the person running dmloadcf must match the UID in the RESOURCES section of the TUXCONFIG file.

Setting Environment Variables

Before you can invoke system commands, you must set several system environment variables. The following table provides descriptions of the four variables you must set. Most of the environment variables required by BEA eLink OSI TP are set when you set up Tuxedo. Refer to your Tuxedo documentation for more information about setting the Tuxedo environment variables.

Variable | Optional/ Required | Default | Description
--- | --- | --- | ---
OSIRUNDIR | Required | None | Indicates location of eLink OSI TP runtime files.
GW_DFLT_TRANTIME | Optional | 300 seconds | Default transaction time for the server. Value is in seconds
GW_POLLING_INTERVAL | Optional | 300 seconds | Internal Polling time for requests to be serviced. Value is in seconds; valid range is 10-10,000 seconds.
GW_TIMER_INTERVAL | Optional | 300 (3 seconds) | Internal timer for global transaction requests. Value is in one hundredths (1/100) of a second. Valid values are 100-1000 indicating 1-10 seconds.

You must set OSIRUNDIR, before you can boot the gateway or run the osiadmin utility. If you do not set the OSIRUNDIR environment variable before you boot the gateway, you will receive a message telling you to set OSIRUNDIR. This environment variable specifies the path that the eLink gateway uses for runtime files. You can set the OSIRUNDIR environment variable through a script, a command line entry, or through the Windows System Properties in the Control Panel. The variable value should include the path and directory as appropriate for your operating system. If the directory does not exist, the system will create it for you.

The default transaction time on the server is determined at startup by an optional environment variable called GW_DFLT_TRANTIME. If you do not set this variable, the default value is 5 minutes (300 seconds). This environment variable can be set to a different value at startup, but if the value exceeds the maximum allowed for a LONG, then the value is reset to 300 and a LIBGWO_CAT msg 2204 is sent to the ULOG to indicate that the maximum has been exceeded.

Note: The maximum for a LONG is 2147483647.

Defining Gateway Configurations

Whether you are defining a new gateway configuration or modifying an existing one, both processes are similar. Defining a gateway configuration requires the following steps:

1. Define the eLink OSI TP servers in Tuxedo so that the BEA eLink system can recognize the gateway servers. Refer to Defining eLink OSI TP Servers for BEA Tuxedo for more information.

2. Run the osiadmin processor if you are upgrading from eLink OSI TP 1.3. Refer to Using the OSI TP Administration Utility for more information.

3. Determine which parameter information needs to be added or changed to define the gateway. Refer to Understanding the DMCONFIG File for more information.

4. Edit the OSI TP Tailor file if OSI TP-specific tables need to be tuned. Refer to Tuning OSI TP-Specific Tables with the TAILOR File for more information.

5. Create or edit the DMCONFIG file with new gateway information. Refer to Implementing Native-A Encoding and Understanding the DMCONFIG File for more information.

6. Generate a binary version of the dmconfig file by running the dmloadcf utility. Refer to Processing a Configuration File with the dmloadcf Utility for more information.

After you perform these steps, you are ready to start the gateway using the Tuxedo tmboot command. Refer to the BEA Tuxedo Online Documentation for more information about Tuxedo commands.

Defining eLink OSI TP Servers for BEA Tuxedo

To establish a gateway configuration, the BEA Tuxedo system must recognize the gateway servers, DMADM, GWADM, and GWOSITP. You define the eLink OSI TP administrative and gateway servers to the BEA Tuxedo system by editing the UBBCONFIG file.

Perform the following steps to define eLink OSI TP servers for BEA Tuxedo:

1. In the GROUPS section of the UBBCONFIG file, add a server group using the following format:

   >     OSIGRP  GRPNO=1  LMID=SITE1

Note: OSIGRP is used as an example. You may give the group any name you wish.

1. In the SERVERS section of the UBBCONFIG file, add the three server names: DMADM,GWADM,and GWOSITP.

Notes: The DMADM and GWADM entries should be placed in this order BEFORE GWOSITP in the UBBCONFIG file so the admin servers are loaded before the GWOSITP gateway server.

It is recommended that you set the RESTART parameter in the SERVERS section to Y so that the gateway will automatically restart in case of failure.

Sample UBBCONFIG File

The following file is a sample UBBCONFIG file that defines gateway servers to the BEA Tuxedo system.

Listing 4-1 Sample UBBCONFIG File

>     #-----------------------------------
>     # Connect OSI Test; Client ubbconfig
>     #-----------------------------------

>     *RESOURCES
>     #---------------
>     # Replace IPCKEY
>     #---------------
>     IPCKEY       52029
>     MASTER       SITE1
>     DOMAINID     FRONTEND
>     PERM         0660
>     MAXACCESSERS 40
>     MAXSERVERS   80
>     MAXSERVICES  80
>     MAXCONV      120
>     MODEL        SHM
>     LDBAL        Y
>     MAXGTT       120
>     MAXBUFTYPE   16
>     MAXBUFSTYPE  32
>     SCANUNIT     5
>     SANITYSCAN   10
>     DBBLWAIT     5
>     BBLQUERY     50
>     BLOCKTIME    15

>     *MACHINES
>     #---------------------
>     # Replace machine name
>     #---------------------
>     DALNT45      LMID=SITE1
>     #------------------------------
>     # Replace directories as needed
>     #------------------------------
>       TUXDIR="c:\tuxedo"
>       APPDIR="D:\dwh\base\ositp\test\client"
>       TUXCONFIG="D:\dwh\base\ositp\test\client\tuxconfig"
>       TLOGDEVICE="D:\dwh\base\ositp\test\client\TLOG"
>       TLOGNAME="TLOG"

>     *GROUPS
>     OSIGRP2      GRPNO=2 LMID=SITE1
>     OSIGRP3      GRPNO=3 LMID=SITE1 TMSNAME="TMS" TMSCOUNT=2

>     *SERVERS
>     DEFAULT: RESTART=Y
>     DMADM      SRVID=101 SRVGRP=OSIGRP2 CLOPT="-A" REPLYQ=N
>     GWADM      SRVID=103 SRVGRP=OSIGRP2 CLOPT="-A"" REPLYQ=N
>     GWOSITP    SRVID=104 SRVGRP=OSIGRP2 CLOPT="-A" GRACE=0" REPLYQ=N
>     CRPCSERV   SRVID=8 SRVGRP=OSIGRP3 CLOPT="-A" RQADDR="rpcq"
>     CCONVSRV   SRVID=9 SRVGRP=OSIGRP3 CLOPT="-A" RQADDR="convq "CONV=Y
>                     MIN=3 MAX=5

>     *SERVICES
>     DEFAULT:      LOAD=50 AUTOTRAN=N
>     CTOUPPER      PRIO=50
>     CCONVRTN      PRIO=50
>     CCONVRTN2     PRIO=50
>     CCONVRTN3     PRIO=50
>     CTOUPPER2      PRIO=50

Refer to the BEA Tuxedo Reference Manual for additional information about the UBBCONFIG file.

Example of a Multiple Gateway Configuration

Following is a sample UBBCONFIG file and corresponding DMCONFIG file for multiple gateways that reside on the same physical system. Note that use of LDBAL=Y in the UBBCONFIG file is not required for multiple gateways. Loads are automatically balanced for multiple gateways.

Listing 4-2 UBBCONFIG for Multiple Gateways

>     *RESOURCES
>     IPCKEY        65952
>     MASTER        "SITE1"
>     MODEL         SHM
>     PERM          0660
>     LDBAL         N   # not needed for gateway load balancing
>     MAXACCESSERS  40
>     MAXSERVERS    80
>     MAXSERVICES   80
>     MAXGTT        120
>     SCANUNIT      5
>     SANITYSCAN    10
>     BLOCKTIME     15
>     MAXCONV       120

>     *MACHINES
>     "SITE1"       LMID="SITE1"

>                   TUXCONFIG="D:\tuxedo\configs\TUXCONFIG"
>                   TUXDIR="D:\tuxedo"
>                   APPDIR="D:\tuxedo\apps"
>                   TLOGDEVICE="D:\tuxedo\log\TLOG"
>                   ULOGPFX="D:\tuxedo\log\ULOG"
>                   TLOGNAME=TLOG
>                   TLOGSIZE=20
>                   TYPE="SITE1"
>     *GROUPS

>     GROUP1        LMID="SITE1"
>                   GRPNO=1
>     GROUP2        LMID="SITE1"
>                   GRPNO=2

>     DMGRP         LMID="SITE1"
>                   GRPNO=3

>     *SERVERS

>     DEFAULT:      RQPERM=0666
>                   RPPERM=0666
>                   MIN=1
>                   MAX=1
>                   CONV=N
>                   MAXGEN=1
>                   GRACE=86400
>                   RESTART=Y
>                   SYSTEM_ACCESS=FASTPATH

>     DMADM         SRVGRP=DMGRP
>                   SRVID=20
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2
>                   REPLYQ=N

>     GWADM         SRVGRP=GROUP1
>                   SRVID=21
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2
>                   REPLYQ=N

>     GWOSITP       SRVGRP=GROUP1
>                   SRVID=22
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2
>                   REPLYQ=N

>     GWADM         SRVGRP=GROUP2
>                   SRVID=23
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2
>                   REPLYQ=N

>     GWOSITP       SRVGRP=GROUP2
>                   SRVID=24
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2
>                   REPLYQ=N

>     *SERVICES

>     DEFAULT:  LOAD=50 AUTOTRAN=N

Listing 4-3 DMCONFIG File for Multiple Gateways

>     *DM_RESOURCES
>     VERSION="SITE1"
>     #
>     *DM_LOCAL_DOMAINS

>     "GW-1"
>     GWGRP       = GROUP1
>     TYPE        = OSITPX
>     DOMAINID    = "GW-1"
>     BLOCKTIME   = 30
>     DMTLOGDEV   = "D:\tuxedo\log\DMLOG"

>     "GW-2"
>     GWGRP       = GROUP2
>     TYPE        = OSITPX
>     DOMAINID    = "GW-2"
>     BLOCKTIME   = 30
>     DMTLOGDEV   = "D:\tuxedo\log\DMLOG2"

>     ###############################################################
>     *DM_REMOTE_DOMAINS

>     DEFAULT:

>     "OPENTI" TYPE="OSITPX" DOMAINID="OPENTI"

>     ###############################################################
>     *DM_OSITPX

>     "GW-1"
>           AET="{1.3.145.62.103},{2}"
>           TAILOR_PATH="d:\tuxedo\configs\tailor.txt"
>                                  # Inserted from OSITP's config file:
>           NWADDR="//SITE1:102"

>     "GW-2"
>           AET="{1.3.145.62.103},{3}"
>           TAILOR_PATH="d:\tuxedo\configs\tailor2.txt"
>                                  # Inserted from OSITP's config file:
>           NWADDR="//SITE1:2000" #second gateway must use another
>                                          #IP or different port number

>     "OPENTI"
>           AET="{1.3.122.61.203},{20}"
>           NWADDR="122.61.203.20"

>     *DM_LOCAL_SERVICES

>     *DM_REMOTE_SERVICES
>     DEFAULT: TRANTIME=300
>         # Tuxedo will alternate outgoing calls between the two LDOMs.

>     callSvc2   RDOM="OPENTI" LDOM="GW-1" PRIO=66
>     callSvc2   RDOM="OPENTI" LDOM="GW-2" PRIO=66

The following example uses the same UBBCONFIG file as in Listing 4-2 and shows how to configure one LDOM to support the non-multiplexed path and the other to support the multiplexed path.

Listing 4-4 DMCONFIG File for Multiplexed and non-Multiplexed Connections

>     *DM_RESOURCES
>     VERSION="SITE1"
>     #
>     *DM_LOCAL_DOMAINS

>     "GW-1"
>     GWGRP       = GROUP1
>     TYPE        = OSITPX
>     DOMAINID    = "GW-1"
>     BLOCKTIME   = 30
>     DMTLOGDEV   = "D:\tuxedo\log\DMLOG"

>     "GW-2"
>     GWGRP       = GROUP2
>     TYPE        = OSITPX
>     DOMAINID    = "GW-2"
>     BLOCKTIME   = 30
>     DMTLOGDEV   = "D:\tuxedo\log\DMLOG2"

>     ###############################################################
>     *DM_REMOTE_DOMAINS

>     DEFAULT:

>     "OPENTI" TYPE="OSITPX" DOMAINID="OPENTI"
>     "dal2200" TYPE="OSITPX" DOMAINID="dal2200"

>     ###############################################################
>     *DM_OSITPX

>     "GW-1"
>           AET="{1.3.145.62.103},{2}"
>           TAILOR_PATH="d:\tuxedo\configs\tailor.txt"
>                                  # Inserted from OSITP's config file:
>           NWADDR="//SITE1:102"

>     "GW-2"
>           AET="{1.3.145.62.103},{3}"
>           TAILOR_PATH="d:\tuxedo\configs\tailor2.txt"
>                                  # Inserted from OSITP's config file:
>           NWADDR="//SITE1:2000" #second gateway must use another
>                                          #IP or different port number
>           EXTENSIONS="MULTIPLEX_POLICY=DEMAND"

>     "OPENTI"
>           AET="{1.3.122.61.203},{20}"
>           NWADDR="122.61.203.20:2003"
>           EXTENSIONS="MULTIPLEX=Y"

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

>     *DM_LOCAL_SERVICES

>     *DM_REMOTE_SERVICES
>     DEFAULT: TRANTIME=300
>         # Tuxedo will alternate outgoing calls between the two LDOMs.

>     CallSvc1   RDOM="dal2200" LDOM="GW-1" PRIO=66
>     callSvc2   RDOM="OPENTI" LDOM="GW-2" PRIO=66

Using the Tuxedo MP Model with the eLink OSI TP Gateway

It is useful to use the Tuxedo MP model (for multiprocessors that do not have global shared memory or for networked applications) when you require two eLink OSI TP systems to exist in the same domain. (Refer to the BEA Tuxedo documentation for more information about the MODEL parameter.) A practical example of this is setting up a Windows NT cluster. The eLink OSI TP gateway supports active-active failover on an NT cluster. In the MP model case, there are two unique nodes, one defined as the master and a second one defined as a slave or backup system in the case of clustering. There is one UBBCONFIG and one DMCONFIG that physically exist on the master node. At TMBOOT time, a copy of the TUXCONFIG is propagated to the slave or backup system.

Listing 4-5 UBBCONFIG File for MP Model

>     UBBCONFIG

>     *RESOURCES
>     IPCKEY        65952
>     MASTER        SITE1,SITE2
>     MODEL         MP
>     OPTIONS       LAN
>     PERM          0660
>     LDBAL         N   # not needed for gateway load balancing
>     MAXACCESSERS  40
>     MAXSERVERS    80
>     MAXSERVICES   80
>     MAXGTT        120
>     SCANUNIT      5
>     SANITYSCAN    10
>     BLOCKTIME     15
>     MAXCONV       120

>     *MACHINES
>     "SITE1"       LMID="SITE1"
>                   TUXCONFIG="D:\tuxedo\configs\TUXCONFIG"
>                   TUXDIR="D:\tuxedo"
>                   APPDIR="D:\tuxedo\apps"
>                   TLOGDEVICE="D:\tuxedo\log\TLOG"
>                   ULOGPFX="D:\tuxedo\log\ULOG"
>                   TLOGNAME=TLOG
>                   TLOGSIZE=20
>                   TYPE="INTEL"

>     "SITE2"       LMID="SITE2"
>                   TUXCONFIG="D:\tuxedo\configs\TUXCONFIG"
>                   TUXDIR="D:\tuxedo"
>                   APPDIR="D:\tuxedo\apps"
>                   TLOGDEVICE="D:\tuxedo\log\TLOG"
>                   ULOGPFX="D:\tuxedo\log\ULOG"
>                   TLOGNAME=TLOG
>                   TLOGSIZE=20
>                   TYPE="INTEL"

>     *GROUPS
>     GROUP1        LMID="SITE1"
>                   GRPNO=1
>     GROUP2        LMID="SITE2"
>                   GRPNO=2
>     DMGRP         LMID="SITE1"
>                   GRPNO=3

>     *NETWORK
>     SITE1         NADDR="/SITE1:5020"
>                   NLSADDR="//SITE1:5021"
>     SITE2         NADDR="//SITE2:5020"
>                   NLSADDR="//SITE2:5021"

>     *SERVERS
>     DEFAULT:      RQPERM=0666
>                   REPLYQ=Y
>                   RPPERM=0666
>                   MIN=1
>                   MAX=1
>                   CONV=N
>                   MAXGEN=1
>                   GRACE=86400
>                   RESTART=N
>                   SYSTEM_ACCESS=FASTPATH

>     DMADM         SRVGRP=DMGRP
>                   SRVID=20
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2
>                   REPLYQ=N

>     GWADM         SRVGRP=GROUP1
>                   SRVID=22
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2
>                   REPLYQ=N

>     GWOSITP       SRVGRP=GROUP1
>                   SRVID=23
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2
>                   REPLYQ=N

>     GWADM         SRVGRP=GROUP2
>                   SRVID=24
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2
>                   REPLYQ=N

>     GWOSITP       SRVGRP=GROUP2
>                   SRVID=25
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2
>                   REPLYQ=N

>     *SERVICES
>     DEFAULT:  LOAD=50 AUTOTRAN=N

Listing 4-6 DMCONFIG File for MP Model

>     DMCONFIG

>     *DM_RESOURCES
>     VERSION="SITE1"
>     #
>     *DM_LOCAL_DOMAINS

>     "GW-1"
>     GWGRP       = GROUP1
>     TYPE        = OSITPX
>     DOMAINID    = "GW-1"
>     BLOCKTIME   = 30
>     DMTLOGDEV   = "D:\tuxedo\log\DMLOG1"
>     DMTLOGNAME  = "DMLOG"

>     "GW-2"
>     GWGRP       = GROUP2
>     TYPE        = OSITPX
>     DOMAINID    = "GW-2"
>     BLOCKTIME   = 30
>     DMTLOGDEV   = "D:\tuxedo\log\DMLOG2"
>     DMTLOGNAME  = "DMLOG"

>     ###############################################################
>     *DM_REMOTE_DOMAINS

>     DEFAULT:

>     "OPENTI" TYPE="OSITPX" DOMAINID="OPENTI"

>     ###############################################################
>     *DM_OSITPX

>     "GW-1"
>                    AET="{1.3.145.62.103},{2}"
>                    TAILOR_PATH="d:\tuxedo\configs\tailor1.txt"
>                    # Inserted from OSITPX's config file:
>                    NWADDR="//SITE1:102"

>     "GW-2"
>                    AET="{1.3.145.62.103},{3}"
>                    TAILOR_PATH="d:\tuxedo\configs\tailor2.txt"
>                    # Inserted from OSITPX's config file:
>                    NWADDR="//SITE2:102" # second gateway must use
>                                         # another IP or different
>                                         # port number

>     "OPENTI"
>                    AET="{1.3.122.61.203},{20}"
>                    NWADDR="122.61.203.20"

>     ########################################################################*DM_LOCAL_SERVICES

>     ###############################################################
>     *DM_REMOTE_SERVICES
>     DEFAULT: TRANTIME=300
>     # Each system will service different applications.

>     callSvc2   RDOM="OPENTI" LDOM="GW-1" PRIO=66
>     callSvc3   RDOM="OPENTI" LDOM="GW-2" PRIO=66

Using eLink OSI TP as a Pass-Through to Other Tuxedo Systems

For this example, the eLink OSI TP gateway acts as a pass-through to allow access to services on other Tuxedo systems. The eLink OSI TP gateway receives service requests from a remote OLTP system and then forwards them through the /TDOMAINS gateway to a remote Tuxedo system. The systems are as follows:

Figure 4-1 Example of eLink OSI TP Acting as a Pass-Through to Other Tuxedo Systems

Listing 4-7 shows a sample UBBCONFIG file and Listing 4-8 shows the corresponding DMCONFIG file for a pass-through configuration.

Listing 4-7 Sample UBBCONFIG File for Pass-Through Configuration

>     *RESOURCES
>     IPCKEY        65952
>     MASTER        "SITE1"
>     MODEL         SHM
>     PERM          0777

>     *MACHINES
>     "SITE1" LMID="SITE1"

>                   TUXCONFIG="D:\tuxedo\appdir\TUXCONFIG"
>                   TUXDIR="D:\tuxedo"
>                   APPDIR="D:\tuxedo\appdir"
>                   TLOGDEVICE="D:\tuxedo\log\TLOG"
>                   ULOGPFX="D:\tuxedo\log\ULOG"
>                   TLOGNAME=TLOG
>                   TLOGSIZE=20
>                   TYPE="SITE1"
>     *GROUPS

>     ADMGRP        LMID="SITE1"
>                   GRPNO=1

>     OSIGRP        LMID="SITE1"
>                   GRPNO=2

>     TDOMGRP       LMID="SITE1"
>                   GRPNO=3
>                   OPENINFO=NONE

>     *SERVERS

>     DEFAULT:      RQPERM=0666
>                   RPPERM=0666
>                   MIN=1
>                   MAX=1
>                   CONV=N
>                   MAXGEN=1
>                   GRACE=86400
>                   RESTART=N
>                   SYSTEM_ACCESS=FASTPATH

>     DMADM         SRVGRP=ADMGRP
>                   SRVID=20
>                   CLOPT="-A"
>                   RESTART=N
>                   REPLYQ=N

>     GWADM         SRVGRP=OSIGRP
>                   SRVID=21
>                   CLOPT="-A"
>                   RESTART=N
>                   REPLYQ=N

>     GWOSITP       SRVGRP=OSIGRP
>                   SRVID=22
>                   CLOPT="-A"
>                   RESTART=Y
>                   REPLYQ=N

>     GWADM         SRVGRP=TDOMGRP
>                   SRVID=51
>                   CONV=N
>                   CLOPT="-A"
>                   REPLYQ=N
>                   RESTART=N

>     GWTDOMAIN     SRVGRP=TDOMGRP
>                   SRVID=52
>                   CLOPT="-A"
>                   REPLYQ=N
>                   RESTART=Y
>     *SERVICES

>     DEFAULT:  LOAD=50 AUTOTRAN=N

Listing 4-8 Sample DMCONFIG File for Pass-Through Configuration

>     *DM_RESOURCES
>     VERSION="SITE1"
>     #
>     *DM_LOCAL_DOMAINS

>      #  SECURITY=NONE

>     "osi-local"
>                  GWGRP       = OSIGRP
>                  TYPE        = OSITPX
>                  DOMAINID    = "local"
>                  BLOCKTIME   = 2000
>                  AUDITLOG    = "D:\tuxedo\log\AUDIT"
>                  DMTLOGDEV   = "D:\tuxedo\log\DMLOG"
>                  DMTLOGSIZE  = 2048
>                  DMTLOGNAME  = "DMLOG"

>     "td-local"   GWGRP=TDOMGRP
>                  TYPE=TDOMAIN
>                  DOMAINID="td-local"
>                  DMTLOGDEV="D:\tuxedo\log\TDMLOG"

>     ###############################################################
>     *DM_REMOTE_DOMAINS

>     DEFAULT:

>     "osi-client" TYPE=OSITPX   DOMAINID="osi-client"
>     "td-backend" TYPE=TDOMAIN DOMAINID="td-tpaix1"

>     ###############################################################
>     *DM_TDOMAIN

>     "td-local"        NWADDR="192.63.22.2:5000"
>     "td-backend"      NWADDR="192.63.24.74:5000"
>     ###############################################################
>     *DM_OSITPX

>     "osi-local"
>                   AET="{1.3.192.63.22},{2}"
>                   TAILOR_PATH="d:\tuxedo\configs\tailor.txt"

>     # the NWADDR for OSI TP may have the same IP as /TDOMAINS, but
>     # requires a different port number
>                   NWADDR="192.63.22.2:102"

>     "osi-client"
>                    AET="{1.3.192.23.2},{3}"
>       	       NWADDR="192.23.2.3"
>                    T_SEL="OSITP"

>     ###############################################################
>     *DM_LOCAL_SERVICES
>     # define the incoming services here, even though they reside on
>     # some remote /TDOMAIN machine.  Include views also on this machine
>     # for eLink OSI TP to process incoming messages

>     callSvc1

>     ###############################################################
>     *DM_REMOTE_SERVICES
>     DEFAULT:

>     # define the actual remote service request here.  It will be
>     # routed by /TDOMAINS

>     callSvc1   RDOM="td-backend"   LDOM="td-local" RNAME="callSvc1"

Note that the service that resides on the backend /TDOMAIN system must be defined as a local service on the eLink OSI TP system, so eLink OSI TP can process the incoming request. It must also be defined as a remote service so that the /TDOMAIN gateway can pass the service request to the backend /TDOMAIN system. The gateway system must have available the viewfiles and corresponding environment variables that are required by the service, even though the service exists on the backend system.

Setting up Security

BEA eLink OSI TP supports the following two types of security:

- Link Layer Security

- Tuxedo Authentication

The BEA Tuxedo UBBCONFIG and eLink OSI TP DMCONFIG files include five sections in which you specify security parameters for whichever type of security you want to implement:

- RESOURCES section of the UBBCONFIG file

- DM_LOCAL_DOMAINS section of the DMCONFIG file

- DM_OSITPX section of the DMCONFIG file

- DM_ACCESS_CONTROL section of the DMCONFIG file

- DM_LOCAL_SERVICES section of the DMCONFIG file

The following figure shows the relationships between security elements for eLink OSI TP.

Figure 4-2 eLink OSI TP Security Elements

Enabling Link Layer Security

To enable security, both the local and remote domains must support security. For Link Layer Security (LLS), the administrator must define the SECURITY in the *LOCAL_DOMAINS section as DM_PW and the OPTIONS parameter in the DM_OSITPX section must be set to SECURITY_SUPPORTED. The Local and Remote domain passwords should be set by the administrator through the dmadmin command passwd.

Whenever Link Layer Security is defined for the local domain and the remote domain, the passwd entered through dmadmin is hashed with a private key. The hashed value and private key are sent to the remote domain where it is compared with the hashed passwd on the remote system. This is a challenge response mechanism used to secure connections with a remote domain.

Three sections in the DMCONFIG file contain parameters affecting how eLink OSI TP controls access to the local Tuxedo domain:

- DM_LOCAL_DOMAINS section contains a SECURITY parameter that specifies the type of security enforced for the Tuxedo local domain.

The SECURITY parameter settings in this section work in conjunction with the SECURITY parameter in the RESOURCES section of the Tuxedo domain's UBBCONFIG file to establish how eLink OSI TP controls access to the Tuxedo local domain. If this parameter is set to NONE or APP_PW, the eLink OSI TP domain takes no action with regard to security. If this parameter is set to DM_PW, the eLink OSI TP domain enforces security according to the security settings in the DM_PASSWORDS section of the BDMCONFIG file.

Caution: Do not delete the Tuxedo BDMCONFIG file. The DM_PW information will be lost if the file is deleted. When new passwords are entered, the GWOSITP service must be shut down and restarted for the passwords to take effect.

- DM_REMOTE_DOMAINS section contains an OPTIONS=SECURITY_SUPPORTED parameter that specifies the type of security enforced for the Tuxedo remote domain.

- DM_OSITPX section contains an OPTION of SECURITY_SUPPORTED, which indicates that the remote domain supports the OSI TP security extension. The OSI TP security extension allows OSI TP systems to perform link-layer security. The link layer security feature is activated when the DM_LOCAL_DOMAINS section has SECURITY=DM_PW set and OPTIONS=SECURITY_SUPPORTED is set for the remote domain.

Refer to Enabling Tuxedo Authentication for more information about Tuxedo security.

The following sample is a DMCONFIG file that defines the necessary parameters for establishing Link Layer Security.

Listing 4-9 Sample DMCONFIG File for Establishing Link Layer Security

>     #------------------------------------
>     # eLink OSI TP test; Client dmconfig
>     #-------------------------------------
>     #
>     *DM_LOCAL_DOMAINS

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

>     ###############################################################
>     *DM_REMOTE_DOMAINS
>     dal2200       TYPE=OSITPX   DOMAINID=dal2200 ACL_POLICY=GLOBAL
>     openti        TYPE=OSITPX   DOMAINID=openti ACL_POLICY=GLOBAL
>     icl2          TYPE=OSITPX   DOMAINID=icl2
>     aseries       TYPE=OSITPX   DOMAINID="aseries1" ACL_POLICY=LOCAL
>                   LOCAL_PRINCIPAL_NAME="MYNAME'

>     *DM_OSITPX

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

>     # Remote domain dal2200 supports security
>     dal2200
>                   AET="{1.3.132.61.46},{3}"
>                   XATMI_ENCODING="OLTP_TM2200"
>                   NWADDR="132.61.146.3"
>                   T_SEL="OSITP"
>                   OPTIONS=SECURITY_SUPPORTED

>     # Remote domain openti supports security
>     openti
>                   AET="{1.3.122.62.103},{209}"
>                   NWADDR="122.62.103.209:2001"
>                   OPTIONS=SECURITY_SUPPORTED

>     # Remote domain icl12 does not support security
>     icl2
>                   AET="{1.3.142.60.203},{4}"
>                   NWADDR="142.60.203.4"
>                   T_SEL="ICLTP"
>                   S_SEL="SSEL"
>                   P_SEL="PSEL"

>     # Remote domain aseries1 does not support security
>     # DOMAINID "aseries1" shall be used as LOCALPRINCIPAL NAME
>     aseries1
>                   AET="{1.3.123.55.222},{51}"
>                   NWADDR="123.55.222.51"
>                   XATMI_ENCODING="PRELIMINARY"
>                   T_SEL="0x5453"
>                   S_SEL="0x3F5C3F"

>     *DM_LOCAL_SERVICES
>     TOUPPERF
>                   INRECTYPE="VIEW:V10"
>                   OUTBUFTYPE="FML:"
>                   COUPLING=LOOSE

>     TOUPPERF32
>                   INRECTYPE="VIEW:V10"
>                   OUTBUFTYPE="FML32:"
>                   COUPLING=TIGHT
>     TOUPPERV
>                   INBUFTYPE="X_C_TYPE:V10"
>                   INRECTYPE="VIEW:upper"
>                   COUPLING=LOOSE

>     TOUPPERC
>                   INCRECTYPE="X_OCTET"
>                   COUPLING-TIGHT

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

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

>     *DM_REMOTE_SERVICES
>     DEFAULT: TRANTIME=300

>     ECHOXOCT RNAME="ECHOSRVR"
>                   OUTBUFTYPE="X_COMMON:ECHOVIEW"
>                   RDOM=dal2200
>                   LDOM=dalnt8

>     ECHOXCOM RNAME="ECHOSRVR"
>                   RDOM=openti
>                   LDOM=dalnt8
>                   AUTOPREPARE=Y

>     ECHOTYPE
>                   RNAME="ECHOSRVR"
>                   INBUFTYPE="X_C_TYPE:ECHOVIEW"
>                   INRECTYPE="X_C_TYPE:ECHOVIEW"
>                   OUTBUFTYPE="X_C_TYPE:ECHOVIEW"
>                   OUTRECTYPE="X_C_TYPE:ECHOVIEW"

>     ECHOVIEW
>                   RNAME="ECHOSRVR"
>                   INBUFTYPE="VIEW:ECHOVIEW"
>                   INRECTYPE="X_COMMON:ECHOVIEW"
>                   OUTBUFTYPE="VIEW:ECHOVIEW"
>                   OUTRECTYPE="X_COMMON:ECHOVIEW"
>                   RDOM=icl2
>                   LDOM=dalnt8
>                   TPSUT_TYPE= "PRINTABLESTRING"
>                    REM_TPSUT="tpmvs"

Enabling Tuxedo Authentication

BEA eLink OSI TP gateway supports Tuxedo authentication and authorization at both the client side (for Tuxedo clients) and server side. Authentication and authorization at the client side works the same as /T domains. Authentication and authorization on the server side requires that the Link Layer Security, described previously, is configured for both the LOCAL DOMAIN and the REMOTE DOMAIN involved in the service call.

In order for user authentication at the server side domain to be performed, the SECURITY parameter defined in the servers local domain *RESOURCE section must be defined as either "APP_PW", "USER_AUTH", "ACL", or "MANDATORY_ACL".

When SECURITY is set to either "APP_PW" or "USER_AUTH", user authentication is performed. If the ACL_POLICY for the remote domain from which the call was issued is defined as LOCAL, then the user ID used for authentication will be the LOCAL_PRINCIPAL_NAME of the remote domain if it has been defined. If the LOCAL_PRINCIPAL_NAME has not been defined, then the user ID will be the DOMAINID of the remote domain. If the ACL_POLICY for the remote domain from which the call was issued is defined as GLOBAL, then the userid passed with the call is used for user authentication. The user ID is authenticated against the user IDs defined in the tpusr file.

When SECURITY is set to "ACL", then user authentication is performed as previously defined for "APP_PW" and "USER_AUTH". User authorization of the service, requested in the call, is also performed. ACL authorization requires that the services have been defined in the ACL Service list and that the user be a member of a group that is allowed access to this service. Services are added to the ACL Service list through the tpacladd command. If the requested service has not been added to the ACL Service list, then all users are allowed access to this service.

When SECURITY is set to "MANDATORY_ACL" authentication and authorization are performed identical to that for SECURITY equal "ACL", however, the request service must be defined in the ACL Service list and the users group must be allowed access to this service.

For more information regarding Tuxedo commands tpgrpadd, tpusradd, tpacladd, tpgrpmod, tpusrmod, tpaclmod, tpgrpdel, tpasrdel, and tpacldel, refer to the online BEA Tuxedo documentation at http://download.oracle.com/docs/cd/E13203_01/tuxedo/tux80/index.htm.

The following sample shows a UBBCONFIG file. The example defines the necessary parameters for establishing Link Layer Security.

Listing 4-10 Sample UBBCONFIG File Showing Security Set to MANDATORY_ACL.

>     #--------------------------------------------------
>     # eLink OSI TP test ubbconfig for servers
>     #--------------------------------------------------
>     *RESOURCES
>     #-------------
>     Chnage IPCKEY
>     #-------------
>     IPCKEY        52029
>     MASTER        SITE1
>     DOMAINID      FRONTEND
>     PERM          0660
>     MAXACCESSSERS 40
>     MAXSERVERS    80
>     MAXSERVICES   80
>     MAXCONV       120
>     MODEL         SHM
>     LDBAL         Y
>     MAXGTT        120
>     MAXBUFTYPE    16
>     MAXBUFSTYPE   32
>     SCANUNIT      5
>     SANITYSCAN    10
>     DBBLWAIT      5
>     BBLQUERY      50
>     BLOCKTIME     15
>     SECURITY	      MANDATORY_ACL
>     #
>     *MACHINES
>     #-------------
>     #Replace machine name
>     #-------------

>     DALNT45       LMID=SITE1
>     #-------------
>     # Replace directories as needed
>     #-------------
>                   TUXDIR="c:\tuxedo"
>                   APPDIR="c:\ositp/test
>                   TUXCONFIG="c:\tuxedo/udataobj\tuxconfig"
>                   TLOGDEVICE="c:\ositp\test\TLOG
>                   TLOGNAME=TLOG

>     *GROUPS
>     OSIGRP2       GRPNO=2  LMID-SITE1  TMSNAME="TMS"  TMSCOUNT=2
>     OSIGRP2       GRPNO=3  LMID=SITE1

>     *SERVERS
>     DEFAULT:RESTART=N  REPLYQ=Y
>     DMADM    SRVID=101  SRVGRP=OSIGRP3  CLOPT="-A" REPLYQ=N
>     GWADM    SRVID=102  SRVGRP=OSIGRP3  CLOPT="-A" REPLYQ=N
>     GWOSITP  SRVID=103  SRVGRP=OSIGRP3  CLOPT="-A" GRACE=0 REPLYQ=N
>     CRPCSERV SRVID=8	    SRVGRP=OSIGRP3  CLOPT="-A" RQADDR="rpcq"
>     CCONSRV  SRVID=9    SRVGRP=OSIGRP3  CLOPT="-A" RQADDR="convq"
>                         CONV=Y

>     *SERVICES
>     DEFAULT       LOAD=50  AUTOTRAN=n
>     CTOUPPER      PRIO=50
>     CCONVRTN      PRIO=50
>     CCONVRTN2     PRIO=50
>     CCONVRTN3     PRIO=50
>     CTOUPPER2     PRIO=50

The following sample shows a DMCONFIG file. The example defines the necessary parameters for user authentication and authorization.

Listing 4-11 Sample DMCONFIG File Showing LLS set and ACL_POLICY of LOCAL

>     #----------------------------------
>     eLink OSI TP Test; Client dmconfig
>     #----------------------------------

>     #
>     *DM_LOCAL DOMAINS

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

>     ################################################################
>     *DM_REMOTE_DOMAINS
>     DAL2200    TYPE=OSITPX  DOMAINID=DAL2200  ACL_POLICY=LOCAL

>     openti     TYPE=OSITPX  DOMAINID=openti   ACL_POLICY=GLOBAL

>     icl2       TYPE=OSITPX DOMAINID=icl2
>     aseries    TYPE=OSITPX  DOMAINID="aseries1"

>     *DM_OSITPX

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

>     # Remote domain dal2200 supports security
>     dal2200
>                AET="{1.3.132.61.47},{3}"
>                XATMI_ENCODING="OLTP_TM2200"
>                NWADDR="132.61.47.3"
>                T_SEL="OSITP"
>                OPTIONS=SECURITY_SUPPORTED

>     # Remote domain openti supports security
>     openti
>                AET="{1.3.122.62.103},{209}"
>                NWADDR="122.62.103.209:2001"
>                OPTIONS=SECURITY_SUPPORTED

>     # Remote domain icl2 does not support security
>     icl2
>                AET="{1.3.142.60.203},{4}"
>                NWADDR="142.60.203.4"
>                T_SEL="ICLTP"
>                S_SEL="SSEL"
>                P_SEL="PSEL"

>     # Remote domain aseries1 does not support security
>     aseries1
>                AET="{1.3.123.55.222},{51}"
>                NWADDR="123.55.222.51"
>                XATMI_ENCODING="PRELIMINARY"
>                T_SEL="0X5453"
>                S_SEL="0X3F5C3F"

>     *DM_LOCAL_SERVICES
>     TOUPPERF
>                INRECTYPE="VIEW:view10"
>                OUTBUFTYPE="FML:"
>                COUPLING=LOOSE

>     TOUPPERF32
>                INRECTYPE="VIEW:view10"
>                OUTBUFTYPE="fml32"
>                COUPLING=TIGHT

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

>     TOUPPERC
>                INCRECTYPE="X_OCTET"
>                COUPLING=TIGHT

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

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

>     *DM_REMOTE_SERVICES
>     DEFAULT:  TRANTIME=300

>     ECHOXOCT
>                RNAME="ECHOSRVR"
>                OUTBUFTYPE="X_COMMON:ECHOVIOEW"
>                RDOM=dal2200
>                LDOM=dalnt8

>     ECHOXCOM
>                RNAME="ECHOSRVR"
>                RDOM=openti
>                LDOM=dalnt8
>                AUTOPREPARE=Y

>     ECHOTYPE
>                RNAME="ECHOSRVR"
>                INBUFTYPE="X_C_TYPE:ECHOVIEW"
>                INRECTYPE="X_C_TYPE:ECHOVIEW"
>                OUTBUFTYPE="X_C_TYPE:ECHOVIEW"
>                OUTRECTYPE="X_C_TYPE:ECHOVIEW"

>     ECHOVIEW
>                RNAME="ECHOSRVR"
>                INBUFTYPE="VIEW:ECHOVIEW"
>                INRECTYPE="X_COMMON:ECHOVIEW"
>                OUTBUFTYPE="VIEW:ECHOVIEW"
>                OUTRECTYPE="X_COMMON:ECHOVIEW"
>                RDOM=icl2
>                LDOM=dalnt8
>                TPSUT_TYPE="PRINTABLESTRING"
>                REM_TPSUT="tpmvs"

Implementing Native-A Encoding

The Native-A encoding feature in eLink OSI TP converts Tuxedo views into a format that is native to Unisys MCP mainframe systems. This feature moves most of the encode/decode processing from the Unisys MCP mainframe systems to the Tuxedo system.

Using the XATMI_ENCODING Type

Currently, the type of XATMI encoding must be configured for each RDOM using the XATMI_ENCODING parameter in the DM_OSITPX section of the DMCONFIG file. An XATMI_ENCODING keyword value of NATIVE_A_SERIES is used to indicate that the Tuxedo system will handle the encode/decode of data into the Native MCP format, not the Unisys MCP machine.

The following example is a *DM_OSITPX section of the DMCOMFIG file.

>     *DM_OSITPX
>     aseries1
>            AET="{1.3.123.55.22},{51}"
>     	NWADDR="123.55.22.51"
>     	XATMI_ENCODING="NATIVE_A_SERIES"
>     	T_SEL="0x5453"
>     	S_SEL="0x3F5C3F"

Using the CODEPAGE Parameter

There is an optional CODEPAGE parameter on the RDOM statement in the DM_REMOTE_DOMAINS section of the DMCONFIG file. The CODEPAGE parameter is configured to specify the pair of code sets involved when translating character strings between the Tuxedo system and the MCP (A-Series) system. If XATMI_ENCODING is not set to NATIVE_A_SERIES, then the CODEPAGE parameter is ignored.

The syntax is shown below:

>     *DM_REMOTE_DOMAINS
>     ...
>     rdom TYPE=OSITPX DOMAINID="domainid" CODEPAGE="cpname"

Where cpname is a case-insensitive keyword from the following table:

cpname keyword | ISO Character Set | MCP Character Set
Tuxedo | ASCII | ASERIESEBCDIC
88591xL1EBC | ISO 8859-1 (Latin-1) | Latin1EBCDIC
88592xL2EBC | ISO 8859-2 (Latin-2) | Latin2EBCDIC
88599xL5EBC | ISO 8859-9 (Latin-5) | Latin5EBCDIC
885915xL9EBC | ISO 8859-15 (Latin-9) | Latin9EBCDIC
88595xLCYEBC | ISO 8859-5 (Latin Cyrillic) | LatinCyrillicEBC
88597xLGREBC | ISO 8859-7 (Latin Greek) | LatinGreekEBCDIC
88591xIBMSEBC | ISO 8859-1 (Latin1) | IBMSwedenEBCDIC
AR20xAR20EBC | Arabic20ISO | Arabic20EBCDIC

Rules for Viewfile Character Types

If XATMI_ENCODING is not set to NATIVE_A_SERIES, then no conversion of character strings occurs. If XATMI_ENCODING is set to NATIVE_A_SERIES, then conversions occur according to the rules described in the following subsections.

Rules for Type string

All view fields of type string must be null-terminated on both the Tuxedo and NATIVE_A_SERIES encoding feature, string fields may contain any non-zero bytes, followed by a zero byte as a null-terminator.

All view fields of type string are always translated from the ISO character set to the MCP character set (as specified by the CODEPAGE parameter) when passing from the Tuxedo system to the MCP system. The input string must be null-terminated; any bytes after the null-terminator are ignored. The resulting string on the Unisys MCP system is null-terminated; any remaining space in the field is also padded with zero bytes.

Conversly, all view fields of type string are translated from the MCP character set to the ISO character set (as specified by the CODEPAGE parameter) when passing from the Unisys MCP system to the Tuxedo system. The input string must be null-terminated; any bytes after the null-terminator are ignored. The resulting string on the Tuxedo system is null-terminated; any remaining space in the field is also padded with zero bytes.

Rules for Type carray

View fields of type carray need not be null-terminated. Carray fields may contain any non-zero bytes; if a zero byte is detected, it is treated as a null-terminator and scanning stops.

All view fields of type carray are always translated from the ISO character set to the MCP character set (as specified by the CODEPAGE parameter) when passing from the Tuxedo system to the Unisys MCP system. The input string may or may not be null-terminated; any bytes after a null-terminator are ignored. The resulting string on the MCP system is not null-terminated; any remaining space in the field is padded with EBCDIC space characters (0x40 bytes).

Conversly, all view fields of type carray are translated from the MCP character set to the ISO character set (as specified in the CODEPAGE parameter) when passing from the Tuxedo system to the Unisys MCP system. The input string may or may not be null-terminated; any bytes after a null-terminator are ignored. If the input string is not null-terminated, then any trailing EBCDIC space characters (0x40 bytes) are discarded before translation starts. The resulting string on the Tuxedo system is null-terminated if there is room; any remaining space in the field is also padded with zero bytes.

For existing users who plan to use the Native-A feature, it is important to note that fields of type carray are always translated. If you wish to transmit binary data that should not be translated, then you must change your view field type from carray to an array of type char.

Rules for Type char

View fields of type char may contain any arbitrary binary data. View fields of type char are never translated.

For existing users who plan to use the Native-A feature, it is important to note that fields of type char are never translated. If you want to have fields of type char translated, you need to change your view field type from char to carray. See the following example.

Listing 4-12 Example of char Field Changed to carray

>     VIEW viewx
>     #
>     #type   cname       fbname  count  flag   size  null
>     #
>     int     accountNum   -      1      -      -     -
>     string  firstName    -      1      -      20    -
>     # Change middleInit from char to carray so it is translated
>     # char  middleInit   -      1      -      -     -
>     carray  middleInit   -      1      -      1     -
>     string  laststName   -      1      -      20    -
>     END

Conversly, you may wish to change other data types (e.g., carray) to type char to prevent then from being translated. See the following example:

Listing 4-13 Example of carray Field Changed to char

>     VIEW viewy
>     #
>     #type   cname       fbname  count  flag   size  null
>     #
>     int     accountNum   -      1      -      -     -
>     string  name         -      1      -      50    -
>     #Change encryptKey from carray to char so it is not
>     #translated:
>     #carray encryptKey   -      1      -      15    -
>     char    encryptKey   -      15     -      -     -
>     END

Editing the DMCONFIG File

If you are upgrading from eLink OSI TP 1.3, it is recommended that you use the osiadmin utility to update your DMCONFIG file; however, you may edit the DMCONFIG file manually. If you are upgrading from eLink OSI TP 4.0 or 4.1, you do not need to change your udmconfig input file. You can use it as input to the eLink OSI TP 4.2 dmloadcf utility. Refer to Using the OSI TP Administration Utility for more information about the osiadmin utility.

To edit the DMCONFIG file manually, perform the following steps:

1. Find the DMCONFIG file in your installation directory and open it in any text editor.

2. Edit the DMCONFIG file as necessary. Refer to the parameter descriptions in this section for details about defining your eLink OSI TP configuration.

3. When editing is complete, save the DMCONFIG file.

Note: You may want to save the original DMCONFIG file with a different name or in a different directory.

1. Process the DMCONFIG file with the dmloadcf utility. This parses the input and creates a binary file: the BDMCONFIG file, which is used by GWOSITP.Refer to Understanding the DMCONFIG File for more detailed information about the parameters in the DMCONFIG file.

Steps for Modifying the DMCONFIG File Parameters

Perform the following steps to modify the DMCONFIG file parameters:

- Step 1 - Define Local Domains

- Step 2 - Define Remote Domains

- Step 3 - Specify Addressing Information for OSI TP Domains

- Step 4 - Specify Access Control for OSI TP Domains

- Step 5 - Specify Available Local Tuxedo Services

- Step 6 - Specify Available Remote Tuxedo Services

- Step 7 - Specify Routing Information

Step 1 - Define Local Domains

You must define the local domains that use the OSI TP server group you defined in your Tuxedo UBBCONFIG file. Refer to Defining eLink OSI TP Servers for BEA Tuxedo for more information about the UBBCONFIG file.

Perform the following steps to define a local domain in the DM_LOCAL_DOMAINS section of the DMCONFIG file:

1. Specify the local domain ID with the DOMAINID parameter.

2. Specify the gateway group you defined in the UBBCONFIG file with the GWGRP parameter.

3. Specify the domain type of OSITPX with the TYPE parameter.

4. Specify the size of the domain transaction log with the DMTLOGSIZE parameter.

5. Specify any of the optional DM_LOCAL_DOMAINS parameters that you require: AUDITLOG, BLOCKTIME, DMTLOGDEV, DMTLOGNAME, MAXRDTRAN, MAXTRAN, and SECURITY.

   Listing 4-14 Example of DM_LOCAL_DOMAINS Section

>     *DM_LOCAL_DOMAINS

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

Refer to Sample Configuration File for more detailed information.

Step 2 - Define Remote Domains

It is recommended that you use the importcfg command in the osiadmin utility to update remote domains if you are upgrading from BEA eLink OSI TP 1.3; however, you can manually define remote domains. Refer to Using the OSI TP Administration Utility for more information about the osiadmin utility.

Perform the following steps to define remote domains in the DM_REMOTE_DOMAINS section of the DMCONFIG file:

1. Specify the remote domain ID with the DOMAINID parameter.

2. Specify the OSITPX domain type with the TYPE parameter.

There are no optional parameters for the DM_REMOTE_DOMAINS section.

Listing 4-15 Example of DM_REMOTE_DOMAINS Section

>     *DM_REMOTE_DOMAINS

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

Refer to DM_REMOTE_DOMAINS Section for more detailed information.

Step 3 - Specify Addressing Information for OSI TP Domains

Perform the following steps to define addressing information for OSI TP domains in the DM_OSITPX section of the DMCONFIG file:

1. Specify the Application Entity Title for each local and remote OSI TP domain with the AET parameter.

2. Specify the IP address or DNS name and port number for each local and remote OSI TP domain with the NWADDR parameter. If you are using multiple IP addresses, make sure to enter all the addresses on one line, and separate them with a semi-colon (;). Put double quotes around the entire address.

3. Specify any of the optional DM_OSITPX parameters that you require: DNS_RESOLUTION, P_SEL, S_SEL, T_SEL, OPTIONS, TAILOR_PATH, and XATMI_ENCODING.

   Listing 4-16 DM_OSITPX Section

>     *DM_OSITPX

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

>     dal2200
>                    AET="{1.3.132.61.146},{3}"
>                    XATMI_ENCODING="OLTP_TM2200"
>                    NWADDR="132.61.146.3;132.61.147.1"
>                    T_SEL="OSITP"

>     openti
>                    AET="{1.3.122.62.103},{209}"
>                    NWADDR="122.62.103.209"

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

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

Refer to DM_OSITPX Section for more detailed information.

Step 4 - Specify Access Control for OSI TP Domains

In the DM_ACCESS_CONTROL section of the DMCONFIG file, specify a list of all the remote OSI TP domain IDs that can access the local domain with the ACLIST parameter. This parameter is optional.

Listing 4-17 Example of DM_ACCESS_CONTROL Section

>     *DM_ACCESS_CONTROL
>     mylist  ACLIST = dalnt8, dal2200

Refer to DM_ACCESS CONTROL Section for more detailed information.

Step 5 - Specify Available Local Tuxedo Services

In the DM_LOCAL_SERVICES section of the DMCONFIG file, specify the Tuxedo services that will be made available to OSI TP applications and define their options with the ACL, COUPLING, INBUFTYPE, INRECTYPE, LDOM, OUTBUFTYPE, OUTRECTYPE, and RNAME parameters. If the local service supports transactions, make sure the group it belongs to contains a TMS name.

These DM_LOCAL_SERVICES parameters are all optional.

Listing 4-18 Example of DM_LOCAL_SERVICES Section

>     *DM_LOCAL_SERVICES
>     TOUPPERF
>       INRECTYPE="VIEW:view10"
>       OUTBUFTYPE="FML:"
>       COUPLING=LOOSE

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

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

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

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

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

Refer to DM_LOCAL_SERVICES Section for more detailed information.

Step 6 - Specify Available Remote Tuxedo Services

In the DM_REMOTE_SERVICES section of the DMCONFIG file, specify the remote services that can be requested by Tuxedo applications and define their options with the AUTOPREPARE, CODEPAGE, CONV, INBUFTYPE, INRECTYPE, LDOM, OUTBUFTYPE, OUTRECTYPE, RDOM, RNAME, ROUTING, and TRANTIME parameters. These parameters are all optional.

Listing 4-19 Example of DM_REMOTE_SERVICES Section

>     *DM_REMOTE_SERVICES
>     DEFAULT: TRANTIME=300

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

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

Refer to DM_REMOTE_SERVICES Section for more detailed information.

Step 7 - Specify Routing Information

Perform the following steps to define routing information for service requests in the DM_ROUTING section of the DMCONFIG file:

1. Specify the name of the routing field with the FIELD parameter.

2. Specify the data buffer type and subtype for which the routing entry is valid with the BUFTYPE parameter.

3. Specify the ranges and associated remote domain names for the routing field with the RANGES parameter.

   Listing 4-20 Example of DM_ROUTING Section

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

Refer to DM_ROUTING Section for more detailed information.

Processing a Configuration File with the dmloadcf Utility

The dmloadcf utility compiles the DMCONFIG file and creates a binary configuration file, BDMCONFIG, which is used by the DMADM server to control the run-time environment.

Figure 4-3 shows how the dmloadcf utility processes the configuration file. A description of the process follows the figure.

Figure 4-3 dmloadcf Process

Invoking the dmloadcf Utility

The dmloadcf utility is invoked from a command line with the following syntax:

>     dmloadcf [-c] [-n] [-y] [-b blocks] [-k] DMCONFIG_file

where the following options are valid:

  -c

  Prints minimum IPC resources needed for each local domain (gateway group) in this configuration. The BDMCONFIG file is not updated.

  -n

  Checks only the syntax of the ASCII DMCONFIG file without actually updating the BDMCONFIG file.

  -y

  Suppresses a prompt to create and initialize the BDMCONFIG file. This parameter must be entered before the DMCONFIG file name.

  -b blocks

  Indicates the number of blocks the device should use to create the Tuxedo file system. If the value of the -b option is large enough to hold the new BDMCONFIG tables, dmloadcf uses the specified value to create the new file system; otherwise, dmloadcf prints an error message and exits. If the -b option is not specified, dmloadcf creates a new file system large enough to hold the BDMCONFIG tables. The -b option is ignored if the file system already exists. The -b option is highly recommended if BDMCONFIG is a raw device (that has not been initialized) and should be set to the number of blocks on the raw device.

  dmconfig_file

  Specifies the name of the input configuration file to dmloadcf.

How the dmloadcf Utility Works

The dmloadcf utility prints an error message if any required section of the DMCONFIG file is missing. If a syntax error is found while parsing the input file, dmloadcf exits without performing any updates to the BDMCONFIG file.

A Tuxedo DMTYPE file is required to define the valid domain types. If this file does not exist, dmloadcf exits without performing any updates to the BDMCONFIG file.

The effective user ID of the person running dmloadcf must match the UID in the RESOURCES section of the TUXCONFIG file.

After syntax checking, dmloadcf verifies that the file pointed to by BDMCONFIG exists, is a valid Tuxedo System file system, and contains BDMCONFIG tables. If these conditions are not true and the -y option was not entered on the command line, the user is prompted to create and initialize the file with

>     Initialize BDMCONFIG file: path {y, q}?

where path is the complete file name of the BDMCONFIG file and "Y" indicates that the configuration file should be created.

If the BDMCONFIG file is determined to already have been initialized, dmloadcf ensures that the local domain described by that BDMCONFIG file is not running. If a local domain is running, dmloadcf prints an error message and exits. Otherwise, dmloadcf confirms that the file should be overwritten by prompting the user with:

>     "Really overwrite BDMCONFIG file {y, q}?"

Prompting is suppressed if the standard input or output are not terminals. Any response other than "y" or "Y" causes dmloadcf to exit without creating the configuration file. If the BDMCONFIG file is not properly initialized and the user has responded with "Y", dmloadcf creates the Tuxedo file system and then creates the BDMCONFIG tables.

If the SECURITY parameter is specified in the RESOURCES section of the TUXCONFIG file, then dmloadcf flushes the standard input, turns off terminal echo, and prompts the user for an application password.

Assuming no errors, and if all checks have passed, dmloadcf loads the DMCONFIG file into the BDMCONFIG file and overwrites all existing information found in the BDMCONFIG tables.

The following example shows how a binary configuration file is loaded from the bank.DMCONFIG ASCII file. The BDMCONFIG device is created (or reinitialized) with 2000 blocks:

>     dmloadcf -b 2000 -y bank.dmconfig

Diagnostics

If an error is detected in the input, the erroneous line is printed to the standard error log along with a message indicating the problem. If a syntax error is found in the DMCONFIG file or the system is currently running, no information is updated in the BDMCONFIG file and dmloadcf exits.

If dmloadcf is run on an active node, the following error message is displayed:

>     *** dmloadcf cannot run on an active node ***

If dmloadcf is run by a person whose effective user ID doesn't match the UID specified in the TUXCONFIG file, the following error message is displayed:

>     *** UID is not effective user ID ***

Upon successful completion, dmloadcf exits. If the BDMCONFIG file is updated, a userlog message is generated to record this event.

Tuning OSI TP-Specific Tables with the TAILOR File

The OSI TP TAILOR file is external to the DMCONFIG and is used for tuning OSI TP- specific tables. All parameters in the TAILOR file are optional with preset defaults.

Following is a list of valid TAILOR parameters:

Parameter | Default | Description
--- | --- | ---
* FreeOldRetryTime | 600 seconds | Time in seconds between automatic terminations of old connections
MaxConnections | 500 | Maximum size of various internal tables
** KeepAliveCheck | 60 | Time in seconds of connection inactivity before a keepalive packet is sent on the connection.
** KeepAliveTimeout | 10 | Time in seconds to wait for an acknowledgement message when a keepalive packet is sent. If this timeout is exceeded, then the connection is re-established.
MaxRemoteNodes | 1000 | Maximum number of total remote domains
* OldAssocTimeout | 3600 seconds | Time in seconds denoting an "old" connection (association)
* RdomAssocRetry | 60 seconds | Time in seconds between automatic retries of associations to unavailable RDOMS.
* TCPSocketsKeepAlives | N | Toggle for TCP keepalive packets
** StartFlowControlThreshold | 1,048,576 | Number of bytes of data which may be buffered to a particular RDOM before flow control is started.
** StopFlowControlThreshold | 102,400 | Number of bytes that the data buffered to the RDOM must fall below before flow control is relieved (when flow control is in effect.)
TCPSocketsLinger | -1 | Amount of time TCP/IP socket connection stays open
TCPSocketsListenQueueDepth | 5 | Number of held TCP/IP connections waiting to be accepted by eLink OSI TP
TCPSocketsNoDelay | N | Toggle to delay sends of TCP/IP packets until an ACK is received from remote machine
TraceIpcKey | 32800 | IPC key value for the OSI TP log and trace shared memory section

Note: The parameters in the previous table with an asterisk (*) are valid for non-multiplexed connections only.

The parameters with double asterisks (**) apply only if you are using the multiplexing protocol.

Following is more detailed information about each of the TAILOR file parameters:

  FreeOldRetryTimer = numeric

  Specifies the time in seconds between automatic terminations of old connections (associations). OSI TP reuses established socket connections to a remote domain. The default value is 600 seconds.

Note: This parameter is valid for non-multiplexed connections only.

  KeepAliveCheck = numeric

  Specifies the time in seconds of connection inactivity before a keepalive packet is sent on the connection. The default value is 60 seconds.

Note: This parameter is only valid when using the multiplexing protocol.

  KeepAliveTimeout = numeric

  Specifies the amount of time in seconds to wait for an acknowledgement message when a keepalive packet is sent. If this timeout is exceeded, then the connection is re-established. The default is 10 seconds.

Note: This parameter is only valid when using the multiplexing protocol.

  MaxConnections = numeric

  Specifies the size of various internal tables. This value should be at least as large as the maximum number of total remote domains, including those added dynamically. The default value is 1000.

  MaxRemoteNodes = numeric

  Specifies the maximum number of total remote domains, including those added dynamically. The default value is 1000.

  OldAssocTimeout = numeric

  Specifies the time in seconds denoting an "old" connection (association). Any connection to a remote domain that remains unused by a tpcall() for this amount of time is subject to automatic termination. This default value is 3600 seconds.

Note: This parameter is valid for non-multiplexed connections only.

  RdomAssocRetry = numeric

  Specifies the time in seconds between automatic retries of associations to unavailable RDOMs. This value must be greater than zero. The default value is 60. This value may be overridden on each RDOM with the EXTENSION parameter and the RdomAssocRetry keyword.

Note: This parameter is valid for non-multiplexed connections only.

  StartFlowControlThreshold = numeric

  Specifies the number of bytes of data which may be buffered to a particular RDOM before flow control is started. When the data buffered to one particular RDOM exceeds this value, the services advertised for that RDOM/LDOM combination are suspended. The default value is 1,048,576 bytes.

Note: This parameter is only valid when using the multiplexing protocol.

  StopFlowControlThreshold = numeric

  Specifies the number of bytes that the data buffered to the RDOM must fall below before flow control is relieved (when flow control is in effect.) When buffering drops below this value for one particular RDOM, the services for that RDOM/LDOM combination are advertised again. The default value is 102,400 bytes.

Note: This parameter is only valid when using the multiplexing protocol.

  TCPSocketsKeepAlives = {Y | N}

  Specifies whether the TCP keepalive packets are sent. This is useful to insure the integrity of the TCP connection. If Y is specified the TCP/IP packets are sent out in a time period specified by the operating system. Most operating systems use a 2 hour time period. The default is N.

Note: This parameter is valid for non-multiplexed connections only.

  TCPSocketsLinger = {-1 | 0 | numeric}

  Specifies the amount of the time that the TCP/IP socket connection will stay open. This can be used to timeout hung connections.

  Possible values are:

-1 (default) | Time that a TCP/IP socket connection stays in the TIME_WAIT state is determined by the operating system.
0 | TCP/IP connection is closed immediately.
n | TCP/IP connection stays in the TIME_WAIT state for n seconds before closing.

  TCPSocketsListenQueueDepth = numeric

  Specifies the number of held TCP/IP connections waiting to be accepted by eLink OSI TP.

  Possible values are:

5 (default) | A minimum of 5 incoming TCP/IP connections are held.
>5 | More than 5 incoming TCP/IP connections are held. The operating system may only supports a number up to a "reasonable value".

  TCPSocketsNoDelay = {Y | N}

  Specifies if subsequent sends of TCP/IP packets are held until an ACK is received from a remote machine. The default is N, the subsequent sends of TCP/IP packets may be held until an ACK is received. If Y is specified, the TCP/IP packets are sent immediately without waiting for an ACK of the previous send.

  TraceIpcKey = numeric

  For UNIX systems, specifies the IPC key value for the OSI TP log and trace shared memory segment. If there are multiple local domains, then each domain must have a unique IPC key value. On Windows NT systems, this value is ignored. The default is 32800.

Enabling Automatic Suspension of Remote Services

The BEA eLink OSI TP service suspend feature provides greater reliability for remote services by automatically suspending services for a remote domain that is unreachable. Automatic suspension prevents repeated calls to remote services that are no longer available. This feature is especially critical when load balancing between remote domains.

eLink OSI TP provides this service suspend feature by maintaining at least one association to every remote RDOM to determine its availability. If an association cannot be established, the services associated with that RDOM will immediately fail. Redundantly defined services will not attempt to use the unavailable RDOM and are diverted.

By default, eLink OSI TP will retry connections to an RDOM that has failed every 60 seconds. This delay may be overridden with the RdomAssocRetry tailor parameter described in the Tuning OSI TP-Specific Tables with the TAILOR File section. It may also be overridden for specific RDOMs using the EXTENTIONS="RdomAssocRetry=n" parameter in the DM_OSITPX section, where n is the number of seconds to wait between retries. The value specified on the EXTENTIONS parameter overrides the corresponding tailor parameter. Refer to DM_OSITPX Section for more information.

In test environments, RDOMs may be configured that are unavailable and are considered offline. ELink OSI TP continually tries to connect to these systems. To disable the RDOMs and the remote services configured to them, specify EXTENSIONS="ONLINE=N" on each offline RDOM in the DM_OSITPX section of the DMCONFIG file. At run-time, these RDOMs can be brought online using the ONLINE osiadmin command described in Using osiadmin Commands.

Copyright © 2002 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.