Skip Headers
Oracle® Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide
11g Release 2 (11.2) for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64

Part Number E12076-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

10 Configuring Oracle Database Gateway for Adabas

After installing the gateway, perform the following tasks to configure the gateway for Adabas:

Configuring the Gateway

Perform the following tasks to configure Oracle Database Gateway for Adabas:

  1. Choose a System Identifier for the Gateway

  2. Customize the Initialization Parameter File

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.

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.

See Also:

The Oracle Database Heterogeneous Connectivity User's Guide for more information about customizing the initialization parameter file.

Configuring Oracle Net Services Listener for the Gateway

The gateway requires Oracle Net Services to provide transparent data access. After configuring the gateway, configure Oracle Net Services to work with the gateway.

  1. Configure Oracle Net Services Oracle Net Listener for the Gateway

  2. Stop and Start the Oracle Net Listener for the Gateway

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

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

Note:

If Oracle Net Services is reinstalled, the original listener.ora file is renamed and a new listener.ora file is put into the same directory.

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.

Example of Address to Listen On in listener.ora File

The Oracle Database accesses the gateway using Oracle Net Services and the TCP/IP protocol adapter. The following is the syntax of the connect descriptor entry in the listener.ora file:

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

Where:

Table 10-1 Parameters for listener.ora File

Variable Description

host_name

is the name of the system on which the gateway is installed.

port

specifies the port number used by the Oracle Net Listener. If you have other listeners running on host_name, the value of port_number must be different from the other listeners' port numbers.


Example of Gateway to Start in listener.ora File

To direct the Oracle Net Listener to start the gateway in response to incoming connection requests, add an entry to the listener.ora file as follows.

Use the following syntax for Linux platforms:

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)
  )
)

Where:

Table 10-2 Parameters for listener.ora File

Variable Description

sid_name

The SID of the gateway and matches the gateway SID specified in the connect descriptor entry in the tnsnames.ora file. The Oracle Net Listener uses the SID name to locate the relevant <sid_name>.ora file.

ORACLE_HOME

The Oracle home directory where the gateway is located.


The following table specifies which ENVS parameter value to use for the different platforms:

Platform ENVS Parameter Value
Sun Solaris 64-bit LD_LIBRARY_PATH=$ORACLE_HOME/lib
HP-UX Itanium 64-bit SHLIB_PATH=$ORACLE_HOME/lib
IBM AIX 64-bit LIBPATH=$ORACLE_HOME/lib
Linux 32-bit LD_LIBRARY_PATH=$ORACLE_HOME/lib
Linux 64-bit LD_LIBRARY_PATH=$ORACLE_HOME/lib

See Also:

Oracle Database Net Services Administrator's Guide for information about changing the listener.ora file.

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.2.0 - Production on 01-JUN-2009 09:16:17

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

Connecting to (ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=11201))
STATUS of the LISTENER
----------------------
Alias                    listener
Version                  TNSLSNR for SOLARIS: Version 11.2.0 - Production
Start Date               31-May-2009 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=11201)))
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.

Note:

You must use the same SID value in the tnsnames.ora file, and the listener.ora file.

Configuring the Oracle Database for Gateway Access

Before you can use the gateway to access Adabas data, you must configure the Oracle Database to enable communication with the gateway over Oracle Net Services.

Perform the following tasks to configure the Oracle Database accordingly:

Configuring Oracle Net Services for the Oracle Database

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.

See Also:

Oracle Database Net Services Administrator's Guide for information about editing the tnsnames.ora file.

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.

Configuring tnsnames.ora

Edit the tnsnames.ora file to add a connect descriptor for the gateway. The following is an example of the Oracle Net Services entries using TCP/IP protocol needed for the Oracle Database to access the gateway:

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

Where:

Table 10-3 Parameters for tnsnames.ora File

Variable Description

connect_descriptor

The description of the object to connect to as specified when creating the database link, such as dg4adbs.

Check the sqlnet.ora file for the following parameter setting:

names.directory_path = (TNSNAMES)

Note: The sqlnet.ora file is typically stored in $ORACLE_HOME/network/admin.

host_name

Specifies the system where the gateway is running.

port_number

Matches the port number used by the Oracle Net Services Oracle Net Listener that is listening for the gateway. The Oracle Net Listener's port number can be found in the listener.ora file used by the Oracle Net Listener. See "Example of Address to Listen On in listener.ora File".

gateway_sid

Specifies the SID of the gateway and matches the SID specified in the listener.ora file of the Oracle Net Listener that is listening for the gateway. See "Configure Oracle Net Services Oracle Net Listener for the Gateway" for more information.


For example:

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

Creating Database Links

Any Oracle client connected to the Oracle Database can access Adabas data through the gateway. The Oracle client and the Oracle Database can reside on different systems. The gateway accepts connections only from the Oracle Database.

A connection to the gateway is established through a database link when it is first used in an Oracle session. In this context, a connection refers to the connection between the Oracle Database and the gateway. The connection remains established until the Oracle session ends. Another session or user can access the same database link and get a distinct connection to the gateway and Adabas database.

Database links are active for the duration of a gateway session. If you want to close a database link during a session, you can do so with the ALTER SESSION CLOSE DATABASE LINK dblink statement. The database and application administrators of a distributed database system are responsible for managing the necessary database links that define paths to the Adabas database.

Gateway Password Encryption Tool

The gateway uses userids and passwords to access the information in the remote database. Some userids and passwords must be defined in the Gateway Initialization File to handle functions such as resource recovery. In the current security conscious environment, having plain-text passwords that are accessible in the Initialization File is considered insecure. The dg4pwd encryption utility has been added as part of Heterogeneous Services' generic connectivity to help make this more secure. This utility is accessible by this gateway. The initialization parameters that contain sensitive values can be stored in an encrypted form.

See Also:

Oracle Database Heterogeneous Connectivity User's Guide for more information about using this utility.

Configuring the Gateway for Multiple Adabas Databases

The tasks for configuring the gateway to access multiple Adabas databases are similar to the tasks for configuring the gateway for a single database. The configuration example assumes the following:

Configuring the gateway for additional Adabas databases is similar to configuring it for one database, and involves the following:

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"

Note:

If you have multiple gateway SIDs for the same Adabas database because you want to use different gateway parameter settings at different times, follow the same procedure. You create several initialization parameter files, each with different SIDs and different parameter settings.

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)
   )
)

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

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.

Configuring Oracle Net Services on the Oracle Database for Multiple Gateway Instances

Add two connect descriptor entries to the tnsnames.ora file. You must have an entry for each gateway instance, even if the gateway instances access the same database.

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

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)) 

The value for PORT is the TCP/IP port number of the Oracle Net Listener that is listening for the gateway. The number can be found in the listener.ora file used by the Oracle Net Listener. The value for HOST is the name of the system on which the gateway is running. The name also can be found in the listener.ora file used by the Oracle Net Listener.

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';

Note:

To encrypt the initialization parameters that would normally be stored in the initialization file in plain text, you must use the dg4pwd utility, as described in Oracle Database Heterogeneous Connectivity User's Guide.

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;

Performing Configuration Tasks

You can perform the following configuration tasks:

Configuring for Global Transactions

The gateway supports the following transaction capabilities:

  • READ_ONLY

  • SINGLE_SITE (default)

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

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.

Note:

Oracle Corporation recommends that you do not use the default value RECOVER for the user name and password. Moreover, storing plain text as user name and password in the initialization file is not a good security policy. There is now a utility called dg4pwd that should be used for encryption. Refer to Chapter 4, "Encrypting Initialization parameters" in Oracle Heterogeneous Connectivity Administration Guide for details.
  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.

Testing the Adabas Data Source

Set the debug environment generalTrace parameter to true to generate entries in the standard log racing the access to Adabas data.

See Also:

Setting Up an Adabas Data Source for information on how to add a data source.

Figure 10-1 Adabas Log Entry Format

This image shows the Adabas log format
Description of "Figure 10-1 Adabas Log Entry Format"