Skip Headers
Oracle® Transparent Gateway for Ingres II Administrator's Guide
10g Release 2 (10.2) for HP-UX

Part Number B14277-01
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

2 Configuring the Gateway

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

2.1 Configuring the Gateway

Perform the following tasks to configure the Oracle Transparent Gateway for Ingres II.

2.1.1 Task 1: Choose a System Identifier for the Gateway

The gateway system identifier (SID) is an alphanumeric character string that identifies a gateway instance. You need one gateway instance, and therefore one gateway SID, for each Ingres II database you are accessing. The SID is used as part of the file name for the initialization parameter file. The default SID is tg4ingr.

You can define a gateway SID, but using the default of tg4ingr is easier because you do not need to change the initialization parameter file name. However, if you want to access two Ingres II databases, you need two gateway SIDs, one for each instance of the gateway. If you have one Ingres II database 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 having multiple gateway SIDs for the single Ingres II database.

2.1.2 Task 2: Customize the Initialization Parameter File

The initialization parameter file must be available when the gateway is started. During installation, the following default initialization parameter file is created:

$ORACLE_HOME/tg4ingr/admin/inittg4ingr.ora

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

If you are not using tg4ingr 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 Ingres II connection as follows:

HS_FDS_CONNECT_INFO=vnode::database_name

Where vnode is the virtual node which will be used by the Ingres II client to access a remote networked Ingres II server. You can retrieve a list of the available nodes on the machine by running the Ingres II net_util utility.

If you specify only database_name, omitting vnode, the gateway binds to the specified local database.

Also, in the initialization parameter file, specify the Ingres II database mode as follows:

HS_FDS_INGRES_MODE=mode

Where mode is the Ingres II database mode that was specified when the Ingres II database was installed; either INGRES or ANSI mode.

Additionally, set the Ingres II environment variable, as follows:

SET II_SYSTEM=ingres_parent_dir

Make sure that the files in the Ingres II parent directory are readable by every one and that users defined in the Ingres II database are defined with the correct permissions. If the correct permissions are not set, the following error occurs:

II_SS01007_PRIV_NOT_GRANTED

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

See Also:

Appendix D, "Heterogeneous Services Initialization Parameters" and the Oracle Database Heterogeneous Connectivity Administrator's Guide for more information about customizing the initialization parameter file.

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

2.2.1 Task 1: Configure Oracle Net Services TNS Listener for the Gateway

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

The TNS listener listens for incoming requests from the Oracle database server. For the TNS listener to listen for the gateway, information about the gateway must be added to the TNS listener configuration file, listener.ora. This file is located in $ORACLE_HOME/network/admin, where $ORACLE_HOME is the directory under which the gateway is installed.

Note:

If Oracle Net Services is reinstalled, the original listener.ora file is renamed and a new listener.ora file is put into the $ORACLE_HOME/network/admin directory.

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

  • A list of Oracle Net Services addresses on which the TNS listener listens

  • The gateway that the TNS listener starts in response to incoming connection requests

2.2.1.1 Example of Address to Listen On in listener.ora File

The Oracle database server 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=
        (ADDRESS= 
          (PROTOCOL=TCP)
          (HOST=host_name)
          (PORT=port_number))

Where:

Value Description
host_name is the name of the machine on which the gateway is installed.
port_number specifies the port number used by the TNS listener. If you have other listeners running on host_name, the value of port_number must be different from the other listeners' port numbers.

2.2.1.2 Example of Gateway to Start in listener.ora File

To direct the TNS listener to start the gateway in response to incoming connection requests, add an entry to the listener.ora file with the following syntax:

SID_LIST_LISTENER=
   (SID_LIST=
      (SID_DESC= 
         (SID_NAME=gateway_sid)
         (ORACLE_HOME=oracle_home_directory)
         (PROGRAM=tg4ingr)
          (ENVS=SHLIB_PATH=ingres_parent_dir/ingres/lib:                                           oracle_home_directory/lib32)
      )
   )

Where:

Value Description
gateway_sid specifies the SID of the gateway and matches the gateway SID specified in the connect descriptor entry in the tnsnames.ora file.
oracle_home_directory specifies the Oracle home directory where the gateway resides.
tg4ingr specifies the Oracle Transparent Gateway for Ingres II.
ingres_parent_dir specifies the value of the II_SYSTEM environment variable.

If you are already running a TNS listener that listens on multiple database SIDs, add only the following syntax to SID_LIST in the existing listener.ora file:

SID_LIST_LISTENER=
(SID_LIST= 
   (SID_DESC=.
     .
   )
   (SID_DESC=.
     .
   )
   (SID_DESC=
      (SID_NAME=gateway_sid)
      (ORACLE_HOME=oracle_home_directory)
      (PROGRAM=tg4ingr)
       (ENVS=SHLIB_PATH=ingres_parent_dir/ingres/lib:                                           oracle_home_directory/lib32)
   )
)

See Also:

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

2.2.2 Task 2: Stop and Start the TNS Listener for the Gateway

The TNS listener must be started to initiate the new settings, as follows:

  1. Set the PATH environment variable to access the commands in the directory $ORACLE_HOME/bin where the gateway is installed. If you have the Bourne or Korn Shell, enter the following:

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

    If you have the C Shell, enter the following:

    $ setenv PATH $ORACLE_HOME/bin:$PATH
    $ setenv SHLIB_PATH $ORACLE_HOME/lib:$SHLIB_PATH
    
    
  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 HPUX: Version 10.2.0.1.0 - Production on 01-JUN-2005 09:16:17Copyright (c) 1991, 2004, Oracle. All rights reserved.Connecting to (ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=1551))STATUS of the LISTENER----------------------Alias                    listenerVersion                  TNSLSNR for HPUX: Version 10.2.0.1.0 - ProductionStart Date               31-MAY-2005 10:16:17Uptime                   0 days 2 hr. 10 min. 25 secTrace Level              offSecurity                 OFFSNMP                     OFFListener Parameter File  /users/oracle/gateway/network/admin/listener.oraListener Log File        /users/oracle/gateway/network/log/listener.logListening Endpoints Summary...  (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=1551)))Services Summary...Service "tg4ingr" has 1 instance(s).  Instance "tg4ingr", status UNKNOWN, has 1 handler(s) for this service...The command completed successfully

In this example, tg4ingr 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, the listener.ora file.

2.3 Configuring the Oracle Database Server for Gateway Access

Before you use the gateway to access Ingres II data you must configure the Oracle database server to enable communication with the gateway over Oracle Net Services.

2.3.1 Configuring Oracle Net Services for the Oracle Database Server

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 Administrator's Guide for information about editing the tnsnames.ora file.

For the Oracle database server 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 server 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 server is installed. The tnsnames.ora file is required by the Oracle database server accessing the gateway, but not by the gateway.

2.3.1.1 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 server to access the gateway:

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

Where:

Value Description
connect_descriptor is the description of the object to connect to as specified when creating the database link, such as tg4ingr.

Check the sqlnet.ora file for the parameter setting names.directory_path = (TNSNAMES)

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

TCP is the TCP protocol used for TCP/IP connections.
host_name specifies the machine where the gateway is running.
port_number matches the port number used by the Oracle Net Services TNS listener that is listening for the gateway. The TNS listener's port number can be found in the listener.ora file used by the TNS 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 TNS listener that is listening for the gateway. See "Task 1: Configure Oracle Net Services TNS Listener for the Gateway" for more information.
(HS=OK) specifies that this connect descriptor uses the Oracle Heterogeneous Services option.

2.4 Creating Database Links

Any Oracle client connected to the Oracle database server can access Ingres II data through the gateway. The Oracle client and the Oracle database server can reside on different machines. The gateway accepts connections only from the Oracle database server.

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 server 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 Ingres II 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 statement. The database and application administrators of a distributed database system are responsible for managing the necessary database links that define paths to the Ingres II database.

