Skip Headers

Oracle® Procedural Gateway for APPC Installation and Configuration Guide
Release 9.2.0.1.0 for Windows

Part Number A96651-01
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

A
Gateway Initialization Parameters

This appendix describes the gateway initialization file location and lists the gateway initialization parameters that are supported by Oracle Procedural Gateway for APPC. These parameters are documented fully in Chapter 7, "Migration and Coexistence with Existing Gateways". This appendix contains the following sections:

Gateway Initialization Parameter File

The parameter file for Oracle Procedural Gateway for APPC is located in the C:\orant\pg4appc\admin directory and is called initsid.ora.

PGA Parameters

The PGA parameters control the APPC interface portion of the gateway.

PGA parameters are supplied using the SET gateway initialization parameter, as in the following example:

SET pga_parm=value 

where pga_parm is one of the PGA parameter names in the list that follows, and value is a character string with contents that depend on pga_parm.

Table A-1 provides a list and description of PGA parameters.


Note:

Other parameters can be added to this file. Refer to "Parameter Changes for Version 4 to Release 9i Migration of Gateway" in Chapter 7, "Migration and Coexistence with Existing Gateways" for more information.


Note Also:

Mis-spelled gateway parameters are ignored.

Table A-1 PGA Parameters
Parameter Description

LOG_DESTINATION=logpath

logpath specifies the destination at which stderr is reopened. LOG_DESTINATION specifies a directory only and stderr is reopened to
logpath\sid_pid.log

where:

sid is the sid name, and

pid is the process ID assigned to the gateway

PGA_CAPABILITY

PGA transaction capability. This controls whether updates are allowed through the gateway. The following are valid values:

READ_ONLY or RO - read-only capabilities.

SINGLE_SITE or SS - single-site update only. This indicates that in a distributed environment, only the gateway can perform updates. No other database updates can occur within the Oracle transaction.

COMMIT_CONFIRM or CC - commit-confirm. This indicates that in a distributed environment, updates can be performed by both the gateway and other participants within the Oracle transaction. The gateway is always committed first in this mode, and no other commit-confirm sites are allowed to participate in the Oracle transaction.

The default is SINGLE_SITE.

PGA_CONFIRM

Incoming APPC CONFIRM request handling option. This controls what the gateway does when an APPC CONFIRM request is received from the remote transaction program. This parameter has meaning only when the conversation is running with
SYNCLEVEL > 0. The following values are valid:

ACCEPT - respond to incoming APPC CONFIRM requests with APPC CONFIRMED responses.

REJECT - treat incoming APPC CONFIRM requests as errors causing the conversation to be de-allocated and an error message to be issued.

The default is REJECT.

PGA_LOG_DB

The Oracle Net service name for the Oracle server in which the gateway maintains its transaction log. This parameter can be from 1 to 255 characters long. This parameter is required only when PGA_CAPABILITY is set to COMMIT CONFIRM.

There is no default value.

PGA_LOG_PASS

The Oracle password to be used by the gateway when connecting to the Oracle server specified by the
PGA_LOG_DB parameter. The password can be from 1 to 30 characters long. This parameter is required only when PGA_CAPABILITY is set to
COMMIT_CONFIRM. For more information, refer to "Using the pg4pwd Utility".

There is no default value.

PGA_LOG_USER

The Oracle user ID to be used by the gateway when connecting to the Oracle server specified by the
PGA_LOG_DB parameter. The user ID can be from 1 to 30 characters long. This parameter is required only when PGA_CAPABILITY is set to
COMMIT_CONFIRM.

There is no default value.

PGA_RECOVERY_PASS

The password used by the gateway when allocating an APPC conversation with the transaction specified by the
PGA_RECOVERY_TPNAME parameter. The password can be from 1 to 8 characters long. This parameter is required only when PGA_CAPABILITY is set to
COMMIT_CONFIRM and PGA_SECURITY_TYPE is set to PROGRAM. For more information, refer to "Using the pg4pwd Utility".

There is no default value.

PGA_RECOVERY_TPNAME

The TP name of the transaction installed in the OLTP for commit-confirm FORGET and RECOVERY processing. The TP name can be from 1 to 64 characters long. For CICS/ESA, the TP name is limited to 4 characters. For IMS/TM, the TP name is limited to 8 characters. Other OLTPs might have other limits on the length of the TP name. This parameter is required only when
PGA_CAPABILITY is set to COMMIT_CONFIRM.

