4 Installing the Gateway

This chapter describes how to install and configure the Oracle Procedural Gateway for APPC. It contains the following sections:

Section 4.1, "Before You Begin"
Section 4.2, "Planning to Upgrade or Migrate the Gateway"
Section 4.3, "Preinstallation Steps for Upgrade"
Section 4.4, " Installing the Gateway Software"
Section 4.5, "Installation Steps"
Section 4.6, "Deinstalling Oracle Procedural Gateway for APPC"

4.1 Before You Begin

You can perform cetain actions on online transaction processing (OLTP) and some components of the host operating system to configure the OLTP to enable access by the gateway. You also need access to the host system and knowledge of the host system and the OLTP. Although this chapter includes some information about host system and OLTP installation steps, you must ensure that you have the applicable OLTP and host system documentation available.

Some configuration actions on the OLTP might require you to restart the OLTP. Ensure that your host system programmer or DBA review the instructions for your OLTP before you restart it.

To install and configure the gateway with a single Oracle Integrating Server and a single OLTP, perform the procedures described in this chapter.

Note:

If your gateway uses the SNA communication protocol, then follow the instructions for installation and configuration in this chapter, in Chapter 5, "Configuring Your Oracle Network", and in Chapter 12, "Gateway Configuration Using SNA Communication Protocol".

If your gateway uses the TCP/IP communication protocol, then follow the instructions for installation and configuration in this chapter, in Chapter 5, "Configuring Your Oracle Network", and in Chapter 13, "Gateway Configuration Using TCP/IP Communication Protocol".

4.2 Planning to Upgrade or Migrate the Gateway

This section is only for customers who have a previous release of Oracle Procedural Gateway for APPC. If you have a previous gateway installation, then you need to perform some tasks before you can install release 10.2.0.1.0 of the Oracle Procedural Gateway for APPC.

Note:

After reading this section, you must read Chapter 15, "Migration From Existing Gateways" to determine the specific actions you must perform to prepare for upgrade or migration of your gateway. If you are migrating to Oracle Procedural Gateway for APPC release 10.2.0.1.0 from version 4.01 or earlier, then you will find content related to migrating the gateway in Chapter 15, "Migration From Existing Gateways".

You may also find it helpful to refer to Appendix D, "Summary of Changes in Previous Versions" for information on changes or corrected problems from earlier releases of the gateway.

If you are installing Oracle Procedural Gateway for APPC for the first time, then begin with "Preinstallation Steps for Upgrade".

This section includes the following topics:

Section 4.2.1, "Preupgrade Procedures"
Section 4.2.2, "Upgrade and Migration Considerations"
Section 4.2.3, "Restoration"

4.2.1 Preupgrade Procedures

Perform the following steps to prepare for upgrading the previous versions of Oracle Procedural Gateway for APPC to current versions:

Make backups of altered PGA shipped files.
Remove or rename any old gateway directories.

4.2.2 Upgrade and Migration Considerations

Upgrade considerations are as follows:

PGAU control files from Gateway release 8 or 9 are upward compatible and you do not need to change them.
After upgrade, the PG Data Dictionary (PG DD ) contains all of its earlier entries without modification. New PGAU control information is added along with some columns to support new features, but no customer entries are altered by the upgrade.
All TIPs from Oracle Procedural Gateway for APPC release 4.0.1 or earlier must be recompiled because of the changes in the following:
- PL/SQL compatibility
- Gateway server RPC interface
- UTL_PG interface
If you have existing TIPs that were generated previously on a gateway using the SNA communication protocol and you want to utilize the new TCP/IP feature, then TIPs will have to be regenerated by PGAU with mandatory NLS_LANGUAGE and Side Profile Settings. Specify the appropriate ASCII character set in the DEFINE TRANSACTION command.

This is because the gateway assumes that the user exit in IMS Connect is being used, which would translate between the ASCII and EBCDIC character sets.

Caution:
An upgraded PG Data Dictionary (PG DD) cannot be accessed by an earlier release of PGAU.

