14 Configuring Oracle Database Gateway for DRDA

14.1.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 DRDA database you are accessing. However, if you want to access two DRDA databases, you need two gateway SIDs, one for each instance of the gateway. If you have one DRDA 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 DRDA database. The SID is used as part of the file name for the initialization parameter file.

14.1.2 Customize the Initialization Parameter File

To configure the host for the Oracle Database Gateway for DRDA, you must tailor the parameter files for your installation. Perform the following steps:

1. Choose the initsid.ora file

   The initsid.ora gateway initialization file defines the operating parameters for the gateway. Samples (tailored for each type of DRDA Server) are provided as a starting point for tailoring to your particular installation. The samples are stored in the $ORACLE_HOME/dg4drda/admin directory. The following is a list of the initialization files for various DRDA Server platforms:

   • For DB2/OS390: initDB2.ora

   • For DB2/UDB: initDB2UDB.ora

   • For DB2/400: initAS400.ora

   Choose a sample initialization file and copy it, within the same directory, using the following naming convention:

   initsid.ora
   

   where sid is the chosen gateway SID. For example, if the chosen gateway SID were DRDA, then the initialization file would be named initDRDA.ora.

2. Tailor the initsid.ora file

   After you have copied the sample initialization file, you will need to tailor it to your installation. While many parameters can be left to their defaults, some parameters must be changed for correct operation of the gateway. Attention should be given to the following DRDA and HS parameters. Attention should also be given to the security aspects of the initialization file. Chapter 15, "Security Considerations", contains details concerning encryption of passwords that would otherwise be embedded in the initialization file. See Appendix C, "Initialization Parameters", for a description of the following parameters:

   • DRDA_CONNECT_PARM

   • DRDA_PACKAGE_COLLID

   • DRDA_PACKAGE_NAME

   • DRDA_PACKAGE_OWNER

   • DRDA_REMOTE_DB_NAME

   • HS_DB_NAME

   • HS_DB_DOMAIN

   • FDS_CLASS

14.2.1 Configure Oracle Net Listener for the Gateway

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 by default 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 addresses on which the Oracle Net Listener listens

• The executable name of the gateway that the Oracle Net Listener starts in response to incoming connection requests

A sample of the listener.ora entry (listener.ora.sample) is available in the $ORACLE_HOME/dg4drda/admin directory where $ORACLE_HOME is the directory under which the gateway is installed.

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

SID_LIST_LISTENER=
(SID_LIST= 
   (SID_DESC=.
     .
   )
   (SID_DESC=.
     .
   )
   (SID_DESC=
      (SID_NAME=gateway_sid)
      (ORACLE_HOME=oracle_home_directory)
      (PROGRAM=g4drsrv)
   )
)

14.2.2 Stop and Start the Oracle Net Listener for the Gateway

You must stop and restart the Oracle Net Listener to initiate the new settings, as follows:

1. Set the PATH environment variable to $ORACLE_HOME/bin where $ORACLE_HOME is the directory in which 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
   

   Table 14-1 specifies which parameter value to use for the different platforms:

   Table 14-1 Parameter Values for UNIX Based Platforms

   Platform	Parameter Value
   Solaris (SPARC) 64 bit	LD_LIBRARY_PATH=$ORACLE_HOME/lib
   HP-UX PA-RISC	SHLIB_PATH=$ORACLE_HOME/lib
   Linux x86, and Linux x86 64 bit	LD_LIBRARY_PATH=$ORACLE_HOME/lib
   AIX	LIBPATH=$ORACLE_HOME/lib

   
   

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 a partial output from a lsnrctl status check:

.
.
.
Listening Endpoints Summary...
  (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=1551)))
Services Summary...
Service "dg4drda" has 1 instance(s).
  Instance "dg4drda", status UNKNOWN, has 1 handler(s) for this service...
The command completed successfully

In this example, the service name is dg4drda which is the default SID value assigned during installation.

14.4.1 DRDA Gateway Package Binding Considerations

Before binding the DRDA gateway package, perform the following steps:

1. Check the user has the appropriate privileges

   The DRDA package must be bound with the internal stored procedure GTW$_BIND_PKG. The user ID used to bind the DRDA package must have the appropriate privileges on the remote database, as described in Chapter 13, "Configuring the DRDA Server".