The default value is RECO.

PGA_RECOVERY_USER

The user ID used by the gateway when allocating an APPC conversation with the transaction specified by the
PGA_RECOVERY_TPNAME parameter. The user ID can be from 1 to 8 characters long. This parameter is required only when PGA_CAPABILITY is set to COMMIT_CONFIRM and PGA_SECURITY_TYPE is set to PROGRAM or SAME.

There is no default value.

PGA_SECURITY_TYPE

APPC conversation security option. This controls what security parameters are sent to the OLTP in the FMH-5 at conversation allocation. The following are valid values:

NONE - which sends no security parameters

PROGRAM - which sends a user ID and password

The default is NONE. For more information on these options, refer to "Using SNA Security Validation".

TRACE_LEVEL

PGA trace level. This controls tracing output written to stderr (the target of the LOG_DESTINATION parameter.) The value must be an integer from 0 to 255.

The default is 0, indicating no tracing.

Sample Gateway Initialization File

############################################################################

#
#
#               SAMPLE initPGA.ora file for PG4APPC for NT                                       
#
#
#
############################################################################

#
FDS_CLASS=PG4APPC_9I
FDS_CLASS_VERSION=2
FDS_INSTANCE=PGA
#SET TRACE_LEVEL=255
#SET LOG_DESTINATION=C:\ORANT\pg4appc\log
#
HS_COMMIT_POINT_STRENGTH=255
HS_DB_NAME=PGA
HS_DB_DOMAIN=WORLD
HS_DB_INTERNAL_NAME=504741
#
SET PGA_CAPABILITY=SINGLE_SITE
SET PGA_SECURITY_TYPE=NONE
SET PGA_SIGDANGER=IGNORE

PGA_CAPABILITY Parameter Considerations

When choosing a setting for the PGA_CAPABILITY parameter, take care to ensure that the correct setting is used based on what the remote transaction programs are doing.

Use the READ_ONLY setting when the remote transaction programs are read-only; that is, when the remote transaction programs perform no database updates. Do not use READ_ONLY when the remote transaction programs perform database updates. For example, if the READ_ONLY setting is chosen, and if a remote transaction program invoked by the gateway performs updates to a foreign database, then the Oracle Integrating Server does not provide any integrity protection for those updates. Furthermore, READ_ONLY mode allows a gateway transaction to be part of a distributed transaction that might update several other databases. If the gateway invokes a remote transaction program that performs updates in this situation, and if a failure occurs, then the database updated by the remote transaction program is out of sync with the other databases.

In cases where the remote transaction programs perform updates to foreign databases, there are two options for PGA_CAPABILITY:

Each of these options provides protection against data integrity problems by allowing COMMIT and ROLLBACK requests to be forwarded to the remote transaction program, and by informing the Oracle Integrating Server about the distributed update and recovery capabilities of the gateway. The particular option chosen depends on the design of the remote transaction programs and on the capabilities of the OLTP (online transaction processor) where they execute.

If the OLTP has only LU6.2 SYNCLEVEL 1 support, then the COMMIT_CONFIRM capability provides limited two-phase commit between the Oracle Integrating Server and the OLTP, with the restriction that no other commit-confirm site (gateway or Oracle) can be part of the distributed transaction. If it is not possible to use COMMIT_CONFIRM, then the SINGLE_SITE capability provides update capability between the Oracle Integrating Server and the OLTP, with the restriction that only the OLTP can perform updates, and no updates can occur on the Oracle side.

Each of the PGA_CAPABILITY options for update control imposes specific requirements on the remote transaction program and on the OLTP. For
COMMIT_CONFIRM capability, these requirements are discussed in detail in Chapter 5, "Implementing Commit-Confirm," of the Oracle Procedural Gateway for APPC User's Guide. For SINGLE_SITE capability, the remote transaction program is responsible for performing the appropriate tasks in response to COMMIT and ROLLBACK requests received from the gateway on behalf of the Oracle Integrating Server. The gateway uses the APPC CONFIRM and SEND_ERR requests to implement COMMIT and ROLLBACK, respectively. On receipt of a CONFIRM, the remote transaction program must perform COMMIT processing and then respond to the gateway with an APPC CONFIRMED response. On receipt of a
SEND_ERR, the remote transaction program must perform ROLLBACK processing.

