8
Configuring the Gateway

After you have installed the gateway, configured your DRDA server, and configured your SNA or TCP/IP software, then you must configure the gateway.  Some of these tasks involve customizing the Gateway Initialization File.

This chapter includes the following sections:

• Configuration Checklists

• Choosing a Gateway System Identifier (SID)

• Gateway Configuration and the Startup Shell Script

• Configuring the RS/6000 Host

• DRDA Gateway Package Considerations

• Backup and Recovery of Gateway Configuration

• Configuring the Integrating Oracle Server

• Accessing the Gateway from Other Oracle Servers

• Accessing Other DRDA Servers

Configuration Checklists

Configuring the Gateway

Choose a Gateway System Identifier (SID)

Configuring the RS/6000 Host

Step 1: Choose an appropriate Startup Shell Script

Step 2: Create the gateway Startup Shell Script

Step 3: Tailor the startup Shell Script

Binding the DRDA Gateway Package

Step 1: Log on to an integrating Oracle Server

Step 2: Create a Database link

Step 3: Execute the stored procedure GTW$_BIND_PKG

Binding Packages on DB2/Universal Database (DB2/UDB)

Step 1: Log into the machine where DB2/UDB is running

Step 2: Copy files from the $ORACLE_HOME/tg4drda/install/db2udb directory

Step 3: Connect to the database using the user ID that you will use for binding the package:

Step 4: Create the ORACLE2PC table:

Step 5: Commit the transaction:

Step 6: Optionally, verify the table was created under the correct user ID:

Step 7: Disconnect from the session:

Before Binding the DRDA Gateway Package

Step 1: Check all DRDA parameter settings

Step 2: If using DB2/UDB, then create ORACLE2PC table

Sample SQL scripts

Step 1: Remove obsolete tables and views

Step 2: Replace current table and views

Step 3: If server is DB2/MVS, then run data dictionary scripts

Step 4a: If server is DB2/UDB, grant authority to package

Step 4b: If server is not DB2/UDB, create the ORACLE2PC table

Configuring the Integrating Oracle Server

Step 1: Create a database link

Step 2: Create synonyms and views

Accessing the Gateway from Other Oracle Servers

Step 1: Create a database link with which to access the gateway.

Step 2: If needed, define synonyms and views for tables accessed through the gateway.

Step 3: Perform GRANT statements for the synonyms and views you create.

Accessing Other DRDA Servers

Step 1: Configure another APPC profile set for the DRDA server

Step 2: Configure additional DRDA server instances

Step 3: Bind the DRDA package to your DRDA server.

Note: Ensure the caths.sql script has been run on the Oracle 9i Server before starting the gateway.  You can verify that this has been done by doing the following: Use SQL*Plus to connect to the integrating Oracle Server as user SYS. Issue the following statement from SQL*Plus: DESCRIBE HS_FDS_INST If the DESCRIBE statement is successful, then it is an indication that caths.sql has been run for the database server.  Otherwise, you must run the caths.sql script first.

Choosing a Gateway System Identifier (SID)

The gateway SID is a string of alphabetic and numeric characters that identifies a gateway instance.  The SID is used in the filenames of gateway parameter files and in the connection information associated with the Oracle server database links that access the gateway. 

A separate SID is required for each DRDA server to be accessed.  You might also have multiple SIDs for one DRDA server to use different gateway parameter settings with that server.  Refer to "Accessing Other DRDA Servers" for information on configuring additional SIDs.

Gateway Configuration and the Startup Shell Script

The data in this chapter describe the configuration process for the gateway.  You should notice that most, if not all, gateway parameters may be moved into the initsid.ora initialization file, which would allow you to omit the Startup Shell Script.  However, the Startup Shell Script provides an environment for troubleshooting and debugging if any problems occur with the gateway.  The only advantage of removing the Startup Shell Script is a small decrease in gateway startup time.  If this decrease in startup time is important to you in your usage of the gateway, then please contact Oracle Support Services for details on further configuration in this manner.

Configuring the RS/6000 Host

To configure the RS/6000 host for the Oracle Transparent Gateway for IBM DRDA, you tailor the parameter files for your installation.

Step 1: Choose an appropriate Startup Shell Script

In previous versions of the gateway, the initialization parameters were stored in files named initsid.ora and initsid.gtwboot in the gateway instance directories.  With version 9i of the gateway, most parameters that were in initsid.gtwboot have been moved to a Startup Shell Script file.  The syntax of the Startup Shell Script is that of the UNIX Bourne shell.  The syntax of the initsid.ora has been simplified.  Refer to Appendix C for details.

When migrating from previous releases of Oracle Transparent Gateway for IBM DRDA, please be aware of these differences.

First, choose a model startup shell script.  Samples are stored in the $ORACLE_HOME/tg4drda/admin directory.  The following list shows the startup shell scripts for various DRDA server platforms:

• sample startup shell script for DB2/MVS: drdaDB2.sh

• sample startup shell script for DB2/UDB: drdaDB2UDB.sh

• sample startup shell script for DB2/400: drdaAS400.sh

• sample startup shell script for DB2/VM: drdaDB2VM.sh

Step 2: Create the gateway Startup Shell Script

In previous versions of the gateway, a startup program was provided, named g4drdrv.  This program was specified at the PROGRAM parameter in the listener.ora file.  This program also was responsible for reading the initsid.gtwboot and starting the gateway server itself.

In version 9i of the gateway, this process has been moved to a shell script.  Most of the init parameters that were stored in the initsid.gtwboot are now stored in this Startup Shell Script, and the name of the script will now be used as the PROGRAM parameter in the listener.ora file.  Sample scripts, named 'drdaXXX.sh' are stored in the $ORACLE_HOME/tg4drda/admin directory.  Copy one to a name of your choosing and move it to the $ORACLE_HOME/bin directory.  For example:

$ cp $ORACLE_HOME/tg4drda/admin/drdaDB2.sh $ORACLE_HOME/bin/drdahoa1.sh 

Hint:

Oracle suggests naming the shell script the same as the SID for the gateway in order to make name associations easier.

Step 3: Tailor the Startup Shell Script

The Startup Shell Script file contains parameters that govern:

• The UNIX environment in which the gateway process runs, including NLS-related parameters.  See Appendix D for information on tailoring the parameters for NLS.

• The environment variable settings needed by SNA server software to initialize the gateway APPC interface.

Customize the file you created in Step 2 as needed to tailor the Startup Shell Script file for your installation.

NOTE: if you are using TCP/IP, then do not perform the following instructions for changing environmental variable settings.

Binding the DRDA Gateway Package

The product requires a package to be bound on the DRDA server.  The gateway has an internal, stored procedure which must be used to create this package.  The internal, stored procedure is invoked from an integrating Oracle Server.  (Refer to "Configuring Oracle Net".  Also refer to "Configuring the Integrating Oracle Server" in this chapter.) Before this package can be bound on the DRDA server, the Gateway Initialization File must be correctly configured, and a Startup Shell Script must be chosen and configured (refer to Appendix C, "DRDA-Specific Parameters").

1. First, log on to an integrating Oracle Server, using either SQL*Plus or Server Manager:

   $ sqlplus system/manager 
   

2. Next, create a Database link with a user ID and with a password that has proper authority on the DRDA server to create packages.

   SQL> CREATE PUBLIC DATABASE LINK dblink 
   2 CONNECT TO userid IDENTIFIED BY password 
   3 USING tns-name-entry
   

   Note: The user ID creating the public database link must have the "CREATE PUBLIC DATABASE LINK" privilege.

Refer to "Configuring the Integrating Oracle Server" for more information.

3. Next, 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.

Binding Packages on DB2/Universal Database (DB2/UDB)

If you are connecting to a DB2/UDB DRDA server, then DB2/UDB requires that you create the ORACLE2PC table before binding the DRDA package.  Other DRDA servers allow you to bind the package before the ORACLE2PC table exists.

To create the ORACLE2PC table:

1. Log into the machine where DB2/UDB is running.  Check that you have the ability to address the DB2/UDB instance where the ORACLE2PC table will reside.

2. Copy the following files from the $ORACLE_HOME/tg4drda/install/db2udb directory:
   • o2pc.sh (Sample shell script for performing the table creation)

   • o2pc.sql (SQL script for creating the table)

   • o2pcg.sql (SQL script for granting package access to PUBLIC)

3. Connect to the database using the user ID that you will use for binding the package:

   $ db2 'CONNECT TO database USER userid USING password' 
   

   Note that the user ID must have CONNECT, CREATETAB, and BINDADD authority to be able to connect to the database, create the table, and create the package.

4. Create the ORACLE2PC table:

   $ db2 -tf o2pc.sql
   

5. Commit the transaction:

   $ db2 'COMMIT'
   

6. Optionally, verify the table was created under the correct user ID:

   $ db2 'LIST TABLES FOR USER'
   $ db2 'COMMIT'
   

7. Disconnect from the session:

   $ db2 'DISCONNECT CURRENT'
   

DRDA Gateway Package Considerations

The DRDA package must be bound with the internal Stored Procedure GTW$_BIND_PKG.  You must perform this bind step if this release is the first time the gateway has been installed on this system.  If you are upgrading from version 4 of the gateway, then a rebind is not necessary unless the initialization parameters have been changed. 

The user ID used to bind or rebind the DRDA package must have the appropriate privileges on the remote database, as described in Chapter 6, "Configuring the DRDA Server".

Before Binding the DRDA Gateway Package

Step 1: 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 for information on the parameters and their settings.

Step 2: If using DB2/UDB, then create ORACLE2PC table

