15 Migration From Existing Gateways

Migrating to new instances of Oracle Procedural Gateway for APPC from an existing installation is straightforward, provided you follow some guidelines. This chapter provides information to make these new installations as easy as possible. It also provides the parameters you need if you are using the TCP/IP for IMS Connect communication protocol on your gateway.

This chapter provides information that is specific to this release of Oracle Procedural Gateway for APPC for UNIX. It contains the following sections:

Section 15.1, "Migrating An Existing Gateway Instance to a New Release Using SNA Protocol"
Section 15.2, "Migrating from an Existing Gateway to TCP/IP Using SNA"

15.1 Migrating An Existing Gateway Instance to a New Release Using SNA Protocol

Follow these steps to migrate an existing gateway to Release 10.2.0 of the gateway using the SNA communication protocol.

Note that if you are using the gateway TCP/IP support for IMS Connect, you will not be migrating an existing release to the current release of the gateway. However, you will need to place valid Heterogeneous Services parameters into your initsid.ora file. Proceed to Section 15.1.5, "Parameter Changes: Version 4 to Release 10.2.0 of the Gateway".

15.1.1 Step 1: Install the New Release

Install the new release of the gateway in a separate directory as outlined in Chapter 4, "Installing the Gateway".

Caution:

Do not install the gateway over a previously existing gateway installation. Doing this corrupts the existing installation.

15.1.2 Step 2: Transfering the initsid.ora Gateway Initialization File Parameters

Copy the initsid.ora file from the old gateway instance to the new instance.

If you are migrating from Release 9.0.1 or earlier of the gateway, PGA_TRACE is not supported. You need to modify the parameter to TRACE_LEVEL instead.

Note:

If you are using TRACE_LEVEL, you must set the path for the LOG_DESTINATION parameter.

If you have encrypted some of the parameters at file initsid.ora by using pg4pwd, copy the $ORACLE_HOMRE/pg4appc/admin/initsid.pwd file from the old gateway instance to the new instance.

Note:

If you are migrating from Release 9.0.1 or earlier of the gateway, you do not need to copy this file into the new instance.

15.1.3 Backout Considerations When Migrating to New Releases

Oracle recommends that you keep the old gateway Oracle home directory and instance configurations intact and operational when you are installing a new release of the gateway and upgrading existing instances, in case there are problems with the upgrade. This helps to ensure minimum down time between changes to different gateway instances.

15.1.4 Oracle Net Considerations

Oracle Procedural Gateway for APPC uses the Heterogeneous Services (HS) facilities of Oracle and Oracle Net. If you are upgrading from a version 4 gateway, then you need to slightly modify the gateway service name entries in the tnsnames.ora file. Add an (HS=) clause to tell Oracle Net that the gateway uses HS facilities. For more information, refer to Section 5.1, "Configuring the Oracle Network for the Gateway".

15.1.5 Parameter Changes: Version 4 to Release 10.2.0 of the Gateway

This release of Oracle Procedural Gateway for APPC introduces new and changed initialization parameters if you are migrating from a Version 4 gateway to Release 10.2.0 of the gateway.

Note:

The "Parameter Changes: Version 4 to Release 10.2.0 of the Gateway" section does not apply to you if you are migrating to Release 10.2.0 from Version 8 of the Oracle Procedural Gateway for APPC.

If you are using the gatway TCP/IP support for IMS Connect, you will not be migrating from Version 4 to the current release of the gateway. However, you need to place valid Heterogeneous Services parameters into your initsid.ora file.

This chapter contains references to the particular HS parameters that you need to run the gateway.

Note:

Refer to the Oracle Connectivity Guide for a complete list and descriptions of all HS parameters used in Oracle products.

New Gateway Initialization Parameters

The following parameters are in the gateway initialization file (initsid.ora):

FDS_CLASS
FDS_INSTANCE
HS_FDS_FETCH_ROWS
LOG_DESTINATION
TRACE_LEVEL
PGA_TCP_DB (TCP/IP only)
PGA_TCP_USER (TCP/IP only)
PGA_TCP_PASS (TCP/IP only)

Note:
The HS_ parameters are specific to Oracle Heterogeneous Services. For details on HS parameters, refer to the Oracle Database Administrator's Guide.

Renamed Gateway Initialization File Parameters

Following is a list of the gateway initialization file (initsid.ora) parameters that have been renamed in this release of the gateway. The former names of the parameters are shown in parentheses.