2. Check all DRDA parameter settings

   Check all DRDA parameter settings to be sure that they are set correctly before you start the bind. For example, the default for DRDA_DISABLE_CALL only works if your DRDA database supports stored procedures. If not, then you must change the setting. Also, the value for DRDA_PACKAGE_NAME must be unique if you have any older versions of the gateway installed. New packages replace any old packages with the same name, causing versions of the gateway that use the old package to fail. Refer to Appendix C, "Initialization Parameters" for information on the parameters and their settings.

14.4.2 DRDA Gateway Package Binding Steps

Perform the following steps:

1. Log on to an Oracle database.

   Use SQL*Plus:

   $ sqlplus system/manager 
   

2. Create a database link using the user ID that you chose while configuring the DRDA Server.

   SQL> CREATE PUBLIC DATABASE LINK dblink 
   2 CONNECT TO userid IDENTIFIED BY password 
   3 USING 'tns_name_entry'
   

   Note:

   The user ID that is creating the public database link must have the CREATE PUBLIC DATABASE LINK privilege.

3. Execute the stored procedure GTW$_BIND_PKG:

   SQL> exec GTW$_BIND_PKG@dblink;
   SQL> COMMIT;
   

This creates and commits the package. If any errors are reported, then correct the Gateway Initialization File parameters as needed and re-execute the bind procedure above.

14.7.1 Configuring tnsnames.ora

Edit the tnsnames.ora file to add a connect descriptor for the gateway. The following is a syntax of the Oracle Net entry using the TCP/IP protocol:

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

Where:

14.9.1 Multiple DRDA Databases Example: Configuring the Gateway

Choose One System ID for Each DRDA Database

A separate instance of the gateway is needed for each DRDA database. Each instance needs its own gateway System ID (SID). For this example, the gateway SIDs are chosen for the instances that access the DRDA databases:

• dg4drda2 for the gateway accessing database db2

• dg4drda3 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/dg4drda/admin/initdg4drda.ora, twice, naming one with the gateway SID for db2 and the other with the gateway SID for db3:

$ cd $ORACLE_HOME/dg4drda/admin$ cp initdg4drda.ora initdg4drda2.ora$ cp initdg4drda.ora initdg4drda3.ora

14.9.2 Multiple DRDA Databases Example: Configuring Oracle Net 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=dg4drda)
      (ORACLE_HOME=oracle_home_directory)
      (PROGRAM=g4drsrv)
   )
   (SID_DESC=
      (SID_NAME=dg4drda2)
      (ORACLE_HOME=oracle_home_directory)
      (PROGRAM=g4drsrv)
   )
   (SID_DESC=
      (SID_NAME=dg4drda3)
      (ORACLE_HOME=oracle_home_directory)
      (PROGRAM=g4drsrv)
   )
)

where, oracle_home_directory is the directory where the gateway resides.

14.9.3 Multiple DRDA 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

14.9.4 Multiple Databases Example: Configuring Oracle Database for Gateway Access

old_db_using=(DESCRIPTION=
              (ADDRESS=
                (PROTOCOL=TCP)
                (PORT=port_number)
                (HOST=host_name))
                (CONNECT_DATA=
                    (SID=dg4drda))
               (HS=OK))
new_db2_using=(DESCRIPTION=
              (ADDRESS=
                (PROTOCOL=TCP)
                (PORT=port_number)
                (HOST=host_name))
                (CONNECT_DATA=
                    (SID=dg4drda2))
                (HS=OK))
new_db3_using=(DESCRIPTION=
              (ADDRESS=
                (PROTOCOL=TCP)
                (PORT=port_number)
                (HOST=host_name))
                (CONNECT_DATA=
                    (SID=dg4drda3))
                (HS=OK)) 

14.9.5 Multiple DRDA Databases Example: Accessing DB2 Data

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

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

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

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

After the database links are created you can verify the connection to the new DRDA databases, as in the following:

SQL> SELECT * FROM ALL_USERS@DRDA2;

SQL> SELECT * FROM ALL_USERS@DRDA3;