Oracle Transparent Gateway for Ingres II Administrator's Guide Release 8.1.6 Part Number A82871-01 |
|
After installing the gateway, perform the following tasks to configure the gateway for Ingres II:
Perform the following tasks to configure the Oracle Transparent Gateway for Ingres II.
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.
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. If you specify only database_name, omitting vnode, the gateway binds to the specified local database.
The entry for database_name is case-sensitive. You can specify an environment variable instead of the database name if your logical database is distributed among several physical databases. The Oracle Transparent Gateway for Ingres II translates the logical name before binding. For example, a logical name (ALL_SITES) can be defined to use as the database_name for a logical database distributed among two physical databases (BOSTON_DB and PARIS_DB), as follows in the UNIX C shell:
$ setenv ALL_SITES BOSTON_DB,PARIS_DB
Additionally, set the Ingres II environment variable, as follows:
SET II_SYSTEM=
ingres_parent_dir
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 C, "Heterogeneous Services Initialization Parameters" and the Oracle8i Distributed Database Systems for more information about customizing the initialization parameter file. |
The gateway requires Net8 to provide transparent data access. After configuring the gateway, configure Net8 to work with the gateway.
Net8 uses the TNS listener to receive incoming connections from a Net8 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 $ORACLE_HOME directory under which the TNS listener is installed. This is the same $ORACLE_HOME directory under which the gateway is installed.
The following entries must be added to the listener.ora
file:
The Oracle database server accesses the gateway using Net8 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:
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)
)
)
where:
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)
)
)
The TNS listener must be started to initiate the new settings, as follows:
/bin
where the gateway is installed. If you have the Bourne or Korn Shell, enter the following:
$ PATH=$ORACLE_HOME/bin:$PATH;export PATH
If you have the C Shell, enter the following:
$ setenv PATH $ORACLE_HOME/bin:$PATH
$ set LD_LIBRARY_PATH=$II_SYSTEM/lib:$ORACLE_HOME/lib:$LD_LIBRARY_
PATH;export LD_LIBRARY_PATH
If you have the C Shell, enter the following:
$ setenv LD_LIBRARY_PATH$
II_SYSTEM/lib:$ORACLE_HOME/lib:$LD_LIBRARY_PATH
$ lsnrctl stop
$ lsnrctl start
$ lsnrctl status
The following is an example of output from a lsnrctl status check:
Connecting to (ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=1551))
STATUS of the LISTENER
----------------------
Alias LISTENER
Version TNSLSNR for Solaris: Version 8.1.6.0.0 - Production
Start Date 05-DEC-1999 14:07:29
Uptime 0 days 21 hr. 9 min. 25 sec
Trace Level off
Security OFF
SNMP OFF
Listener Parameter File /parla/test40/ingr/network/admin/listener.ora
Listener Log File /parla/test40/ingr/network/log/listener.log
Services Summary...
tg4ingr has 1 service handler(s)
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.
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.
Before you use the gateway to access Ingres II data you must configure the Oracle database server to enable communication with the gateway over Net8.
To configure the server you add connect descriptors to the tnsnames.ora
file. You cannot use the Net8 Assistant or the Net8 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.
Edit the tnsnames.ora
file to add a connect descriptor for the gateway. The following is an example of the Net8 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:
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 in the Oracle database server's $ORACLE_HOME for the following lines:
Note: If the Oracle database server is on Sun SPARC Solaris, the file is
If the |
|
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 Net8 TNS listener that is listening for the gateway. The TNS listener's port number can be found in the |
gateway_sid |
specifies the SID of the gateway and matches the SID specified in the |
|
specifies that this connect descriptor uses the Oracle Heterogeneous Services option. |
You can perform the following configuration tasks:
The gateway supports the following transaction capabilities:
By default, the gateway runs in COMMIT_CONFIRM transaction mode. When the Ingres II database is updated by a transaction, the gateway becomes the commit point site. The Oracle database server commits the unit of work in the Ingres II 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.
For the gateway to recover distributed transactions, a recovery account and password must be set up in the Ingres II database. 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.
For information about editing the initialization parameter file, see "Task 2: Customize the Initialization Parameter File" on page 4-2. For information about HS_FDS_RECOVERY_ACCOUNT and HS_FDS_RECOVERY_PWD, see Appendix C, "Heterogeneous Services Initialization Parameters".
See Also:
When configuring the gateway for two-phase commit, a table must be created in the Ingres II database for logging transactions. The gateway uses the transaction log table to check the status of failed transactions that were started at the Ingres II database by the gateway and registered in the table. Updates to the transaction log table cannot be part of an Oracle distributed transaction.
The table consists of two columns, GLOBAL_TRAN_ID, data type CHAR(64) NOT NULL and TRAN_COMMENT, data type CHAR(255).
Create a transaction log table in the user account you created in "Task 1: Create a Recovery Account and Password". Because the transaction log table is used to record the status of a gateway transaction, the table must reside at the database where the Ingres II update takes place. Also, the transaction log table must be created under the owner of the recovery account.
To create a transaction log table use the tg4ingr_tx.sql
script, located in the directory $ORACLE_HOME/tg4ingr/admin
where $ORACLE_HOME is the directory under which the gateway is installed. Use isql to execute the script, as follows:
$ isql -Urecovery_account -Precovery_account [-Sserver] -itg4ingr_tx.sql
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.
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:
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:
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/tg4ingr/admin/inittg4ingr.ora
, twice, naming one with the gateway SID for db2 and the other with the gateway SID for db3:
$ 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=db2
For inittg4ingr3.ora
, enter the following:
HS_FDS_CONNECT_INFO=db3
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
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) ) (SID_DESC= (SID_NAME=tg4ingr2) (ORACLE_HOME=oracle_home_directory
) (PROGRAM=tg4ingr) ) (SID_DESC= (SID_NAME=tg4ingr3) (ORACLE_HOME=oracle_home_directory
) (PROGRAM=tg4ingr) ) )
The LD_LIBRARY_PATH environment variable must be set to include the Ingres II libraries and the TNS listener must be started to initiate the new settings.
If you have the Bourne or Korn Shell, to set the LD_LIBRARY_PATH enter the following:
$ set LD_LIBRARY_PATH=$II_SYSTEM/lib:ORACLE_HOME/lib:$LD_LIBRARY_PATH;export LD_
LIBRARY_PATH
If you have the C Shell, enter the following:
$ setenv LD_LIBRARY_PATH$
II_SYSTEM/lib:ORACLE_HOME/lib:$LD_LIBRARY_PATH
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
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_link=(DESCRIPTION= (ADDRESS= (PROTOCOL=TCP) (PORT=1541) (HOST=gtwhost)) (CONNECT_DATA= (SID=tg4ingr)) (HS=OK)) new_db2_link=(DESCRIPTION= (ADDRESS= (PROTOCOL=TCP) (PORT=1541) (HOST=gtwhost)) (CONNECT_DATA= (SID=tg4ingr2)) (HS=OK)) new_db3_link=(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.
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 'tg4ingr2';
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 'tg4ingr3';
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;
|
![]() Copyright © 2000 Oracle Corporation. All Rights Reserved. |
|