This chapter describes how to configure the Oracle Integrating Server for a gateway using the SNA protocol on your UNIX platform. It also shows you how to configure commit-confirm, should you choose to implement it.
This chapter provides the steps necessary to verify installation and configuration of the gateway components, including optional commit-confirm. It contains the following sections:
Chapter12, "Preparing to Configure a Gateway Installation/Upgrade"
Chapter12, "Integrating Server Configuration: First-Time Gateway Installations"
Chapter12, "Upgrading or Migrating the Oracle Server from Previous Gateways"
Chapter12, "Configuring the Oracle Integrating Server for Gateways to Coexist"
Chapter12, "Optional Configuration Steps to Permit Multiple Users"
Chapter12, "Verifying the Gateway Installation and OLTP Configuration"
Configuring the Oracle Procedural Gateway for APPC using SNA involves working with the following components:
Oracle Integrating Server
UNIX system
Network
OLTP
This chapter requires you to input parameters unique to your system to properly configure the gateway and SNA communications interface.
Refer to Appendix E, "Configuration Worksheet" for a worksheet listing the installation parameters that you need to know before you can complete the configuration process. Ask your network administrator to provide you with these unique parameter names before you begin.
There are three ways to establish the gateway-Oracle Integrating Server relationship when you are installing or upgrading or migrating the gateway:
When Oracle Integrating Server and the Gateway Are Installed in the Same ORACLE_HOME
When Oracle Integrating Server and the Gateway Are Installed on Separate Systems
When Oracle Integrating Server and the Gateway Are on the Same System but in Different Directories
Depending on the location of the gateway and the Oracle Integrating Server, you might need to transfer some of the gateway administrative files to the location where Oracle Integrating Server is installed.
Follow the instructions corresponding to your combination of the gateway-Oracle Integrating Server locations listed below.
When Oracle Integrating Server and the Gateway Are Installed in the Same ORACLE_HOME
You do not need to transfer files. Proceed to Chapter12, "Integrating Server Configuration: First-Time Gateway Installations".
When Oracle Integrating Server and the Gateway Are Installed on Separate Systems
You need to perform the following tasks if Oracle Integrating Server and the gateway are installed on separate systems:
Locate the gateway administrative files in the gateway $ORACLE_HOME/pg4appc/admin
directory. All files in this directory that have the .sql
, .pkh
, or .pkb
suffixes must be copied into a similarly-named directory in the Oracle Integrating Server Oracle home directory.
Now locate the gateway demo files and subdirectories in the $ORACLE_HOME/pg4appc/demo
directory of the gateway. Copy the pgavsn.sql
and pgaecho.sql
files into a similarly named directory in Oracle Integrating Server.
Copy the other subdirectories and files related to your installed OLTP on your remote host. For example, if you have CICS as your only OLTP, then copy the $ORACLE_HOME/pg4appc/demo/CICS
gateway files into a similarly named directory in the Oracle Integrating Server.
Note:
Before transferring the files from the$ORACLE_HOME/pg4appc/demo
directory, ensure that you have generated your required TIPs. You need to transfer the TIPs as well.
Refer to the Oracle Procedural Gateway for APPC User's Guide for information about generating TIPs using Procedural Gateway Administrative Utility (PGAU).
When Oracle Integrating Server and the Gateway Are on the Same System but in Different Directories
You must change your gateway Oracle home to the Oracle home directory of Oracle Integrating Server.
For example, if your gateway Oracle home is set as follows:
$ echo $ORACLE_HOME /oracle/pga/10.2
and your server Oracle home is located in the /oracle/pga/10.2
directory, then you need to do the following:
$ ORACLE_HOME=/oracle/pga/10.2; export ORACLE_HOME
Now create the directories with the following commands:
$ cd $ORACLE_HOME $ mkdir pg4appc $ mkdir pg4appc/admin
Use whatever file transfer mechanism is available on your system to copy all of the .sql
, .pkh
, and .pkb
files from the gateway Oracle home $ORACLE_HOME/pg4appc/admin
directory to the Oracle Integrating Server Oracle home $ORACLE_HOME/pg4appc/admin
directory.
You might also transfer the demo files from the gateway directory to the Oracle Integrating Server directory. Copy the files and directory recursively from the gateway Oracle home $ORACLE_HOME/pg4appc/demo
directory to the Oracle Integrating Server $ORACLE_HOME/pg4appc/demo
directory.
For example:
$ cp -p -R /oracle/pga/10.2/pg4appc/demo $ORACLE_HOME/pg4appc
Note:
Before transferring the files from the$ORACLE_HOME/pg4appc/demo
directory, ensure that you have generated your required TIPs. You need to transfer the TIPs as well.
Refer to the Oracle Procedural Gateway for APPC User's Guide for information about generating TIPs using PGAU.
If this is a first-time installation, proceed with Chapter12, "Integrating Server Configuration: First-Time Gateway Installations".
If this is an upgrade, proceed with Chapter12, "Upgrading or Migrating the Oracle Server from Previous Gateways".
Following those steps, you might want to perform the Chapter12, "Optional Configuration Steps to Permit Multiple Users".
Follow these steps to configure your Oracle Integrating Server if you have installed Oracle Procedural Gateway for APPC for the first time:
Ensure that the UTL_RAW PL/SQL package has been installed on your Oracle Integrating Server. All PGAU-generated TIP specifications use UTL_RAW, which provides routines for manipulating raw data.
Use SQL*Plus to connect to the Oracle Integrating Server as the SYS
user.
From SQL*Plus, enter the following command:
SQL> DESCRIBE UTL_RAW
The DESCRIBE
statement produces output on your screen. If you browse through the output, you should see some functions, including a compare function. If you do not see this output, then continue the UTL_RAW installation by performing step d below.
If the DESCRIBE
statement indicates success, then your Oracle Integrating Server has UTL_RAW installed and you can proceed to Step 2.
Use SQL*Plus to connect to the Oracle Integrating Server as the SYS user.
From SQL*Plus, run the utlraw.sql
and prvtrawb.plb
scripts in the Oracle Integrating Server $ORACLE_HOME/rdbms/admin
directory, in the following order:
SQL> @$ORACLE_HOME/rdbms/admin/utlraw.sql SQL> @$ORACLE_HOME/rdbms/admin/prvtrawb.plb
Ensure that the DBMS_OUTPUT standard PL/SQL package is enabled on Oracle Integrating Server. The sample programs and installation verification programs on the distribution media use this standard package.
If necessary, use SQL*Plus to connect to the Oracle Integrating Server as the SYS
user.
From SQL*Plus, enter the following command:
SQL> DESCRIBE DBMS_OUTPUT
The DESCRIBE
statement produces output on your screen. If you browse through that output, you should see some functions, including a put_line
function.
If you do not see this output, then you must create the DBMS_OUTPUT package. Refer to the Oracle Database Application Developer's Guide for more information about creating the DBMS_OUTPUT package. After successful installation of the DBMS_OUTPUT package, issue the DESCRIBE
statement.
If the DESCRIBE
statement indicates success, then your Oracle Integrating Server has DBMS_OUTPUT created, and you can proceed to Step 3.
Install the UTL_PG PL/SQL package. All PGAU-generated TIP specifications use UTL_PG, which provides routines for performing numeric conversions to and from raw data.
If necessary, use SQL*Plus to connect to the Oracle Integrating Server as the SYS
user.
From SQL*Plus, run the utlpg.sql
and prvtpgb.plb
scripts in the Oracle Integrating Server $ORACLE_HOME/rdbms/admin
directory, in the following order:
SQL> @$ORACLE_HOME/rdbms/admin/utlpg.sql SQL> @$ORACLE_HOME/rdbms/admin/prvtpgb.plb
Install the Heterogeneous Services (HS) catalogs.
If necessary, use SQL*Plus to connect to the Oracle Integrating Server as the SYS
user.
Enter the following command:
SQL> DESCRIBE HS_FDS_CLASS
The DESCRIBE statement produces output on your screen. If the DESCRIBE statement indicates success, then heterogeneous services catalogs have been created on your Oracle Integrating Server and you can proceed to Step 5, otherwise follow the next step only if the DESCRIBE statement does not indicate success. Step c creates the Heterogeneous Services catalog.
If it is necessary to create the Heterogeneous Services catalog, enter the following command:
SQL> $ORACLE_HOME/rdbms/admin/caths.sql
Create a public database link to access Oracle Procedural Gateway for APPC:
Use SQL*Plus to connect to the Oracle Integrating Server as the SYSTEM
user. You can use the following SQL*Plus sample whether the Oracle Integrating Server and the gateway are on the same system or on different systems. In the following sample, pgasrv
is the tns_name_entry
that will be assigned to the gateway when you modify the tnsnames.ora
file later in this chapter.
SQL> CREATE PUBLIC DATABASE LINK PGA USING 'PGASRV'
Create the gateway administrator user PGAADMIN
and install the PG DD.
Use SQL*Plus to connect to the Oracle Integrating Server as the SYSTEM
user.
From SQL*Plus, run the pgacr8au.sql
script in the $ORACLE_HOME/pg4appc/admin
directory. This script creates the PGAADMIN
user ID.
The initial password defined for PGAADMIN
is PGAADMIN
. Use the ALTER USER
command to change the password. For more information about password issues, refer to the Oracle Database SQL Reference.
SQL> @$ORACLE_HOME/pg4appc/admin/pgacr8au.sql
Use SQL*Plus to connect to the Oracle Integrating Server as user PGAADMIN
.
From SQL*Plus, run the pgddcr8.sql
script in the $ORACLE_HOME/pg4appc/admin
directory. This script installs the PG DD.
SQL> @$ORACLE_HOME/pg4appc/admin/pgddcr8.sql
From SQL*Plus, connect to the Oracle Integrating Server as the SYS
user.
Grant execution privileges on DBMS_PIPE to PGAADMIN
:
SQL> GRANT EXECUTE ON DBMS_PIPE TO PGAADMIN
Install the TIP trace access PL/SQL routines. These routines require that the DBMS_PIPES standard PL/SQL package is installed and that PGAADMIN
has execute privileges on it. For more information on DBMS_PIPES, refer to the Oracle Database Application Developer's Guide.
If necessary, use SQL*Plus to connect to the Oracle Integrating Server as user PGAADMIN.
From SQL*Plus, run the pgatiptr.sql
script in the $ORACLE_HOME/pg4appc/admin
directory. This script creates PL/SQL routines that can be called to read and purge trace information created by PGAU-generated TIP specifications. It also creates public synonyms for these routines. The script prompts you for the necessary user IDs and passwords.
SQL> @$ORACLE_HOME/pg4appc/admin/pgatiptr.sql
Install the GPGLOCAL package. This package is required for compilation and execution of all PGAU-generated TIP specifications. TIP developers should be granted execute privileges on GPGLOCAL (refer to Step 3 of "Optional Configuration Steps to Permit Multiple Users").
Use SQL*Plus to connect to the Oracle Integrating Server as user PGAADMIN
.
From SQL*Plus, run the gpglocal.pkh
script in the $ORACLE_HOME/pg4appc/admin
directory. This script compiles the GPGLOCAL package specification.
SQL> @$ORACLE_HOME/pg4appc/admin/gpglocal.pkh
From SQL*Plus, run the gpglocal.pkb
script in the $ORACLE_HOME/pg4appc/admin
directory. This script compiles the GPGLOCAL package body.
SQL> @$ORACLE_HOME/pg4appc/admin/gpglocal.pkb
Follow these instructions only if you have a previous version of the Oracle Procedural Gateway for APPC installed on your system and need to configure it for Release 10.2.0 of the gateway.
Upgrade your Oracle Procedural Gateway for APPC to current version levels as follows:
Use SQL*Plus to connect to the Oracle Integrating Server as the SYS
user.
Install the UTL_RAW package body. From SQL*Plus, run the prvtrawb.plb
script from the $ORACLE_HOME/rdbms/admin
directory. This script upgrades the UTL_RAW package body.
SQL> @$ORACLE_HOME/rdbms/admin/prvtrawb.plb
Install the UTL_PG package body. From SQL*Plus, run the prvtpgb.plb
script from the $ORACLE_HOME/rdbms/admin
directory. This script upgrades the UTL_PG package body.
SQL> @$ORACLE_HOME/rdbms/admin/prvtpgb.plb
The prvtrawb.plb
and prvtpgb.plb
scripts should complete successfully. If they fail because specifications do not exist or were invalidated, then consider reinstalling the package specifications as directed in the following section.
If the UTL_RAW or UTL_PG package has been invalidated or deinstalled, the prvtrawb.plb
and prvtpgb.plb
scripts might not complete successfully and you might have to reinstall the package specifications.
If you do reinstall the package specifications, any dependent objects (such as existing user TIPs and client applications) are invalidated and will subsequently need to be recompiled. The impact of this is a one-time performance delay while recompilation of the TIPs and dependent client applications proceeds.
Important:
Before proceeding with reinstallation of the package scripts, make sure that you are in the$ORACLE_HOME/pg4appc/admin
directory.TIPs were split into separate specification and body files in release 3.3 to avoid cascaded recompilations in later releases.
Step 1 Run the Following Scripts before Proceeding with the PGAU Upgrade
From SQL*Plus, run the utlraw.sql
script:
If necessary, use SQL*Plus to connect to the Oracle Integrating Server as the SYS
user.
From SQL*Plus, run the utlraw.sql
and utlpg.sql
scripts in Oracle Integrating Server $ORACLE_HOME/rdbms/admin
directory, in the following order, to upgrade their respective package specifications:
SQL> @$ORACLE_HOME/rdbms/admin/utlraw.sql SQL> @$ORACLE_HOME/rdbms/admin/utlpg.sql
Step 2 Repeat Installation of UTL_RAW and UTL_PG Package Body
After the scripts have run, repeat Steps 0b and 0c in Chapter12, "Upgrading or Migrating the Oracle Server from Previous Gateways". Then proceed to the section titled "Upgrading PGAU From Previous Gateway Releases".
Note:
TIPs and dependent client applications must be recompiled after reinstallation of the package specifications. Refer to the "Compiling a TIP" section in Chapter 3 of the Oracle Procedural Gateway for APPC User's Guide for information about compiling TIPs.You might have an older version of the gateway already installed. Be aware that although a version 10 gateway can communicate with a version 9 data dictionary (PGDD), a version 9 gateway cannot communicate with a version 10 data dictionary. Thus, if you upgrade your data dictionary to a version 10, no gateways which were configured with a version 9 data dictionary will be able to communicate with it.
The following configuration steps are optional. Perform these steps if you want to allow users other than PGAADMIN
to perform PG DD operations using PGAU.
Create public synonyms for the PG DD to allow other users to access the tables:
Create roles for accessing the PG DD, performing definitions of transactions, and generating TIP specifications. The PGAADMIN
user can grant these roles to other users as necessary.
Use SQL*Plus to connect to the Oracle Integrating Server as user PGAADMIN
.
From SQL*Plus, run the pgddcr8r.sql
script in the $ORACLE_HOME/pg4appc/admin
directory. This script creates two roles, PGDDDEF
and PGDDGEN
. The PGDDDEF
role provides SELECT
, INSERT
, UPDATE
, and DELETE
privileges against some of the PG DD tables, and SELECT
privileges against others, and allows execution of the PGAU DEFINE
, GENERATE
, REDEFINE
, REPORT
, and UNDEFINE
statements. The PGDDGEN role provides select privileges against the PG DD tables, and allows execution of the PGAU GENERATE
and REPORT
statements only.
SQL> @$ORACLE_HOME/pg4appc/admin/pgddcr8r.sql
Grant access to PGA required packages.
TIP developers require access to the following PL/SQL packages, which are shipped with the Oracle Integrating Server:
Explicit grants to execute these packages must be made to TIP developers.
These grants can be private as in the following example:
$ sqlplus SYS/pw@database_specification_string SQL> GRANT EXECUTE ON UTL_RAW TO tip_developer; SQL> GRANT EXECUTE ON UTL_PG TO tip_developer; SQL> GRANT EXECUTE ON DBMS_PIPE TO tip_developer; SQL> CONNECT PGAADMIN/pw@database_specification_string SQL> GRANT EXECUTE ON PGAADMIN.PURGE_TRACE TO tip_developer; SQL> GRANT EXECUTE ON PGAADMIN.READ_TRACE TO tip_developer; SQL> GRANT EXECUTE ON PGAADMIN.GPGLOCAL TO tip_developer; SQL> exit
Alternatively, these grants can be public as in the following example:
$ sqlplus SYS/pw@database_specification_string SQL> GRANT EXECUTE ON UTL_RAW TO PUBLIC; SQL> GRANT EXECUTE ON UTL_PG TO PUBLIC; SQL> GRANT EXECUTE ON DBMS_PIPE to PUBLIC; SQL> CONNECT PGAADMIN/pw@database_specification_string SQL> GRANT EXECUTE ON PGAADMIN.PURGE_TRACE TO PUBLIC; SQL> GRANT EXECUTE ON PGAADMIN.READ_TRACE TO PUBLIC; SQL> GRANT EXECUTE ON PGAADMIN.GPGLOCAL TO PUBLIC; SQL> EXIT
You can use either private or public grants. Both are sufficient for using PGA. Public grants are easier and can be performed now. If you use private grants, then they must be issued each time a new TIP developer user ID is created.
SQL scripts for performing these grants are provided in the $ORACLE_HOME/pg4appc/admin
directory. The pgddapub.sql
script performs these grants for public access to the packages. The pgddadev.sql
script performs the grants for private access to the packages by a single TIP developer. If you are going to use private grants, then you must run the pgddadev.sql
script once for each TIP developer user ID:
Use SQL*Plus to connect to the Oracle Integrating Server as user PGAADMIN
.
From SQL*Plus, run the appropriate script (pgddapub.sql
or pgddadev.sql
) from the $ORACLE_HOME/pg4appc/admin
directory. The script performs the necessary grants as described earlier. You are prompted for the required user IDs, passwords, and database specification strings.
If you are using private grants, then repeat this step for each user ID requiring access to the packages.
SQL> @$ORACLE_HOME/pg4appc/admin/pgddapub.sql SQL> @$ORACLE_HOME/pg4appc/admin/pgddadev.sql
If you are upgrading from a previous release of the gateway, and if you want to upgrade your existing TIPs with new function and maintenance, then regenerate existing TIP specifications using the PGAU GENERATE
statement.
Note:
The PGAU has been enhanced to automatically upgrade existing PG DD entries with a new attribute when a PGAU GENERATE command is executed. To support this enhancement, add a new privilege to the PGDDGEN role. To do this, as the PGAADMIN user, use SQL*Plus to connect to the Oracle Integrating Server where the PG DD is stored. Then issue the following SQL command:SQL> GRANT INSERT ON PGA_DATA_VALUES TO PGDDGEN
Invoke PGAU in the directory path where the PGAU control files are generated and where TIPs are stored:
$ pgau PGAU> CONNECT PGAADMIN/pgaadmin@database_specification_string PGAU> GENERATE tranname PGAU> EXIT
For more information about the GENERATE
command, refer to the PGAU GENERATE
command section in Chapter 2, of the Oracle Procedural Gateway for APPC User's Guide.
Note that it is not necessary to define the PG DD entries again.
Invoke SQL*Plus in the same directory path where the newly-generated TIP specifications are stored.
$ sqlplus tip_owner/pw@database_specification_string SQL> @tipname.pkh SQL> @tipname.pkb SQL> exit
PGAU GENERATE produces the TIP in two output files: a specification and a body. You must compile both, first the specification and then the body.
For more information about the GENERATE
command, refer to the PGAU GENERATE
command section in Chapter 2, of the Oracle Procedural Gateway for APPC User's Guide.
To configure the gateway, perform the following steps:
Tailor the Oracle Procedural Gateway for APPC parameters.
Parameters specific to the gateway are supplied in the gateway parameter file, init
sid
.ora
, which is in the $ORACLE_HOME/pg4appc/admin
directory. A sample gateway parameter file, initPGA.ora
is provided in this subdirectory.
Note:
In theinit
sid
.ora
file, substitute your pg4appc
SID name for "sid
" in this file name.
The init
sid
.ora
file contains both APPC and TCP/IP parameters, separated by a description. You must modify the init
sid
.ora
file by deleting the TCP/IP parameters. Refer to Appendix A, "Gateway Initialization Parameters for SNA Protocol" for the valid APPC parameters.
The parameters fall into two categories:
Gateway initialization parameters
These parameters control the general operation of the gateway in the Oracle environment.
Important:
Before performing the following step, refer to Appendix A, "Gateway Initialization Parameters for SNA Protocol" for information about tailoring gateway initialization and PGA parameters. Pay special attention to the information about using thePGA_CAPABILITY
parameter.PGA parameters control the APPC interface portion of the gateway. Use the SET
gateway initialization parameter to specify PGA parameters. Oracle recommends that you group all SET
commands for PGA parameters at the end of the init
sid
.ora
file.
Note:
If you are planning to implement commit-confirm, read the detailed explanation of commit-confirm's capabilities in Chapter 5 of the Oracle Procedural Gateway for APPC User's Guide, "Implementing Commit-Confirm (SNA Only) before proceeding.Follow these steps to configure the commit-confirm components. The steps for configuring commit-confirm include:
Configuring the Oracle Integrating Server where the gateway server will store its transaction log information
Configuring the gateway initialization parameters
Configuring the OLTP
All of these steps must be performed before attempting to use any applications that use commit-confirm.
The Oracle Integrating Server installation where the gateway server will store its transaction log information should ideally be on the same system where the gateway runs. The configuration of the server consists of creating the gateway DBA user, creating the commit-confirm log tables and creating the PL/SQL stored procedure used by the gateway server for logging transactions.
The pgaccau.sql
script from the $ORACLE_HOME/pg4appc/admin
directory creates the gateway DBA user ID. The default user ID is PGADBA
with the initial password set to PGADBA
. If you want to change the user ID or initial password, you must modify the script.
Use SQL*Plus to connect to the Oracle Integrating Server as the SYSTEM
user.
From SQL*Plus, run the pgaccau.sql
script from the $ORACLE_HOME/pg4appc/admin
directory. This script creates the gateway DBA user ID. If you want to change the password at any time after running this script, you can use the ALTER USER
command to change the password. For further information, refer to the Oracle Database SQL Reference.
Use SQL*Plus to connect to Oracle Integrating Server as the PGADBA
user.
From SQL*Plus, run the pgaccpnd.sql
script from the $ORACLE_HOME/pg4appc/admin
directory. This script creates the PGA_CC_PENDING
table used by the gateway server for its commit-confirm transaction log.
From SQL*Plus, run the pgacclog.sql
script from the $ORACLE_HOME/pg4appc/admin
directory. This script creates the PGA_CC_LOG
PL/SQL stored procedure used by the gateway server for updating the PGA_CC_PENDING
table.
Disconnect from Oracle Integrating Server.
The gateway initialization parameters are described in Appendix A, "Gateway Initialization Parameters for SNA Protocol". The parameters necessary for commit-confirm support in the gateway are:
PGA_CAPABILITY
PGA_LOG_DB
PGA_LOG_USER
PGA_LOG_PASS
PGA_RECOVERY_USER
PGA_RECOVERY_PASS
PGA_RECOVERY_TPNAME
These parameters should be added to your init
sid
.ora
file, where sid
is the gateway SID for your commit-confirm gateway.
Configuration of the OLTP includes defining and installing the following:
Commit-confirm transaction log database
Commit-confirm forget or recovery transaction
Sample commit-confirm applications provided with the gateway
Note:
A restart of the OLTP may be necessary to implement the changes required for commit-confirm support. You should plan for this with your OLTP system administrator.Detailed instructions for configuring the Transaction Server for z/OS and IMS/TM are provided in the $ORACLE_HOME/pg4appc/demo/CICS/README.doc
and $ORACLE_HOME/pg4appc/demo/IMS/README.doc
files, respectively.
Refer to "Implementing Commit-Confirm (SNA Only)" in the Oracle Procedural Gateway for APPC User's Guide for detailed information about commit-confirm. You will take steps to verify configuration of commit-confirm later in this chapter, in Chapter12, "Verifying OLTP Configuration for Commit-Confirm".
To verify the gateway installation and the OLTP configuration, perform the following procedures after installing Oracle Procedural Gateway for APPC. In addition, if you chose to configure commit-confirm, follow the steps to verify the OLTP configuration for commit-confirm.
Note:
If your database link name is notPGA
, modify the demonstration .sql
files to give them the particular database link name that you created in Step 5 of Chapter12, "Integrating Server Configuration: First-Time Gateway Installations". You must modify the following .sql
files:
To verify the gateway software installation using the database link PGA previously created, perform the following steps:
Using SQL*Plus, connect to your Oracle Integrating Server as PGAADMIN.
Run $ORACLE_HOME/pg4appc/demo/pgavsn.sql
.
SQL> @$ORACLE_HOME/pg4appc/demo/pgavsn.sql
The server version number banner appears at your terminal. The following output appears:
Oracle Procedural Gateway for APPC. Version 10.2.0.1.0 Thu Feb 13 13:12:49 2005 Copyright (c) Oracle Corporation 1979, 2005. All rights reserved.
PL/SQL procedure successfully completed.
The procedure for verifying your OLTP configuration varies, depending on which OLTP you are using and depending upon which platform the OLTP is running on. CICS Transaction Server for z/OS, IMS/TM, APPC/MVS, IDMS-DC, and z/OS are the currently supported OLTPs. Follow the instructions in the following sections for verifying installation:
Attention:
If you have not completed the file transfers detailed in Chapter12, "Preparing to Configure a Gateway Installation/Upgrade", complete them now, before proceeding to the next step.If your OLTP is CICS Transaction Server for z/OS, perform the following steps to verify the CICS configuration.
To verify that the FLIP transaction is installed correctly, log on to your CICS Transaction Server for z/OS and enter the following transaction, replacing FLIP
with the transaction ID you chose for FLIP
when you configure your CICS Transaction Server for z/OS for the gateway:
FLIP THIS MESSAGE
The following output appears:
EGASSEM SIHT PILF
Log on to HP-UX.
Modify the pgacics.sql
file, which is located at $ORACLE_HOME/pg4appc/demo/CICS/pgacics.sql
. Customize the following three items used for accessing the gateway and the CICS Transaction Server for z/OS as described in the comments at the beginning of the file:
Ensure that the SNA communication package on your system has been started.
Log on to your CICS Transaction Server for z/OS and run this transaction, where name
is the name of the CONNECTION definition installed by the DFHCSDUP job run in the CICS configuration steps:
CEMT SET CONNECTION(name) ACQUIRED
This transaction activates the CICS connection to HP-UX.
Use SQL*Plus to connect to your Oracle Integrating Server as PGAADMIN
.
SQL> @$ORACLE_HOME/pg4appc/demo/CICS/pgacics.sql
The following message appears:
==> Congratulations, your gateway is communicating with CICS <==
Your CICS Transaction Server for z/OS installation verification is complete.
If your OLTP is IDMS-DC, perform the following steps to verify the IDMS-DC configuration:
Log on to HP-UX.
Modify the pgaidms.sql
file, which is located at $ORACLE_HOME/pg4appc/demo/IDMS/pgaidms.sql
. Customize the following three items used for accessing the gateway and the IDMS-DC system as described in the comments at the beginning of the file:
IDMS-DC transaction ID
Side Profile Name
Logmode entry name
Ensure that the SNA communication package on your system has been started.
Using the IDMS-DC DCMT transaction, display the LU6.2 line to check that sessions have been started with your system. Enter the following command, where linename
is the name of the LINE defined for LU6.2 communications with your system:
DCMT DIS LINE linename
Each defined LTERM
/PTERM
should show a status of INSRV
. Any other status indicates a problem with the IDMS-DC APPC interface
Use SQL*Plus to connect to Oracle Integrating Server as PGAADMIN
.
SQL> @$ORACLE_HOME/pg4appc/demo/IDMS/pgaidms.sql
The following message appears:
==> Congratulations, your gateway is communicating with IDMS-DC<==
Your IDMS-DC installation verification is now complete.
If your OLTP is IMS/TM, then perform the following steps to verify the IMS/TM configuration:
To verify that the FLIP transaction is installed correctly, log on to your IMS/TM system and enter the following transaction, replacing FLIP
with the transaction ID you chose for FLIP
when you configured your IMS/TM system for the gateway:
FLIP THIS MESSAGE
The following output appears on your terminal:
EGASSEM SIHT PILF
Log on to HP-UX.
Modify the pgaims.sql
file, which is located at $ORACLE_HOME/pg4appc/demo/IMS/pgaims.sql
. Customize the following three items used for accessing the gateway and the IMS/TM system as described in the comments at the beginning of the file:
IMS/TM transaction ID
Side Profile Name
Logmode entry name
Ensure that the SNA communication package on your system has been started.
Use SQL*Plus to connect to Oracle Integrating Server as PGAADMIN
.
SQL> @$ORACLE_HOME/pg4appc/demo/IMS/pgaims.sql
The following message appears:
==> Congratulations, your gateway is communicating with IMS/TM <==
Your IMS/TM installation verification is now complete.
If your OLTP is APPC/MVS, perform the following steps to verify the APPC/MVS configuration:
Verify that your APPC/MVS subsystem is active.
Log on to the HP-UX system
Modify the pgamvs.sql
file, which is located at $ORACLE_HOME/pg4appc/demo/MVS/pgamvs.sql
. Customize the following three items used for accessing the gateway and the APPC/MVS system as described in the comments at the beginning of the file:
APPC/MVS transaction ID
Side Profile Name
Logmode entry name
Ensure that the SNA communication package on your system has been started.
Use SQL*Plus to connect to your Oracle Integrating Server as PGAADMIN
.
Run pgamvs.sql
.
SQL> @$ORACLE_HOME/pg4appc/demo/MVS/pgamvs.sql
The following message appears:
=> Congratulations, your gateway is communicating with APPC/MVS <=
Your APPC/MVS installation verification is now complete.
If you chose to configure commit-confirm in Chapter12, "Configuring Commit-Confirm", the following section will assist you in verifying the configuration.
Note:
Refer to Chapter 5, "Implementing Commit-Confirm" in the Oracle Procedural Gateway for APPC User's Guide for background information on the components and capabilities of commit-confirm.Samples are provided with the gateway for Transaction Server for z/OS and IMS/TM for implementing commit-confirm support. They are in the following directories, respectively: $ORACLE_HOME/pg4appc/demo/CICS
and $ORACLE_HOME/pg4appc/demo/IMS
. A README.doc
file in each directory provides detailed information about installing and using the samples. JCL files for compiling and linking the sample programs are provided as well. The samples included with the gateway assist you with the following:
Creating and initializing the commit-confirm transaction log databases and defining those databases to the OLTP
For Transaction Server for z/OS, the sample uses a VSAM file for the log database. For IMS/TM, a SHISAM/VSAM database is used.
Using subroutines for receiving the Oracle Global Transaction ID from the gateway and logging it into the commit-confirm transaction log database
These subroutines are provided in the pgacclg.asm
files. They can be used in your applications to reduce the complexity of the code changes to your programs. For Transaction Server for z/OS, the subroutine provided is called using the EXEC CICS LINK interface. For IMS/TM, the subroutine provided is called using the standard CALL statement or its equivalent in the application programming language. Both of these subroutines are written in 370 assembler to eliminate any interlanguage interface complexities and compiler dependencies.
Forget and recovery transactions
These are provided in the pgareco.asm
files. Forget and recovery transactions must be installed into your OLTP and accessible through APPC so that the gateway can invoke them to forget a transaction once it has been successfully committed, and to query transaction state during recovery processing. These transactions delete the entry for a particular Oracle Global Transaction ID from the OLTP commit-confirm transaction log database during forget processing, and query the entry for a particular Oracle Global Transaction ID from the OLTP commit-confirm transaction log database during recovery processing. For both Transaction Server for z/OS and IMS/TM, these transactions are written in 370 assembler.
Using the sample commit-confirm transaction log databases and subroutines
For Transaction Server for z/OS, a sample DB2 update transaction, DB2C
, is provided in the pgadb2c.cob
file. This is a COBOL example that updates the DB2 sample EMP
table. For IMS/TM, a sample DLI update transaction, PGAIMSU
, is provided in the pgaimsu.cob
file. This is a COBOL example that updates the DLI sample PARTS database.
The following are optional steps that you can perform as necessary. Installation of the sample applications for your OLTP is recommended to help you to fully understand how the gateway works and how it interfaces with your OLTP.
Oracle Procedural Gateway for APPC package contains the following sample PL/SQL procedures and OLTP transaction programs that demonstrate the capabilities of the gateway.
APPC/MVS
z/OS data set information
CICS Transaction Server for z/OS
ADABAS inquiry
DB2 inquiry
DB2 multi-row inquiry
DB2 update
VSAM inquiry
VSAM update
DLI inquiry
FEPI DB2 inquiry
FEPI VSAM inquiry
IDMS-DC
IDMS/R inquiry
IMS/TM
IMS inquiry using IVTNO and IVTNV sample transactions
IMS PARTS update (CPI-C)
Additional samples are added to the distribution media in later releases of the product. Wherever possible, sample applications use the sample databases provided with the database products.
For this release, full documentation on installing and using the sample applications is available in the README.doc
files in the following directories: