10 Configuring Oracle Database Gateway for Adabas

10.1.1 Choose a System Identifier for the Gateway

Choosing a system identifier is the first task in configuring Oracle Database Gateway for Adabas. The gateway system identifier (SID) is an alphanumeric character string that identifies a gateway instance. If you want to connect simultaneously to different Adabas data sources, you need one gateway instance, and therefore one gateway SID, for each Adabas database you are accessing. The SID name is used as part of the file name for the initialization parameter file. The default SID is dg4adbs.

The HS_FDS_DATASOURCE_NAME parameter takes on the gateway SID as the default value. This means that the data source matches the gateway SID by default. However, you can specify the value of the HS_FDS_DATASOURCE_NAME parameter to match the data source that you want to access. See "HS_FDS_DATASOURCE_NAME" for more information.

If you have one Adabas data source and want to access it sometimes with one set of gateway parameter settings, and other times with different gateway parameter settings, you can do that by defining two different data sources and defining the matching SID s accordingly.

10.1.2 Customize the Initialization Parameter File

Customizing the initialization parameter file is the second task in configuring Oracle Database Gateway for VSAM. The initialization parameter file must be available when the gateway is started. During installation, the following default initialization parameter file is created:

$ORACLE_HOME/dg4adbs/admin/initdg4adbs.ora

Where $ORACLE_HOME is the directory under which the gateway is installed.

The name of the parameter file is init[SID].ora, where SID is the gateway SID. If you are not using dg4adbs as the gateway SID, you must rename the initialization parameter file using the SID you chose in Task 1. This default initialization parameter file is sufficient for starting the gateway, verifying a successful installation, and running the demonstration scripts.

In the initialization parameter file, specify the Adabas connection as follows:

In the initialization parameter file, specify the VSAM connection as follows:

• If you use the default workspace:

  HS_FDS_CONNECT_INFO="address:port"
  

• If you use a workspace other than the default:

  HS_FDS_CONNECT_INFO="address='host' port='port' workspace='workspace'"
  

Where:

• host: The name of the mainframe computer on which Oracle Connect for IMS, VSAM, and Adabas Gateways runs.

• port: The port number to listen to.

• workspace: The Adabas data source workspace name. (optional)

A number of initialization parameters can be used to modify the gateway behavior. You may want to change the initialization parameter file later to meet system requirements.

10.2.1 Configure Oracle Net Services Oracle Net Listener for the Gateway

Oracle Net Services uses the Oracle Net Listener to receive incoming connections from a Oracle Net Services client. The Oracle Net Listener and the gateway must reside on the same machine.

The Oracle Net Listener listens for incoming requests from the Oracle Database. For the Oracle Net Listener to listen for the gateway, information about the gateway must be added to the Oracle Net Listener configuration file, listener.ora. This file is located in the following directory:

$ORACLE_HOME/network/admin

The following entries must be added to the listener.ora file:

• A list of Oracle Net Services addresses on which the Oracle Net Listener listens.

• The gateway that the Oracle Net Listener starts in response to incoming connection requests.

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS_LIST =
        (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC))
      )
      (ADDRESS_LIST =
        (ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = 1552))
      )
    )
  )

SID_LIST_LISTENER =
  (SID_LIST =
  .
  .
  (SID_DESC=
  (SID_NAME=gateway_sid)
  (ORACLE_HOME=ORACLE_HOME_directory)
  (PROGRAM=dg4adbs)
  (ENVS=LD_LIBRARY_PATH=$ORACLE_HOME/lib)
  )
)

10.2.2 Stop and Start the Oracle Net Listener for the Gateway

The Oracle Net Listener must be started to initiate the new settings, as follows:

1. Set the PATH environment variable to access the commands in the following directory:

   $ORACLE_HOME/bin
   

   If you have the Bourne or Korn Shell, enter the following:

   $ PATH=$ORACLE_HOME/bin:$PATH;export PATH
   $ LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
   

   If you have the C Shell, enter the following:

   $ setenv PATH $ORACLE_HOME/bin:$PATH
   $ setenv LD_LIBRARY_PATH $ORACLE_HOME/lib:$LD_LIBRARY_PATH
   

   where $ORACLE_HOME is the directory where the gateway is installed.

