8
Gateway Running Environment

Relaxed Model

This model discards the Oracle username and password.  The authorizations granted to the effective user ID of the gateway by the queue manager are the only associations an Oracle application has.  For example, if the gateway's user ID is granted permission to open or read messages, or place messages on a queue, then all Oracle applications that access the gateway can request those operations. 

The effective user ID is determined by how the gateway is running:

• If the gateway runs as an MQI client application, then the user ID is determined by the MQI channel definition (refer to IBM publications for more information about channel definitions)

• If the gateway runs as an MQI server application, then the effective user ID of the gateway is the user who started the Oracle Net listener and who must have authorization to all the MQSeries objects that the Oracle application wants to access.  Refer to "Authorization for MQSeries Objects" for more information

Oracle Corporation recommends against using the relaxed model unless your application has minimal security requirements.

Strict Model

This model uses the Oracle user ID and password provided in the Oracle CREATE DATABASE LINK statement when a database link is created, or the current Oracle user ID and password if none was provided with CREATE DATABASE LINK. 

The Oracle user ID:

• should match a user account for the computer that runs the gateway and for the computer that runs the MQSeries queue manager

• must have authorization for all the accessed MQSeries objects.  Refer to "Authorization for MQSeries Objects" for more information

The authorization process to verify the Oracle user ID and password varies depending on how the gateway is running.

Authorization for MQSeries Objects

The effective user ID for the relaxed model and the Oracle user ID for the strict model require the following MQSeries authorizations:

Table 8-1 MQ Series Access Authorization

Refer to IBM publications for more information about MQSeries authorizations.

Non-Oracle Data Sources and Distributed Transactions

This section describes generic transaction support features of Oracle Server.

When an Oracle distributed database contains a gateway, the gateway must be properly configured to take part in a distributed transaction.  The outcome of a distributed transaction involving a gateway should be that all participating sites roll back or commit their parts of the distributed transaction.  All participating sites, including gateway sites, that are updated during a distributed transaction must be protected against failure and must be able to take part in the two-phase commit mechanism.  A gateway that updates a target system as part of a distributed transaction must be able to take part in the automatic recovery mechanism, which might require that recovery information be recorded in transaction memory at the target system.

If a SQL-based gateway is involved in a distributed transaction, the distributed database must be in a consistent state after the distributed transaction is committed.

A procedural gateway or a SQL-based gateway with the procedural option translates remote procedure calls into target system calls.  From the viewpoint of the Oracle transaction model, the gateway appears to be an Oracle server executing a PL/SQL block containing SQL statements used to access an Oracle database.

For a procedural gateway, it is unknown whether a target system call alters data.  To ensure the consistency of a distributed database, it must be assumed that a procedural gateway updates the target system.  Accordingly, all remote procedure calls sent to a procedural gateway take part in a distributed transaction and must be protected by the two-phase commit protocol.  For example, you could issue the following SQL*Plus statements:

EXECUTE REMOTE_PROC@FACTORY;
INSERT INTO DEBIT@FINANCE
ROLLBACK;

In the example, REMOTE_PROC is a remote procedure call to access a procedural gateway, DEBIT is an Oracle table residing in an Oracle database, and FACTORY and FINANCE are database links used to access the remote sites.

Transaction Capability Types

This section describes generic transaction support features of Oracle Server.

When gateways are involved in a distributed transaction, the transaction capabilities of the non-Oracle data source determine whether the data source can participate in two-phase commit operations or distributed transactions.

Depending on the transaction capabilities of the non-Oracle data source, it can be mapped to one of the following transaction types:

Transaction Capability Types of Procedural Gateway for IBM MQSeries

This section describes transaction capabilities of the Oracle Procedural Gateway for IBM MQSeries.

Transactions from an Oracle application (that invoke MQSeries message queue operations and that are using the gateway) are managed by the Oracle transaction coordinator at the Oracle server where the transaction originates.  The procedural gateway for IBM MQSeries provides the following transaction types:

• single-site

• commit-confirm

Message and Error Code Processing

The gateway architecture includes a number of separate components.  Any of these components can detect and report an error condition while processing PL/SQL code.  An error condition can be complex, involving error codes and supporting data from multiple components.  In all cases, the Oracle application receives a single Oracle error code upon which to act.

Error conditions are represented in three ways:

1. Errors from the Oracle integrating server

   Messages from the Oracle integrating server are in the format ORA-xxxxx or PLS-xxxxx, where xxxxx is a code number.  ORA-xxxxx is followed by text explaining the error code.  Refer to the Oracle9i Database Error Messages for explanations of these errors. 

   Example:

   PLS-00306: wrong number or types of arguments in call to 'MQOPEN'
   ORA-06550: line7, column 3:
   PL/SQL: Statement ignored
   
   