4.2.3 Restoration

If you want to restore a previous release of gateway, then you must restore the following components to their previous versions:

PGAU
PG DD
Gateway server

4.3 Preinstallation Steps for Upgrade

Before you install the gateway, perform the following pre-installation procedures:

Ensure that your system meets all of the hardware and software requirements specified in Chapter 3, "System Requirements".
A CD-ROM drive is required.

The Oracle Procedural Gateway for APPC is currently shipped on CD-ROM media. The hardware required for the medium on which the gateway was ordered must be installed on your system.
Ensure that your security requirements are met.

Refer to Chapter 3, "System Requirements" for more information about the security requirements for connections and data access on your OLTP.
Fill out the worksheet identifying unique parameter names needed to configure your system and your chosen communication protocol (either SNA or TCP/IP), which is located in Chapter E, "Configuration Worksheet".
Decide on a SID (system identifier) for your gateway. This SID is used in Section 12.7, "Configuring the Gateway".

The SID must be unique and must not be used by any other gateway or Oracle Integrating Server on the system.
SNA only : Your SNA package must be installed and configured before you can proceed with installation of the gateway. Ensure that your system can communicate with the OLTP using the SNA communication package appropriate for your platform.

For more information about setting up and configuring the SNA communication package your platform needs to run the Oracle Procedural Gateway for APPC, refer to the appropriate chapter in this guide from the following list:
- For Linux for Intel Pentium-based 32-bit systems, refer to Chapter 6, "Configuring the SNA Communication Package on Linux".
- For AIX-Based Systems, refer to Chapter 7, " Configuring the SNA Communication Package on AIX-Based Systems".
- For HP-UX, refer to Chapter 8, "Configuring the SNA Communication Package on HP-UX".
- For Solaris Operating System (SPARC 64-bit), refer to Chapter 9, "Configuring the SNA Communication Package on Solaris".
TCP/IP only: Your TCP/IP package must be installed and configured before you can proceed with installation of the gateway. Refer to Chapter 10, "Configuring the TCP/IP Communications Package for IMS Connect" for more information about setting up and configuring TCP/IP for your platform.

Ensure that your system can communicate with the OLTP using the TCP/IP communication package for your platform.

If you need general information about installing Oracle products and using the Oracle Universal Installer, then refer to the Oracle Database Installation Guide.

4.3.1 Gateway Installation Methods

You can install the gateway in any of the following ways:

On the same system as the existing Oracle Integrating Server but in a different directory.

All tasks for this type of installation or upgrade are discussed in this section.
On a system different from a local Oracle Integrating Server.
On the same system as the Oracle Integrating Server, and in the same Oracle home directory. Note that in this case, the Oracle Integrating Server and the gateway must be at the same Release level.

4.4 Installing the Gateway Software

For general information about installing Oracle products and how to use the Oracle Universal Installer, refer to the Oracle Database Installation Guide and perform all necessary tasks there first.

If your server release is different than your gateway release, do not install the gateway in the same Oracle home directory as the Oracle Integrating Server. This is required to isolate the gateway from the Oracle Integrating Server upgrades that might cause incompatibilities if the gateway executables were relinked with later versions of the Oracle server libraries.

4.5 Installation Steps

If you want to install the gateway in the same Oracle home as the Oracle Integrating Server, then the release number of both products must be the same. This section provides the steps for installing the gateway. It contains the following topics:

Section 4.5.1, "Step 1: Login as DBA and Create Login User ID"
Section 4.5.2, "Step 2: Create the Product Installation Directory"
Section 4.5.3, "Step 3: Setting the Environment Variables"
Section 4.5.4, "Step 5: Mount the CD-ROM"
Section 4.5.5, "Step 6: Start the Oracle Universal Installer"
Section 4.5.6, "Step 7: Step through the Oracle Universal Installer"

4.5.1 Step 1: Login as DBA and Create Login User ID

Log in as the Oracle database administrator (DBA) user. If you are not currently a DBA user, then contact your system administrator to create a DBA login user ID. .

