2 Configuring the Gateway

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 Teradata database you are accessing. The SID is used as part of the file name for the initialization parameter file. The default SID is tg4tera.

You can define a gateway SID, but using the default of tg4tera is easier because you do not need to change the initialization parameter file name. However, if you want to access two Teradata databases, you need two gateway SIDs, one for each instance of the gateway. If you have one Teradata 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 Teradata 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/tg4tera/admin/inittg4tera.ora

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

If you are not using tg4tera 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 Teradata connection as follows:

HS_FDS_CONNECT_INFO=dsn
HS_FDS_SHAREABLE_NAME=odbc_installation_path/lib/libodbc.so
set ODBCINI = full_path_to_the_odbcini_file

Where:

• dsn is the Data Source Name defined in the odbc.ini file.

• full_path_to_the_odbcini_file is the full path location of the odbc initialization file.

• odbc_installation_path is the path where the NCR Teradata ODBC Driver is installed.

  Note that the set statement is optional as long as it is specified in the working account.

  Note:

  In the ODBC DSN set up, make sure that the DateTimeFormat parameter is set to AAA

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.

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.

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.

LISTENER=
        (ADDRESS= 
          (PROTOCOL=TCP)
          (HOST=host_name)
          (PORT=port_number))

SID_LIST_LISTENER=
   (SID_LIST=
      (SID_DESC= 
         (SID_NAME=gateway_sid)
         (ORACLE_HOME=oracle_home_directory)
         (PROGRAM=tg4tera)
         (ENVS=LD_LIBRARY_PATH=odbc_installation_path/lib:                                               oracle_home_directory/lib32)
      )
   )

SID_LIST_LISTENER=
(SID_LIST= 
   (SID_DESC=.
     .
   )
   (SID_DESC=.
     .
   )
   (SID_DESC=
      (SID_NAME=gateway_sid)
      (ORACLE_HOME=oracle_home_directory)
      (PROGRAM=tg4tera)
       (ENVS=LD_LIBRARY_PATH=odbc_installation_path/lib:                                               oracle_home_directory/lib32)
   )
)

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

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 10.2.0.1.0 - Production on 01-JUN-2005 09:28:13Copyright (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 Solaris: Version 10.2.0.1.0 - ProductionStart Date               28-APRIL-2005 15:38:56Uptime                   33 days 17 hr. 49 min. 22 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 "tg4tera" has 1 instance(s).  Instance "tg4tera", status UNKNOWN, has 1 handler(s) for this service...The command completed successfully

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

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.

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.

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

names.directory_path = (TNSNAMES)

2.6.1 Multiple Databases Example: Configuring the Gateway

Choose Two System IDs for Each Teradata Database

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

• tg4tera2 for the gateway accessing database db2.

• tg4tera3 for the gateway accessing database db3.

Create Two Initialization Parameter Files

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

$ORACLE_HOME/tg4tera/admin/inittg4tera.ora, twice, naming one with the gateway SID for db2 and the other with the gateway SID for db3:

$ cd $ORACLE_HOME/tg4tera/admin$ cp inittg4tera.ora inittg4tera2.ora$ cp inittg4tera.ora inittg4tera3.ora

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

For inittg4tera2.ora, enter the following:

HS_FDS_CONNECT_INFO=dsn2

For inittg4tera3.ora, enter the following:

HS_FDS_CONNECT_INFO=dsn3

2.6.2 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=tg4tera)
      (ORACLE_HOME=oracle_home_directory)
      (PROGRAM=tg4tera)
      (ENVS=LD_LIBRARY_PATH=odbc_installation_path/lib:                                               oracle_home_directory/lib32)
   )
   (SID_DESC=
      (SID_NAME=tg4tera2)
      (ORACLE_HOME=oracle_home_directory)
      (PROGRAM=tg4tera)
      (ENVS=LD_LIBRARY_PATH=odbc_installation_path/lib:                                               oracle_home_directory/lib32)
   )
   (SID_DESC=
      (SID_NAME=tg4tera3)
      (ORACLE_HOME=oracle_home_directory)
      (PROGRAM=tg4tera)
      (ENVS=LD_LIBRARY_PATH=odbc_installation_path/lib:                                               oracle_home_directory/lib32)
   )
)

2.6.3 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.4 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 Teradata 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=tg4tera))
               (HS=OK))
new_db2_using=(DESCRIPTION=
              (ADDRESS=
                (PROTOCOL=TCP)
                (PORT=1541)
                (HOST=gtwhost))
                (CONNECT_DATA=
                    (SID=tg4tera2))
                (HS=OK))
new_db3_using=(DESCRIPTION=
              (ADDRESS=
                (PROTOCOL=TCP)
                (PORT=1541)
                (HOST=gtwhost))
                (CONNECT_DATA=
                    (SID=tg4tera3))
                (HS=OK)) 

Where 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.5 Multiple Databases Example: Accessing Teradata Data

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

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

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

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

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

SQL> SELECT * FROM ALL_USERS@TERA2;

Or

SQL> SELECT * FROM ALL_USERS@TERA3;

2.7.1 Configuring for Two-Phase Commit

The gateway supports the following transaction capabilities:

• COMMIT_CONFIRM

• READ_ONLY

• SINGLE_SITE

By default, the gateway runs in COMMIT_CONFIRM transaction mode. When the Teradata database is updated by a transaction, the gateway becomes the commit point site. The Oracle database server commits the unit of work in the Teradata database after verifying that all Oracle databases in the transaction have successfully prepared the transaction. Only one gateway can participate in an Oracle two-phase commit transaction as the commit point site.

To enable the COMMIT_CONFIRM transaction mode, create a recovery account and password and create a log table. The log table, called HS_TRANSACTION_LOG, is where two-phase commit transactions are recorded.