HS_COMMIT_STRENGTH_POINT (formerly COMMIT_STRENGTH_POINT)
HS_DB_DOMAIN (formerly DB_DOMAIN)
HS_DB_INTERNAL_NAME (formerly DB_INTERNAL_NAME)
HS_DB_NAME (formerly DB_NAME)
HS_DESCRIBE_CACHE_HWM (formerly DESCRIBE_CACHE_HWM)
HS_LANGUAGE (formerly LANGUAGE)
HS_NLS_DATE_FORMAT (formerly NLS_DATE_FORMAT)
HS_NLS_DATE_LANGUAGE (formerly NLS_DATE_LANGUAGE)
HS_OPEN_CURSORS (formerly OPEN_CURSORS)
HS_ROWID_CACHE_SIZE (formerly ROWID_CACHE_SIZE)

Obsolete Parameters

The following parameters are obsolete. If necessary, remove them from your configuration files:

MODE
SERVER_PATH
ERROR_LOGGING
ERROR_REPORTING
ERRORTAG
GATEWAY_SID
GROUP_BY_OFF
GTWDEBUG
INCREMENT_CURSORS
INIT_CURSORS
LIST
MAX_LOG_SIZE
OPTIMIZE_FILE_OPEN
ORDER_BY_OFF
RESOLVE_BINDS
RETRY
SET
SNMP_SUPPORT
SQL_TRACE
TRIM_CURSORS
D_OPEN_CURSORS
D_INIT_CURSORS
D_INCREMENT_CURSORS
D_TRIM_CURSORS
PGA_TRACE

15.1.6 Parameter Changes: Version 8 or Earlier to Gateway Release 10.2.0

The following startup shell script parameter must be added to initsid.ora if you are migrating from a Version 4 or Version 8 gateway to Release 10.2.0 of the Oracle Procedural Gateway for APPC:

FDS_CLASS_VERSION

15.1.7 Migrating from Gateway Release 9.0.1 or 9.2.0 or 10.1.0 to Gateway Release 10.2.0

No new parameters were added between release 9.0.1 and this release of the gateway.

15.2 Migrating from an Existing Gateway to TCP/IP Using SNA

The following sections are for those users who have an existing release of the gateway using the SNA protocol, but who want to switch to using TCP/IP support for IMS Connect.

The TCP/IP support for IMS Connect feature in this release of the gateway enables you to continue to use existing TIPs.

15.2.1 Using Existing TIPs with Existing Side Profile Definitions

Follow these instructions:

Make sure you have used the pg4tcpmap tool to insert valid parameter values into the PGA_TCP_IMSC table.

Refer to Chapter 13, "Gateway Configuration Using TCP/IP Communication Protocol" for instructions to load the PGA_TCP_IMSC table.
Make sure the LANGUAGE parameter in your TIPs is set to american_america_us7ascii.
Use PGAU to regenerate the IMS TIPs.

Add the following new TCP/IP parameters to the initsid.ora file:

PGA_TCP_DB
PGA_TCP_USER
PGA_TCP_PASS

You will find descriptions and information about adding these parameters in Section 15.1.5, "Parameter Changes: Version 4 to Release 10.2.0 of the Gateway". You will also find descriptions of the parameters in Appendix B, "Gateway Initialization Parameters for TCP/IP Communication Protocol".

Note:

If your TIPs from a previous version of the gateway were already defined using a SideProfileName and the NLS_ LANGUAGE parameter has been set to a value of american_america_us7ascii, then you will not need to recompile these TIPs. You still need to map your parameter values using the pg4tcpmap tool.

15.2.2 Using Existing TIPs with LU/TP/LOGMODE Names

The new TCP/IP support for IMS Connect feature of the gateway only supports Side Profile Name coding in the IMS TIPs. If you have been using SNA on a gateway using LU, TP, or LOGMODE combinations, perform the following:

Edit the IMS TIPs. Create an 8-character, unique identifier and insert it into the TIP as the Side Profile.

This identifier does not need to be a system-defined SNA Side Profile Name, and it is simply a unique name.
Make sure you have used the pg4tcpmap tool to insert the Side Profile name into the PGA_TCP_IMSC table.

Refer to Chapter 13, "Gateway Configuration Using TCP/IP Communication Protocol" for instructions on loading the PGA_TCP_IMSC table.
Make sure the LANGUAGE in your TIPs is set to american_america_us7ascii.
Use PGAU to regenerate the IMS TIPs.

Add the following new TCP/IP parameters to the initsid.ora file:

PGA_TCP_DB
PGA_TCP_USER
PGA_TCP_PASS

Descriptions and information about adding these parameters is available in Section 15.1.5, "Parameter Changes: Version 4 to Release 10.2.0 of the Gateway". You will also find descriptions of the parameters in Appendix B, "Gateway Initialization Parameters for TCP/IP Communication Protocol".

Note:

TIPs must be recompiled when changing communication protocol from SNA to TCP/IP.

If you have existing TIPs that were generated previously on a gateway using the SNA communication package protocol, and you want to use the new TCP/IP feature, then the TIPs 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 appropriate user exit in IMS Connect is being used, which would translate between the appropriate ASCII and EBCDIC character sets.