4.5.2 Step 2: Create the Product Installation Directory

When you create a new directory, Oracle recommends that you use the version number as part of the path name. Doing this enables different versions of the same Oracle product to be installed under one Oracle directory tree. The product installation directory is also known as $ORACLE_HOME for the gateway.

Next create the /oracle/pga/10.2 product installation directory.

For example, enter:

$ mkdir /oracle/pga
$ mkdir /oracle/pga/10.2
$ chown oracle:dba /oracle/pga/10.2
$ chmod 755 /oracle/pga/10.2

4.5.3 Step 3: Setting the Environment Variables

The ORACLE_HOME, LD_LIBRARY_PATH, and TNSADMIN environment variables must point to the directory that you created in Step 2. The command to set the environment variable depends on the shell that you are using.

For example, if you are a Bourne or Korn shell user, then enter:

$ ORACLE_HOME=/oracle/pga/10.2; export ORACLE_HOME
$ LD_LIBRARY_PATH=$ORACLE_HOME/lib;export LD_LIBRARY_PATH
$ TNS_ADMIN=$ORACLE_HOME/network/admin;export TNS_ADMIN
$ DISPLAY=machine:0; export DISPLAY

and, if you are using SNA, then enter:

$NLS_LANG=american_america.WE8EBCDIC37C;export NLS_LANG

or, if you are using TCP/IP, then enter:

$NLS_LANG=american_america.us7ascii;export NLS_LANG

If you are a C shell user, then enter:

$ setenv ORACLE_HOME /oracle/pga/10.2
$ setenv LD_LIBRARY_PATH /oracle/pga/10.2/lib
$ setenv TNS_ADMIN $ORACLE_HOME/network/admin
$ setenv DISPLAY machine:0

and, if you are using SNA, then enter:

$ setenv NLS_LANG american_america.WE8EBCDIC37C

or, if you are using TCP/IP, then enter:

$ setenv NLS_LANG american_america.us7ascii

Note:

Ensure that the TNS_ADMIN environment variable points to the path where your tnsnames.ora and listener.ora files are. These files are usually in the $ORACLE_HOME/network/admin directory.

Set the DISPLAY environment variable to the X-server display where the Oracle Universal Installer is displayed.

4.5.4 Step 5: Mount the CD-ROM

The following sections describe how to mount the CD-ROM for each platform:

Section 4.5.4.1, "Mounting the CD-ROM for Linux"
Section 4.5.4.2, "Mounting the CD-ROM for AIX-Based Systems"
Section 4.5.4.3, "Mounting the CD-ROM for HP-UX"
Section 4.5.4.4, "Mounting the CD-ROM for Solaris Operating System (SPARC 64-bit)"

4.5.4.1 Mounting the CD-ROM for Linux

To mount the CD-ROM on Linux:

Insert the CD in your CD-ROM drive and enter the following commands:

$ su root
# mkdir /cdrom
# mount /dev/hdb /cdrom
# exit
$ cd /cdrom

Proceed to Step 6: Start the Oracle Universal Installer For Linux in Section 4.5.5.1

4.5.4.2 Mounting the CD-ROM for AIX-Based Systems

Insert the CD in your CD-ROM drive and enter:

$ su root 
# mkdir /cdrom
# mount -r -v cdrfs /dev/cd0 /cdrom
# exit

Proceed to Step 6: Start the Oracle Universal Installer For AIX Systems in Section 4.5.5.2, to start the Oracle Universal Installer.

4.5.4.3 Mounting the CD-ROM for HP-UX

To mount the installation, perform the following:

Use a system editor to add the following line to the /etc/pfs_fstab file.
```
device_file mount_point filesystem_type translation_method 
```
For example:
```
/dev/dsk/c5t2d0 /SD_CDROM pfs-rrip xlat=unix 10
```
The first entry is the CD-ROM device file; the second is the mount point. The third entry indicates that the CD-ROM to be mounted is in ISO9660 format with RockRidge extension.
Log in as the root user:
```
$ su root
```
Enter the following command:
```
# nohup/usr/sbin/pfs_mountd &
```
Enter the following file command:
```
# nohup/usr/sbin/pfsd &
```
Insert the CD into the tray and enter the following command to mount the CD-ROM:
```
# /usr/sbin/pfs_mount /SD_CDROM
```
Exit the root account.
```
# exit
```
Change directories to /SD_CDROM where you can see a lowercase listing of the directories and files on the CD-ROM. The mounted CD-ROM should appear as another read-only file system.
Now proceed to Step 6: Start the Oracle Universal Installer For HP-UX in Section 4.5.5.3 to start the Oracle Universal Installer.

4.5.4.4 Mounting the CD-ROM for Solaris Operating System (SPARC 64-bit)

Insert the CD in your CD-ROM drive and enter the following command:
```
$ cd /cdrom
```
Now proceed to Step 6: Start the Oracle Universal Installer For Solaris in Section 4.5.5.4 to start the Oracle Universal Installer.

4.5.5 Step 6: Start the Oracle Universal Installer

The Oracle Universal Installer is provided on the distribution installation media with the gateway. For general information about installing Oracle products and how to use the Oracle Universal Installer, refer to the Oracle Database Installation Guide.

The following sections describe how to start the Oracle Universal Installer for each of the platforms:

Section 4.5.5.1, "For Linux"
Section 4.5.5.2, "For AIX Systems"
Section 4.5.5.3, "For HP-UX"
Section 4.5.5.4, "For Solaris"

4.5.5.1 For Linux

To start Oracle Universal Installer, enter the following commands:

$ cd cdrom_mount_point_directory
$ ./runInstaller

4.5.5.2 For AIX Systems

Start the Oracle Universal Installer with the following command:
```
$ cd cdrom_mount_point_directory
$ ./runInstaller
```
A window appears with the question "Has the rootpre.sh script been run by root?" Before you can proceed with the installation, this script must have been run on the install system of the gateway.
If you have already run this script (either during a previous installation of this version of the gateway, or during an installation of the Oracle Database 10g Server), then type "Y" and begin stepping through the Oracle Universal Installer. If you have not run the script, then perform step 3 .
If the rootpre.sh script has not yet been run, type "N" and complete the following steps:
1. Log on as the root user.
2. Change directory to the install directory on the installation media.
3. Run the rootpre.sh script.
4. Exit from the root user.
5. Restart the Oracle Universal Installer.

4.5.5.3 For HP-UX

Start the Oracle Universal Installer, as follows:

$ cd cdrom_mount_point_directory 
$ ./runInstaller

4.5.5.4 For Solaris

Start the Oracle Universal Installer, as follows:

$ cd cdrom_mount_point_directory 
$ ./runInstaller

4.5.6 Step 7: Step through the Oracle Universal Installer

Caution:

Oracle Universal Installer automatically installs the Oracle-supplied version of the Java Runtime Environment (JRE). This version is required to run the Oracle Universal Installer and several Oracle assistants. Do not modify the JRE except by using a patch provided by Oracle Support Services. The Oracle Universal Installer also installs JDK .

Oracle Universal Installer is a menu-driven utility that guides you through installing the gateway by prompting you with action items. The action items and the sequence in which they appear depend on your platform.

The following section describes how use the Oracle Universal Installer to install the gateway on your platform:

4.5.6.1 Oracle Universal Installer on UNIX platforms

Use Table 4-1 as a guide to step through the Oracle Universal Installer. At each prompt from the Oracle Universal Installer, perform the actions described in the Response column of the table to install the gateway on your UNIX platform.

Table 4-1 The Oracle Universal Installer: Steps for Installing the Gateway

Prompt	Response
Oracle Universal Installer: Welcome	Click Next.
Oracle Universal Installer: Specify Inventory Directory and credentials	a. Specify the full path of the inventory directory. b. Specify the operating system group name. c. Click Next.
Oracle Universal Installer: Specify Home Details	a. Specify the name of the installation. b. Specify the full path where you want to install the product. c. Click Next.
Oracle Universal Installer: Available Product Components	a. Deselect the checked products. b. Select "Oracle Transparent Gateway 10.2.0.1.0", open up this row. c. Select "Oracle Procedural Gateway for APPC 10.2.0.1.0". d. Click Next.
Oracle Universal Installer: Network Software	Specify your network package and click Next.
Oracle Universal Installer: Summary	Click Install.
Oracle Net Congiguration Assistance: Welcome	Click Next.
Oracle Net Configuration Assistance: Listener Configuration, Listener Name	Specify the name of Listener you want to create and click Next.
Oracle Net Configuration Assistance: Listener Configutration, Select Protocols	Select the protocols and click Next.
Oracle Net Configuration Assistance: Listener Configuration, TCP/IP Protocol	Specify a port number and click Next.
Oracle Net Configuration Assistance:Listener Configuration, More Listeners?	Click "No" and then click Next.
Oracle Net Configuration Assistance: Listener Configuration Done	Click Next.
Oracle net Configuration Assistance: Naming Methods Configuration	Click No and then click Next.
Oracle Net Configuration Assistance: Done	Click Finish.
Execute Configuration scripts	You must run the `root.sh` configuration script from the `$ORACLE_HOME` directory at this point. Leave the installation open, run the script as the `root` user from another window, then come back to the installation screen and click OK to continue.
Oracle Universal Installer: End of Installation	Click Exit.

When the Oracle Universal Installer confirms that the installation is complete, verify that the installation procedure was successful. To do this, read the contents of the installation log file, which is located in the $ORACLE_HOME/install directory. The default file name is make.log.

Attention:

Print the contents of the $ORACLE_HOME/pg4appc/doc/README.doc file and read the entire document; it contains important information about the installation. After reading the README.doc file, proceed with configuration of the gateway.

4.6 Deinstalling Oracle Procedural Gateway for APPC

If you decide to deinstall the gateway, perform the following steps:

Drop the PG DD (packages and procedures):
1. Use SQL*Plus to connect to the Oracle Integrating Server as user PGAADMIN.
2. From SQL*Plus, run the pgdddel.sql script in the $ORACLE_HOME/pg4appc/admin directory directory.
Log in as DBA. Refer to "Step 1: Login as DBA and Create Login User ID" for more information.
Set the ORACLE_HOME environment variable. Refer to "Step 3: Setting the Environment Variables" for more information.
Verify the DISPLAY and ORACLE_HOME environment variables. Refer to "Step 3: Setting the Environment Variables" for more information.
Mount the CD-ROM. Refer to "Step 5: Mount the CD-ROM" for more information.
Start the Oracle Universal Installer by running the following command:
```
$ ./runInstaller
```

Step through the Oracle Universal Installer. Use the prompts listed in Table 4-2, " Steps to DeInstall the Gateway Using Oracle Universal Installer" as a guide for deinstallation, following the instructions in the Response column.

Table 4-2 Steps to DeInstall the Gateway Using Oracle Universal Installer

Prompt	Response
1. Oracle Universal Installer	Click Deinstall Products.
2. Inventory	Check "Oracle Procedural Gateway for APPC 10.2.0.1.0" and click Remove.
3. Confirmation	Click Yes.
4. Inventory	Click Close.
5. Oracle Universal Installer	Click Cancel.
6. Exit	Click Yes.

The gateway is now deinstalled.

When the Oracle Universal Installer confirms that the deinstallation has ended, verify that the deinstallation procedure was successful. To do this, read the contents of the deinstallation log file, which is located in the $ORACLE_HOME/install directory directory. The default file name is install.log.
The only files that are removed are those that were copied to the $ORACLE_HOME directory during the gateway installation. You must remove any other related files manually, including deleting listener.ora and tnsnames.ora entries relating to the gateway, dropping database links and the PGAADMIN user ID and deleting the TIPs.