2. If the listener is already running, use the lsnrctl command to stop the listener and then start it with the new settings, as follows:

   $ lsnrctl stop$ lsnrctl start 
   

3. Check the status of the listener with the new settings, as follows:

   $ lsnrctl status
   

   The following is an example of output from a lsnrctl status check:

LSNRCTL for SOLARIS: Version 11.1.0 - Production on 01-JUN-2005 09:16:17

Copyright (c) 1991, 2004, Oracle. All rights reserved.

Connecting to (ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=1521))
STATUS of the LISTENER
----------------------
Alias                    listener
Version                  TNSLSNR for SOLARIS: Version 11.1.0 - Production
Start Date               31-May-2005 10:16:17
Uptime                   0 days 18 hr. 5 min. 13 sec
Trace Level              off
Security                 OFF
SNMP                     OFF
Listener Parameter File  /users/oracle/gateway/network/admin/listener.ora
Listener Log File        /users/oracle/gateway/network/log/listener.log
Listening Endpoints Summary...
  (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=1521)))
Services Summary...
Service "dg4adbs" has 1 instance(s).
  Instance "dg4adbs", status UNKNOWN, has 1 handler(s) for this service...
The command completed successfully

In this example, dg4adbs is the default SID value assigned during installation. You can use any valid ID for the SID, or keep the default.

10.3.1 Configuring Oracle Net Services for the Oracle Database

To configure the server you add connect descriptors to the tnsnames.ora file. You cannot use the Oracle Net Services Assistant or the Oracle Net Services Easy Config tools to configure the tnsnames.ora file. You must edit the file manually.

For the Oracle Database to access the gateway, it needs a service name entry or a connect descriptor name entry in the tnsnames.ora file to tell the Oracle Database where to make connections.

By default, this file is in $ORACLE_HOME/network/admin, where $ORACLE_HOME is the directory in which the Oracle Database is installed. The tnsnames.ora file is required by the Oracle Database accessing the gateway, but not by the gateway.

connect_descriptor=
vsam =
  (DESCRIPTION =
  (ADDRESS_LIST =
  (ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = port_number))
  )
  (CONNECT_DATA =
  (SID = gateway_sid)
  )
  (HS = OK)
  )

connect_descriptor=
Adabas =
  (DESCRIPTION =
  (ADDRESS_LIST =
  (ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = port_number))
  )
  (CONNECT_DATA =
  (SID = gateway_sid)
  )
  (HS = OK)
  )

10.6.1 Multiple Databases Example: Configuring the Gateway

Choose Two System IDs for Each Adabas Database

A separate instance of the gateway accesses the different Adabas databases. Each instance needs its own gateway System ID (SID). For this example, the gateway SIDs for the instances that access the Adabas databases are named as follows:

• dg4adbs2 for the gateway accessing data source dg4adbs2.

• dg4adbs3 for the gateway accessing data source dg4adbs3.

Create Two Initialization Parameter Files

Create an initialization parameter file for each instance of the gateway by copying the original initialization parameter file twice, naming one with the gateway SID for dg4adbs2 and the other with the gateway SID for dg4adbs3:

$ cd $ORACLE_HOME/dg4adbs/admin$ cp initdg4adbs.ora initdg4adbs2.ora$ cp initdg4adbs.ora initdg4adbs3.ora

Change the value of the HS_FDS_CONNECT_INFO parameter in the new files.

For initdg4adbs2.ora, enter the following:

HS_FDS_CONNECT_INFO="mvs5:2551"

For initdg4adbs3.ora, enter the following:

HS_FDS_CONNECT_INFO="mvs5:2551"

10.6.2 Multiple Databases Example: Configuring Oracle Net Services Listener

Add Entries to listener.ora