Because the distributed transaction capability of the Oracle Integrating Server is affected by the PGA_CAPABILITY option used by the gateway, it is desirable to separate inquiry and update applications by using different gateway instances for each. One gateway can be defined with PGA_CAPABILITY set to READ_ONLY and others with PGA_CAPABILITY set to SINGLE_SITE or COMMIT_CONFIRM.

This allows read-only transaction programs to participate in distributed transactions under the control of the Oracle Integrating Server. For example, data from DB2 can be retrieved through the READ_ONLY gateway by an inquiry-only remote transaction program, and can then be used as input to database updates on the Oracle Integrating Server, all in one Oracle transaction. A
SINGLE_SITE gateway can be used only for accessing remote transaction programs which perform updates to foreign databases outside the scope of the Oracle Integrating Server's control. Data can be read from any databases accessible to the Oracle Integrating Server, and that data can be used to perform updates through the gateway.

When it is necessary to update resources on both the Oracle side and the OLTP side, you can use a COMMIT_CONFIRM gateway, provided that the OLTP and the remote transaction programs are set up to implement commit-confirm.

All that is necessary to set up multiple gateway instances is to set up the following for each instance:

Note that the gateway instances can share one common directory structure, and use the same executables.

For example, to set up two gateways, PGAI and PGAU (for inquiry and update use, respectively), perform the following:

  1. Define entries in listener.ora for two SIDs, PGAI and PGAU.

  2. Define two aliases in tnsnames.ora that connect to the two new SIDs, PGAI and PGAU.

  3. Define two database links in the Oracle Integrating Server, one connecting to PGAI and the other connecting to PGAU.

  4. Finally, create the initialization files initPGAI.ora and initPGAU.ora.

    In initPGAI.ora, set PGA_CAPABILITY to READ_ONLY, and in initPGAU.ora, set PGA_CAPABILITY to SINGLE_SITE or COMMIT_CONFIRM. Then, use the PGAI gateway for inquiry-only transactions, and use the PGAU gateway for update transactions.

    The same steps can be used to set up additional gateway instances.

PGA_CONFIRM Parameter Considerations

When deciding on the setting for the PGA_CONFIRM parameter, it is important to understand the effects of each setting. First, keep in mind that this parameter affects only those conversations running at SYNCLEVEL 1. The default setting,
PGA_CONFIRM=REJECT, is appropriate for most applications. With this setting, the gateway generates an error if a CONFIRM request is received from the remote transaction program. If you have a remote transaction that uses CONFIRM to verify that data was received by the gateway, then you must use
PGA_ CONFIRM=ACCEPT to allow the gateway to respond to those incoming CONFIRM requests with CONFIRMED responses. You must be aware that the gateway sends CONFIRM requests to the remote transaction when the Oracle application has issued a COMMIT. For the COMMIT processing to work correctly, the remote transaction must be written to perform its local commit processing whenever a CONFIRM request is received from the gateway, and respond to the gateway with CONFIRMED after the commit processing has successfully completed. If an error occurs during commit processing, then the remote transaction must respond to the gateway with SEND_ERR to indicate that the commit failed.

One special case for the use of PGA_CONFIRM=ACCEPT is with IMS/TM version 6. When using the "implied APPC" support that is provided by IMS/TM version 6, conversations that run at SYNCLEVEL 1 are handled differently than conversations that run at SYNCLEVEL 0. IMS/TM automatically generates CONFIRM requests after each APPC SEND when the conversation is at SYNCLEVEL 1. On the gateway side, if PGA_CONFIRM=ACCEPT is not specified, then the CONFIRM requests sent by IMS/TM result in errors generated by the gateway. Using PGA_CONFIRM=ACCEPT alleviates this problem, allowing the gateway to respond to incoming CONFIRM requests with CONFIRMED responses. The only limitation with running this way is that the implied APPC support provided by IMS does not notify the application when a CONFIRM is received from the gateway. This means that the gateway cannot use CONFIRM to implement COMMIT, thereby disabling the use of COMMIT/ROLLBACK to control updates on the IMS side of the conversation.


Go to previous page Go to next page
Oracle
Copyright © 1996, 2002 Oracle Corporation.

All Rights Reserved.
Go To Table Of Contents
Contents
Go To Index
Index