This appendix describes the gateway initialization file location and lists the gateway initialization parameters supported by the Oracle Procedural Gateway for APPC specifically for the SNA protocol. These parameters are fully documented in Section 12.1, "Migrating an Existing Gateway Instance to New Release Using SNA Protocol". In addition, this appendix contains sample listener.ora and tnsnames files for a gateway using SNA.
This appendix contains the following section:
The parameter file for the gateway is located in the %ORACLE_HOME%\pg4appc\admin directory and is called initsid.ora.
Note:
The initsid.ora file contains both SNA and TCP/IP parameters. You must modify these files with the suitable parameters.The PGA parameters control the APPC interface portion of the gateway.
PGA parameters are specified using the SET gateway initialization parameter. For 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 of PGA parameters and their descriptions.
Table A-1 PGA Parameters for Gateway Using SNA
Parameter | Description |
---|---|
where:
|
|
PGA transaction capability. This controls whether updates are allowed through the gateway. The following are valid values:
The default is |
|
Incoming
The default is |
|
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 There is no default value. |
|
The Oracle password to be used by the gateway when connecting to the Oracle server specified by the There is no default value. |
|
The Oracle user ID to be used by the gateway when connecting to the Oracle server specified by the There is no default value. |
|
The password to be used by the gateway when allocating an APPC conversation with the transaction specified by the There is no default value. |
|
The TP name of the transaction installed in the online transaction processor (OLTP) for commit-confirm The default value is |
|
The user ID to be used by the gateway when allocating an APPC conversation with the transaction specified by the There is no default value. |
|
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:
The default is For further information about these options, refer to Chapter 11, "Security Requirements". |
|
PGA trace level. This controls tracing output written to stderr (the target of the The default is 0, indicating no tracing. Any value between 1 and 255 will turn on tracing. |
When choosing a setting for the PGA_CAPABILITY
parameter, take care to ensure that the correct setting is used based on what the RTPs will be doing.
The READ_ONLY
setting should always be used when the RTPs are read-only, that is, when the RTPs perform no database updates. READ_ONLY
should never be used when the RTPs perform database updates. For example, if the READ_ONLY
setting is chosen, and if a RTP called by the gateway performs updates to a foreign database, then the Oracle Integrating Server does not provide any integrity protection for those updates. Further, READ_ONLY
mode allows a gateway transaction to be part of a distributed transaction that might update several other databases. If the gateway calls a RTP that performs updates in this situation and if a failure occurs, then the database updated by the RTP is out of sync with the other databases.
In cases where the RTPs perform updates to foreign databases, there are two options for PGA_CAPABILITY
:
SINGLE_SITE
COMMIT_CONFIRM
Each of these options provides protection against data integrity problems by permitting COMMIT
and ROLLBACK
requests to be forwarded to the RTP 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 RTPs and upon the capabilities of the OLTP where they execute.
If the OLTP has LU6.2 SYNCLEVEL 1 or 2 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 RTP 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. Also refer to Section 9.8.3, "Configuring the OLTP for Commit-Confirm" in this guide. For SINGLE_SITE
capability, the RTP is responsible for performing the suitable 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
command, the RTP must perform COMMIT
processing and then respond to the gateway with an APPC
CONFIRMED
response. On receipt of a SEND_ERR
command, the RTP 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 RTP, 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 RTPs which perform updates to foreign databases outside the scope of control of the Oracle Integrating Server. 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, a COMMIT_CONFIRM
gateway can be used, provided that the OLTP and the RTPs 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:
an entry in the listener.ora file defining the sid of the gateway instance
an entry in the tnsnames.ora file defining an alias to be used to connect to the gateway instance defined in listener.ora
a database link in the Oracle Integrating Server that specifies the alias defined in the tnsnames.ora file in its USING
parameter.
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), the following steps are required:
Define two aliases in tnsnames.ora that connect to the two new sid
s, PGAI and PGAU.
Define two database links in the Oracle Integrating Server, one connecting to PGAI and the other connecting to PGAU.
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.
When deciding upon 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 suitable 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
request. In order 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 7. When using the implied APPC support that is provided by IMS/TM version 7, 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
request 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.
LISTENER = (ADDRESS_LIST = (ADDRESS= (COMMUNITY= TCP.world) (Host = bay) (PROTOCOL= TCP) (Port= 2621) ) (ADDRESS= (COMMUNITY= TCP.world) (Host = bay) (PROTOCOL= TCP) (Port= 2623) ) ) SID_LIST_LISTENER = (SID_LIST = (SID_DESC = (SID_NAME = PGA) (ORACLE_HOME = C:\oracle\pga\10.2) (PROGRAM = pg4asrv) ) )
ORA920 = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = bay.us.oracle.com)(PORT = 1521)) ) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = ORA920.bay) ) ) PGA = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = bay)(PORT = 2621)) ) (CONNECT_DATA = (SID = PGA) ) (HS = OK) )