2. Errors from the gateway

   Most gateway error conditions are reported to your application using one of the gateway error codes in the range of ORA-00700 through ORA-00799, ORA-08502 through ORA-08599, or ORA-09100 through ORA-09199.  If an error is detected by the Oracle integrating server, then the gateway message lines do not occur.  For example, if the gateway cannot be accessed because of an Oracle Net or gateway installation problem, then the gateway message line is not present in the generated error.

   The message format is explained under "Interpreting Gateway Messages".  Refer to the Oracle Open Gateway Guide for SQL-Based and Procedural Gateways for an explanation of messages in these number ranges.

   Example:

   ORA-09119: Initialization file contains error.
   ORA-00718: Value "3" illegal for parameter "TRACE_LEVEl"
   ORA-02063: preceding 2 lines from PG4MQ
   
   

3. MQSeries errors

   When possible, an MQSeries error code is converted to an Oracle error code.  If that is not possible, then the Oracle error ORA-08500 with the corresponding MQSeries error code is returned.  Refer to "Common Error Codes" for more information. 

   
   

   Note: Because the Oracle integrating server distinguishes only between a successful or failed outcome of all user operations, MQI calls that return a warning are reported as a successful operation.

   
   

   Example:

   ORA-08500: The IBM MQSeries MQI call "MQOPEN" fails with reason code 2085
   ORA-06512: at line 8
   

ORA-nnnnn:error_message_text
gateway_message_line
ORA-02063: preceding n lines from dblink 

Common Error Codes

The error conditions that are described in this section are common error conditions that an application might receive while using the gateway, but do not cover all error situations.

Gateway Tracing

The gateway has a trace feature for testing or debugging purposes.  The trace feature collects information about the gateway running environment, MQI calls, and parameter values of MQI calls.  How much trace data to collect is based on the tracing level selected with the TRACE_LEVEL parameter.  Do not enable tracing when your application is running in a production environment because it reduces gateway performance.  Refer to Appendix C, " Gateway Initialization Parameters" for more information about enabling tracing.

The trace data is written to the directory and file specified by the LOG_DESTINATION parameter.

LOG_DESTINATION = log_file

Calling MQCONN()
         Name = mgr.nlsu41.1
         pHconn = 273248
Returning from MQCONN()
         Name = mgr.nlsu41.1
         Hconn = 2849264
         CompCode = 0
         Reason = 0
Calling MQOPEN()
         Hconn = 2849264
         pObjDesc = efffed58
         ObjectName = QUEUE2
         Options = 16
         pHobj = 274468
Returning from MQOPEN()
         Hconn = 2849264
         pObjDesc = efffed58
         Options = 16
         Hobj = 239888
         CompCode = 0
         Reason = 0
Calling MQCMIT()
         Hconn = 2849264
Returning from MQCMIT()
         Hconn = 2849264
         CompCode = 0
         Reason = 0
Calling MQDISC()
         Hconn = 2849264
Returning from MQDISC()
         Hconn = -1
         CompCode = 0

Verifying Gateway Operation

If your application cannot connect to the gateway, then rerun the application with the gateway trace feature enabled.  If no trace information is written to the log file specified by LOG_DESTINATION, or if the log file is not created at all, then verify that:

• the Oracle Net configuration for the gateway and the Oracle integrating server is set up properly (refer to "Configuring Oracle Net for the Gateway")

• a database link between the Oracle integrating server and the gateway was created ("Administering Database Links")

If the Oracle Net configuration and database link are set up correctly, then check the gateway's operation with the test.sql script:

1. Change directory to the gateway sample directory by entering:

   $ cd $ORACLE_HOME/pg4mqseries/sample
   

2. Using an editor, modify the test.sql script to:

   1. Specify the database link name that you created for the gateway.  To do this, replace the characters @pg4mq with @dblink, where dblink is the name you chose when the database link was created.

   2. Replace the characters YOUR_QUEUE_NAME with a valid MQSeries queue name.

3. Using SQL*Plus, connect to your Oracle integrating server as a valid user.

4. Run test.sql, a script that sends and retrieves a message from an MQSeries queue.  A successful completion displays the following output:

   SQL> @test.sql
   message put on queue = 00102030405060708090
   message read back = 00102030405060708090
   
   PL/SQL procedure successfully completed.
   

   An unsuccessful test displays the following output:

   SQL> @test.sql
   message put on queue = 00102030405060708090
   Error: Procedural Gateway for IBM MQSeries verification script failed.
   ORA-08500: The IBM MQSeries MQI call "MQOPEN" fails with reason code 2085