See Also:

Oracle Database Administrator's Guide and Oracle Database Heterogeneous Connectivity Administrator's Guide for more information about using database links.

2.5 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 deemed insecure. The tg4pwd 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 which contain sensitive values can be stored in an encrypted form.

See Also:

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

2.6 Configuring the Gateway for Multiple Ingres II Databases

The tasks for configuring the gateway to access multiple Ingres II 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 Ingres II databases is similar to configuring it for one database, and involves the following:

2.6.1 Multiple Databases Example: Configuring the Gateway

Choose Two System IDs for Each Ingres II Database

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

  • tg4ingr2 for the gateway accessing database db2

  • tg4ingr3 for the gateway accessing database db3

Create Two Initialization Parameter Files

Create an initialization parameter file for each instance of the gateway by copying twice the original initialization parameter file:

$ORACLE_HOME/tg4ingr/admin/inittg4ingr.ora

Naming one with the gateway SID for db2 and the other with the gateway SID for db3, as follows:

$ cd $ORACLE_HOME/tg4ingr/admin$ cp inittg4ingr.ora inittg4ingr2.ora$ cp inittg4ingr.ora inittg4ingr3.ora

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

For inittg4ingr2.ora, enter the following:

HS_FDS_CONNECT_INFO=vnode::db2

For inittg4ingr3.ora, enter the following:

HS_FDS_CONNECT_INFO=vnode::db3

Note:

If you have multiple gateway SIDs for the same Ingres II 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.

2.6.2 Multiple Databases Example: Configuring the Ingres II Environment

Set the Ingres II environment variables in both of the new initialization parameter files, as follows:

For inittg4ingr2.ora, enter the following:

SET II_SYSTEM=ingres_parent_dir

For inittg4ingr3.ora, enter the following:

SET II_SYSTEM=ingres_parent_dir

2.6.3 Multiple Databases Example: Configuring Oracle Net Services Listener

Add Entries to listener.ora

Add two new entries to the TNS 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=tg4ingr)
      (ORACLE_HOME=oracle_home_directory)
      (PROGRAM=tg4ingr)
       (ENVS=SHLIB_PATH=ingres_parent_dir/ingres/lib:oracle_home_directory/lib32))
   (SID_DESC=
      (SID_NAME=tg4ingr2)
      (ORACLE_HOME=oracle_home_directory)
      (PROGRAM=tg4ingr)
       (ENVS=SHLIB_PATH=ingres_parent_dir/ingres/lib:oracle_home_directory/lib32))
   (SID_DESC=
      (SID_NAME=tg4ingr3)
      (ORACLE_HOME=oracle_home_directory)
      (PROGRAM=tg4ingr)
       (ENVS=SHLIB_PATH=ingres_parent_dir/ingres/lib:oracle_home_directory/lib32))
)

2.6.4 Multiple Databases Example: Stopping and Starting the TNS 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

2.6.5 Multiple Databases Example: Configuring the Oracle Database Server for Gateway Access

To configure Oracle Net Services on the Oracle Database Server 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 Ingres II 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=tg4ingr))
               (HS=OK))
new_db2_using=(DESCRIPTION=
              (ADDRESS=
                (PROTOCOL=TCP)
                (PORT=1541)
                (HOST=gtwhost))
                (CONNECT_DATA=
                    (SID=tg4ingr2))
                (HS=OK))
new_db3_using=(DESCRIPTION=
              (ADDRESS=
                (PROTOCOL=TCP)
                (PORT=1541)
                (HOST=gtwhost))
                (CONNECT_DATA=
                    (SID=tg4ingr3))
                (HS=OK)) 

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

2.6.6 Multiple Databases Example: Accessing Ingres II Data

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

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

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

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

Note:

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

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

SQL> SELECT * FROM ALL_USERS@INGR2;

Or

SQL> SELECT * FROM ALL_USERS@INGR3;