Add two new entries to the Oracle Net Listener configuration file, listener.ora. You must have an entry for each gateway instance, even when multiple gateway instances access the same database.

The following example shows the entry for the original installed gateway first, followed by the new entries:

SID_LIST_LISTENER=
(SID_LIST=
   (SID_DESC=
      (SID_NAME=dg4adbs)
      (ORACLE_HOME=ORACLE_HOME_directory)
      (PROGRAM=dg4adbs)
   )
   (SID_DESC=
      (SID_NAME=dg4adbs2)
      (ORACLE_HOME=ORACLE_HOME_directory)
      (PROGRAM=dg4adbs)
   )
   (SID_DESC=
      (SID_NAME=dg4adbs3)
      (ORACLE_HOME=ORACLE_HOME_directory)
      (PROGRAM=dg4adbs)
   )
)

10.6.3 Multiple Databases Example: Stopping and Starting the Oracle Net Listener

If the listener is already running, use the lsnrctl command to stop the listener and then start it with the new settings, as follows:

$ lsnrctl stop$ lsnrctl start

10.6.4 Multiple Databases Example: Configuring the Oracle Database for Gateway Access

This section describes the required procedures to configure the Oracle Database for the gateway access.

old_db_using=(DESCRIPTION=
              (ADDRESS=
                (PROTOCOL=TCP)
                (PORT=1541)
                (HOST=gtwhost))
                (CONNECT_DATA=
                    (SID=dg4adbs))
               (HS=OK))
new_Adabas2_using=(DESCRIPTION=
              (ADDRESS=
                (PROTOCOL=TCP)
                (PORT=1541)
                (HOST=gtwhost))
                (CONNECT_DATA=
                    (SID=dg4adbs2))
                (HS=OK))
new_Adabas3_using=(DESCRIPTION=
              (ADDRESS=
                (PROTOCOL=TCP)
                (PORT=1541)
                (HOST=gtwhost))
                (CONNECT_DATA=
                    (SID=dg4adbs3))
                (HS=OK)) 

10.6.5 Multiple Databases Example: Accessing Adabas Data

Enter the following to create a database link for the dg4adbs2 gateway:

SQL> CREATE PUBLIC DATABASE LINK Adabas2 CONNECT TO
  2  user2 IDENTIFIED BY password2 USING 'new_Adabas2_using';

Enter the following to create a database link for the dg4adbs3 gateway:

SQL> CREATE PUBLIC DATABASE LINK Adabas3 CONNECT TO
  2  user3 IDENTIFIED BY password3 USING 'new_Adabas3_using';

After the database links are established you can query the new Adabas databases, as in the following:

SQL> SELECT * FROM ALL_TABLES@Adabas2;

Or

SQL> SELECT * FROM ALL_TABLES@Adabas3;

10.7.1 Configuring for Global Transactions

The gateway supports the following transaction capabilities:

• READ_ONLY

• SINGLE_SITE (default)

See the Oracle Database Heterogeneous Connectivity Administrator's Guide for configuration information.

10.7.2 Enabling Automatic Recovery

For the gateway to recover distributed transactions, a recovery account and password must be set up in the Adabas data source. By default, both the user name of the account and the password are RECOVER. The name of the account can be changed with the gateway initialization parameter HS_FDS_RECOVERY_ACCOUNT. The account password can be changed with the gateway initialization parameter HS_FDS_RECOVERY_PWD.

1. Set up a user account in the Adabas data source. Both the user name and password must be a valid Adabas user name and password.

2. In the initialization parameter file, set the following gateway initialization parameters:

   • HS_FDS_RECOVERY_ACCOUNT to the user name of the Adabas user account you set up for recovery.

   • HS_FDS_RECOVERY_PWD to the password of the Adabas user account you set up for recovery.

     See Also:

     "Customize the Initialization Parameter File" for information about editing the initialization parameter file and Appendix B, "Initialization Parameters" for information about the HS_FDS_RECOVERY_ACCOUNT and HS_FDS_RECOVERY_PWD initialization parameters.