If your DRDA server is DB2/UDB, then create your ORACLE2PC table.  Refer to "Binding Packages on DB2/Universal Database (DB2/UDB)" for information on creating the table.

Sample SQL scripts

SQL scripts are provided to perform steps such as creating the ORACLE2PC table, removing obsolete tables and views, using previous releases, and creating tables and views to provide Data Dictionary support. 

Choose the appropriate subdirectory for your DRDA server platform from the following list:

• for DB2/MVS: choose tg4drda/install/db2

• for DB2/400: choose tg4drda/install/as400

• for DB2/VM: choose tg4drda/install/db2vm

• for DB2/UDB: choose tg4drda/install/db2udb

These scripts must be run on the DRDA server platform using a database native tool (such as SPUFI on DB2/MVS), because no tool is provided with the gateway to execute these scripts.  Note that when running these scripts, the user ID used must be suitably authorized.

Step 1: Remove obsolete tables and views

If you have previously installed a V3 or older TG4DRDA product, then you should run dropold.sql for each user.

Step 2: Replace current table and views

If you previously installed the gateway, then run v3delvw.sql

Step 3: If server is DB2/MVS or DB2/400, then run data dictionary scripts

If your DRDA server is DB2/MVS or DB2/400, then run the following scripts to create the Data Dictionary tables and view:

• g4ddtab.sql and

• g4ddview.sql

Step 4: DB2/UDB or other server

Depending on your DRDA server, perform one of the following steps:

Step 4a: If server is DB2/UDB, grant authority to package

If your DRDA server is DB2/UDB, then the ORACLE2PC table has already been created (see the previous sections).  For all users to be able to use the table, run o2pcg.sql granting authority to all users.

Step 4b: If server is not DB2/UDB, create the ORACLE2PC table

If your DRDA server is not DB2/UDB, then the ORACLE2PC table must be created.  Run o2pc.sql.

Backup and Recovery of Gateway Configuration

The configuration of the gateway is stored in the Gateway Initialization File and in the Startup Shell Script.  These are stored in $ORACLE_HOME/tg4drda/admin and $ORACLE_HOME/bin, respectively.  Since they are simple files, you may back them up using an archiving tool of your choice.

Configuring the Integrating Oracle Server

Configure the integrating Oracle Server, regardless of the platform on which it is installed.  It can be on the RS/6000 host, but this is not required.

Note: Ensure the caths.sql script has been run on the Oracle 9i Server before starting the gateway.  You can verify that this has been done by doing the following: Use SQL*Plus to connect to the integrating Oracle Server as user SYS. Issue the following statement from SQL*Plus: DESCRIBE HS_FDS_INST If the DESCRIBE statement is successful, then it is an indication that caths.sql has been run for the database server.  Otherwise, you must run the caths.sql script first.

Step 1: Create a database link

To access the DRDA server, you must create a public database link.  A public database link is the most common of database links.  Refer to "Processing a Database Link" for information on creating database links.  In the following example, the Oracle server gateway is on the same RS/6000 host.  Replace linkname with the name you used for the database link when you added your entry to the tnsnames.ora file (refer to Chapter 5, "Oracle Net", "Step 2: Modify tnsnames.ora file").

CREATE PUBLIC DATABASE LINK DB2 USING `tns_name_entry` 

Note: The user ID creating the public database link must have the "CREATE PUBLIC DATABASE LINK" privilege.

Step 2: Create synonyms and views

To facilitate accessing data using the gateway, define synonyms and views for the DRDA data tables.  If needed, perform GRANT statements to ensure that the synonyms and views are accessible to the appropriate groups of users.  Refer to "Using the Synonym Feature" for information.

Accessing the Gateway from Other Oracle Servers

Perform the following steps for each of the Oracle servers from which you want to access the gateway:

1. Create a database link with which to access the gateway.

2. If needed, define synonyms and views for tables accessed through the gateway.

3. Perform GRANT statements for the synonyms and views you create.

Provide local or Oracle Net access from the Oracle servers to the gateway.

Accessing Other DRDA Servers

To access other DRDA servers from the integrating Oracle Server, use the following steps:

1. Configure another APPC profile set for the DRDA server.  Only Side Information and Partner LU Profiles must be new.  You can point to existing configuration information for other profiles, unless you need to modify other aspects of the connection.  For example, if you are using a different network adapter, then you must configure an entire APPC profile set.

2. Configure additional DRDA server instances.  To configure an additional instance, create new Startup Shell Scripts.  If you are using Oracle Net, then add entries to the listener.ora file and tnsnames.ora file with the new SIDs.

   Other components, including the gateway ORACLE_HOME directory structure, can be shared among multiple gateway instances.

3. Bind the DRDA package to your DRDA server.

Gateway Installation and Configuration Complete

The Oracle Transparent Gateway for IBM DRDA installation and configuration process is now complete.  The gateway is ready for use.