Skip Headers
Oracle® Streams Advanced Queuing User's Guide and Reference
10g Release 2 (10.2)

Part Number B14257-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

19 Working with Oracle Messaging Gateway

After Oracle Messaging Gateway (MGW) is loaded and set up, it is ready to be configured and run. This chapter describes how to manage the Messaging Gateway agent and how to configure propagation.

This chapter contains these topics:

Note:

All commands in the examples must be run as a user granted MGW_ADMINISTRATOR_ROLE.

See Also:

"DBMS_MGWADM" and "DBMS_MGWMSG" in PL/SQL Packages and Types Reference

19.1 Configuring the Oracle Messaging Gateway Agent

Messages are propagated between Oracle Streams AQ and non-Oracle messaging systems by the Messaging Gateway agent. The Messaging Gateway agent runs as an external process of the Oracle Database server.

You must set the following information in order for the agent to start:

19.1.1 Database Connection

The Messaging Gateway agent runs as a process external to the database. To access Oracle Streams AQ and the Messaging Gateway packages, the Messaging Gateway agent needs to establish connections to the database. You can use DBMS_MGWADM.DB_CONNECT_INFO to set the username, password and the database connect string that the Messaging Gateway agent will use for creating database connections. The user must be granted the role MGW_AGENT_ROLE before the Messaging Gateway agent can be started.

You can call DBMS_MGWADM.DB_CONNECT_INFO to alter connection information when the Messaging Gateway agent is running.

Example 19-1 shows Messaging Gateway being configured for user mgwagent with password mgwagent_password using net service name mydatabase.

Example 19-1 Setting Database Connection Information

SQL> exec dbms_mgwadm.db_connect_info(username => 'mgwagent', 
                                      password => 'mgwagent_password',
                                      database => 'mydatabase');

19.1.2 Resource Limits

You can use DBMS_MGWADM.ALTER_AGENT to set the maximum number of messaging connections used by the Messaging Gateway agent, the heap size of the Messaging Gateway agent process, and the number of propagation threads in the agent process. The default values are one connection, 64 MB of memory heap, and one propagation thread.

Example 19-2 sets the number of database connections to two, the heap size to 64MB, and the number of propagation threads to two.

Example 19-2 Setting the Resource Limits

SQL> exec dbms_mgwadm.alter_agent(max_connections => 2,
                                  max_memory => 64,
                                  max_threads => 2);

You can alter the maximum number of connections when the Messaging Gateway agent is running. The memory heap size and the number of propagation threads cannot be altered when the Messaging Gateway agent is running. Example 19-3 updates the maximum number of connections to three but leaves the maximum memory and the number of propagation threads unchanged.

Example 19-3 Updating the Maximum Connection Number

SQL> exec dbms_mgwadm.alter_agent(max_connection => 3);

19.2 Starting and Shutting Down the Oracle Messaging Gateway Agent

This section contains these topics:

19.2.1 Starting the Oracle Messaging Gateway Agent

After the Messaging Gateway agent is configured, you can start the agent with DBMS_MGWADM.STARTUP, as shown in Example 19-4.

Example 19-4 Starting the Messaging Gateway Agent

SQL> exec dbms_mgwadm.startup;

You can use the MGW_GATEWAY view to check the status of the Messaging Gateway agent, as described in Chapter 21, "Monitoring Oracle Messaging Gateway".

19.2.2 Shutting Down the Oracle Messaging Gateway Agent

You can use DBMS_MGWADM.SHUTDOWN to shut down the Messaging Gateway agent, as shown in Example 19-5.

Example 19-5 Shutting Down the Messaging Gateway Agent

SQL> exec dbms_mgwadm.shutdown;

You can use the MGW_GATEWAY view to check if the Messaging Gateway agent has shut down successfully, as described in Chapter 21, "Monitoring Oracle Messaging Gateway".

19.2.3 Oracle Messaging Gateway Agent Job Queue Job

Messaging Gateway uses a job queue job to start the Messaging Gateway agent. This job is created when procedure DBMS_MGWADM.STARTUP is called. When the job is run, it calls an external procedure that creates the Messaging Gateway agent in an external process. The job is removed after:

  • The agent shuts down because DBMS_MGWADM.SHUTDOWN was called

  • The agent terminates because a non-restartable error occurs

The DBMS_JOB package creates a repeatable job with a repeat interval of two minutes. The job is owned by SYS. A repeatable job enables the Messaging Gateway agent to restart automatically when a given job instance ends because of a database shutdown, database malfunction, or a restartable error. Only one instance of a Messaging Gateway agent job runs at a given time.

If the agent job encounters an error, then the error is classified as either a restartable error or non-restartable error. A restartable error indicates a problem that might go away if the agent job were to be restarted. A non-restartable error indicates a problem that is likely to persist and be encountered again if the agent job restarts. ORA-01089 (immediate shutdown in progress) and ORA-28576 (lost RPC connection to external procedure) are examples of restartable errors. ORA-06520 (error loading external library) is an example of a non-restartable error.

Messaging Gateway uses a database shutdown trigger. If the Messaging Gateway agent is running on the instance being shut down, then the trigger notifies the agent of the shutdown, and upon receipt of the notification, the agent will terminate the current run. The job scheduler will automatically schedule the job to run again at a future time.

If a Messaging Gateway agent job instance ends because of a database malfunction or a restartable error detected by the agent job, then the job will not be removed and the job scheduler will automatically schedule the job to run again at a future time.

The MGW_GATEWAY view shows the agent status, the job identifier, and the database instance on which the Messaging Gateway agent is currently running.

19.2.4 Running the Oracle Messaging Gateway Agent on RAC

While the Messaging Gateway job startup and shutdown principles are the same for Real Application Clusters (RAC) and non-RAC environments, there are some things to keep in mind for a RAC environment.

Only one Messaging Gateway agent process can be running at a given time, even in a RAC environment. The job scheduler determines which database instance will run a job based on parameters specified when the job is created. The DBMS_MGWADM.STARTUP procedure has two optional parameters, instance and force, that can be used to set the instance affinity of the Messaging Gateway agent job.

When a database instance is shut down in a RAC environment, the Messaging Gateway shutdown trigger will notify the agent to shut down only if the Messaging Gateway agent is running on the instance being shut down. The job scheduler will automatically schedule the job to be run again at a future time, either on another instance, or if the job can only run on the instance being shut down, when that instance is restarted.

Oracle recommends that all database connections made by the Messaging Gateway agent be made to the instance on which the Messaging Gateway agent process is running. This ensures correct failover behavior in a RAC environment.

19.3 Configuring Messaging System Links

Running as a client of non-Oracle messaging systems, the Messaging Gateway agent communicates with non-Oracle messaging systems through messaging system links. A messaging system link is a set of connections between the Messaging Gateway agent and a non-Oracle messaging system.

To configure a messaging system link of a non-Oracle messaging system, users must provide information for the agent to make connections to the non-Oracle messaging system. Users can specify the maximum number of messaging connections.

When configuring a messaging system link for a non-Oracle messaging system that supports transactions and persistent messages, the native name of log queues for inbound and outbound propagation must be specified in order to guarantee exactly-once message delivery. The log queues should be used only by the Messaging Gateway agent. No other programs should enqueue or dequeue messages of the log queues. The inbound log queue and outbound log queue can refer to the same physical queue, but better performance can be achieved if they refer to different physical queues.

When configuring a messaging system link, users can also specify an options argument. An options argument is a set of {name, value} pairs of type SYS.MGW_PROPERTY.

This section contains these topics:

19.3.1 Creating a WebSphere MQ Base Java Link

A WebSphere MQ Base Java link is created by calling DBMS_MGWADM.CREATE_MSGSYSTEM_LINK with the following information provided:

  • Interface type: DBMS_MGWADM.MQSERIES_BASE_JAVA_INTERFACE

  • WebSphere MQ connection information:

    • Host name and port number of the WebSphere MQ server

    • Queue manager name

    • Channel name

    • User name and password

  • Maximum number of messaging connections allowed

  • Log queue names for inbound and outbound propagation

  • Optional information such as:

    • Send, receive, and security exits

    • Character sets

Example 19-6 configures a WebSphere MQ Base Java link mqlink. The link is configured to use the WebSphere MQ queue manager my.queue.manager on host myhost.mydomain and port 1414, using WebSphere MQ channel mychannel.

This example also sets the option to register a WebSphere MQ SendExit class. The class mySendExit must be in the CLASSPATH set in mgw.ora.

Example 19-6 Configuring a WebSphere MQ Base Java Link

DECLARE
  v_options sys.mgw_properties;
  v_prop sys.mgw_mqseries_properties;
BEGIN
  v_prop := sys.mgw_mqseries_properties.construct();
  
  v_prop.interface_type := dbms_mgwadm.MQSERIES_BASE_JAVA_INTERFACE;
  v_prop.max_connections := 1;
  v_prop.username := 'mqm';
  v_prop.password := 'mqm';
  v_prop.hostname := 'myhost.mydomain';
  v_prop.port     := 1414;
  v_prop.channel  := 'mychannel';
  v_prop.queue_manager := 'my.queue.manager';
  v_prop.outbound_log_queue := 'mylogq';
  
  -- Specify a WebSphere MQ send exit class 'mySendExit' to be associated with
  -- the queue. 
  -- Note that this is used as an example of how to use the options parameter, 
  -- but is not an option that is usually set.
  v_options := sys.mgw_properties(sys.mgw_property('MQ_SendExit',
                                                   'mySendExit'));
  dbms_mgwadm.create_msgsystem_link(
      linkname => 'mqlink', properties => v_prop, options => v_options );
END;

See Also:

19.3.2 Creating a WebSphere MQ JMS Link

A WebSphere MQ JMS link is created by calling DBMS_MGWADM.CREATE_MSGSYSTEM_LINK with the following information provided:

  • Interface type

    Java Message Service (JMS) distinguishes between queue and topic connections. The Sun Microsystem JMS 1.1 standard supports domain unification that allows both JMS queues and topics to be accessed by a single JMS connection:

    • A WebSphere MQ JMS link created with interface type DBMS_MGWADM.JMS_CONNECTION can be used to access both JMS queues and topics. This is the recommended interface for a WebSphere MQ JMS link.

    • A WebSphere MQ JMS link created with interface type DBMS_MGWADM.JMS_QUEUE_CONNECTION can be used to access only JMS queues.

    • A WebSphere MQ JMS link created with interface type DBMS_MGWADM.JMS_TOPIC_CONNECTION can be used to access only JMS topics.

  • WebSphere MQ connection information:

    • Host name and port number of the WebSphere MQ server

    • Queue manager name

    • Channel name

    • User name and password

  • Maximum number of messaging connections allowed

    A messaging connection is mapped to a JMS session.

  • Log destination (JMS queue or JMS topic) for inbound and outbound propagation

    The log destination type must be valid for the link type. JMS unified links and JMS queue links must use JMS queues for log destinations, and JMS topic links must use topics:

    • For a WebSphere MQ JMS unified or queue link, the log queue name must be the name of a physical WebSphere MQ JMS queue created using WebSphere MQ administration tools.

    • For a WebSphere MQ JMS topic link, the log topic name must be the name of a WebSphere MQ JMS topic. The physical WebSphere MQ queue used by that topic must be created using WebSphere MQ administration tools. By default, the physical queue used is SYSTEM.JMS.D.SUBSCRIBER.QUEUE. A link option can be used to specify a different physical queue.

  • Optional information such as:

    • Send, receive, and security exits

    • Character sets

    • WebSphere MQ publish/subscribe configuration used for JMS topics

Example 19-7 configures a Messaging Gateway link to a WebSphere MQ queue manager using a JMS topic interface. The link is named mqjmslink and is configured to use the WebSphere MQ queue manager my.queue.manager on host myhost.mydomain and port 1414, using WebSphere MQ channel mychannel.

This example also uses the options parameter to specify a nondefault durable subscriber queue to be used with the log topic.

Example 19-7 Configuring a WebSphere MQ JMS Link

DECLARE
  v_options sys.mgw_properties;
  v_prop sys.mgw_mqseries_properties;
BEGIN
  v_prop := sys.mgw_mqseries_properties.construct();
  v_prop.max_connections := 1;
  
  v_prop.interface_type := dbms_mgwadm.JMS_TOPIC_CONNECTION;
  v_prop.username := 'mqm';
  v_prop.password := 'mqm';
  v_prop.hostname := 'myhost.mydomain';
  v_prop.port     := 1414;
  v_prop.channel  := 'mychannel';
  v_prop.queue_manager := 'my.queue.manager'; 
  
  v_prop.outbound_log_queue := 'mylogtopic' 
  
  -- Specify a WebSphere MQ durable subscriber queue to be used with the
  -- log topic.
  v_options := sys.mgw_properties(
  sys.mgw_property('MQ_JMSDurSubQueue', 'myDSQueue'));
  
  dbms_mgwadm.create_msgsystem_link(
      linkname => 'mqjmslink', properties => v_prop, options => v_options );
END;

See Also:

19.3.3 Creating a TIB/Rendezvous Link

A TIB/Rendezvous link is created by calling DBMS_MGWADM.CREATE_MSGSYSTEM_LINK with three parameters (service, network and daemon) for the agent to create a corresponding transport of TibrvRvdTransport type.

A TIB/Rendezvous message system link does not need propagation log queues. Logging information is stored in memory. Therefore, Messaging Gateway can only guarantee at-most-once message delivery.

Example 19-8 configures a TIB/Rendezvous link named rvlink that connects to the rvd daemon on the local computer.

Example 19-8 Configuring a TIB/Rendezvous Link

DECLARE
  v_options sys.mgw_properties;
  v_prop     sys.mgw_tibrv_properties;
BEGIN
  v_prop := sys.mgw_tibrv_properties.construct();
  
  dbms_mgwadm.create_msgsystem_link(linkname => 'rvlink', properties => v_prop);
END;

19.3.4 Altering a Messaging System Link

Using DBMS_MGWADM.ALTER_MSGSYSTEM_LINK, you can alter some link information after the link is created. You can alter link information with the Messaging Gateway agent running or shut down. Example 19-9 alters the link mqlink to change the max_connections and password properties.

Example 19-9 Altering a WebSphere MQ Link

DECLARE
  v_options sys.mgw_properties;
  v_prop sys.mgw_mqseries_properties;
BEGIN
  -- use alter_construct() for initialization
  v_prop := sys.mgw_mqseries_properties.alter_construct();
  v_prop.max_connections := 2;
  v_prop.password := 'newpasswd';
  
  dbms_mgwadm.alter_msgsystem_link(
    linkname => 'mqlink', properties => v_prop);
END;

See Also:

"Configuration Properties" for restrictions on changes when the Messaging Gateway agent is running

19.3.5 Removing a Messaging System Link

You can remove a Messaging Gateway link to a non-Oracle messaging system with DBMS_MGWADM.REMOVE_MSGSYSTEM_LINK, but only if all registered queues associated with this link have already been unregistered. The link can be removed with the Messaging Gateway agent running or shut down. Example 19-10 removes the link mqlink.

Example 19-10 Removing a Messaging Gateway Link

BEGIN
  dbms_mgwadm.remove_msgsystem_link(linkname =>'mqlink');
END;

19.3.6 Views for Messaging System Links

You can use the MGW_LINKS view to check links that have been created. It lists the name and link type, as shown in Example 19-11.

Example 19-11 Listing All Messaging Gateway Links

SQL> select link_name, link_type from MGW_LINKS;
 
LINK_NAME     LINK_TYPE 
------------------------
MQLINK        MQSERIES
RVLINK        TIBRV

You can use the MGW_MQSERIES_LINK and MGW_TIBRV_LINKS views to check messaging system type-specific configuration information, as shown in Example 19-12.

Example 19-12 Checking Messaging System Link Configuration Information

SQL> select link_name, queue_manager, channel, hostname from mgw_mqseries_link;
 
LINK_NAME   QUEUE_MANAGER      CHANNEL     HOSTNAME
----------------------------------------------------------
MQLINK      my.queue.manager  mychannel  myhost.mydomain
 
SQL> select link_name, service, network, daemon from mgw_tibrv_links;
 
LINK_NAME   SERVICE      NETWORK     DAEMON
-----------------------------------------------------
RVLINK 

19.4 Configuring Non-Oracle Messaging System Queues

All non-Oracle messaging system queues involved in propagation as a source queue, destination queue, or exception queue must be registered through the Messaging Gateway administration interface. You do not need to register Oracle Streams AQ queues involved in propagation.

This section contains these topics:

19.4.1 Registering a Non-Oracle Queue

You can register a non-Oracle queue using DBMS_MGWADM.REGISTER_FOREIGN_QUEUE. Registering a non-Oracle queue provides information for the Messaging Gateway agent to access the queue. However, it does not create the physical queue in the non-Oracle messaging system. The physical queue must be created using the non-Oracle messaging system administration interfaces before the Messaging Gateway agent accesses the queue.

The following information is used to register a non-Oracle queue:

  • Name of the messaging system link used to access the queue

  • Native name of the queue (its name in the non-Oracle messaging system)

  • Domain of the queue

    • DBMS_MGWADM.DOMAIN_QUEUE for a point-to-point queue

    • DBMS_MGWADM.DOMAIN_TOPIC for a publish/subscribe queue

  • Options specific to the non-Oracle messaging system

    These options are a set of {name, value} pairs, both of which are strings.

Example 19-13 shows how to register the WebSphere MQ Base Java queue my_mq_queue as a Messaging Gateway queue destq.

Example 19-13 Registering a WebSphere MQ Base Java Queue

BEGIN
  dbms_mgwadm.register_foreign_queue(
    name => 'destq',
    linkname => 'mqlink',
    provider_queue => 'my_mq_queue',
    domain => dbms_mgwadm.DOMAIN_QUEUE);
END;

19.4.1.1 Registering a WebSphere MQ Base Java Queue

The domain must be DBMS_MGWADM.DOMAIN_QUEUE or NULL, because only point-to-point queues are supported for WebSphere MQ.

19.4.1.2 Registering a WebSphere MQ JMS Queue or Topic

When registering a WebSphere MQ JMS queue, the domain must be DBMS_MGWADM.DOMAIN_QUEUE, and the linkname parameter must refer to a WebSphere MQ JMS unified link or queue link.

When registering a WebSphere MQ JMS topic, the domain must be DBMS_MGWADM.DOMAIN_TOPIC, and the linkname parameter must refer to a WebSphere MQ JMS unified link or topic link. The provider_queue for a WebSphere MQ JMS topic used as a propagation source may include wildcards. See WebSphere MQ documentation for wildcard syntax.

19.4.1.3 Registering a TIB/Rendezvous Subject

When registering a TIB/Rendezvous subject with Messaging Gateway, the provider_queue parameter specifies a TIB/Rendezvous subject name. The domain of a registered TIB/Rendezvous queue must be DBMS_MGWADM.DOMAIN_TOPIC or NULL.

A registered TIB/Rendezvous queue with provider_queue set to a wildcard subject name can be used as a propagation source queue for inbound propagation. It is not recommended to use queues with wildcard subject names as propagation destination queues or exception queues. As documented in TIB/Rendezvous, sending messages to wildcard subjects can trigger unexpected behavior. However, neither Messaging Gateway nor TIB/Rendezvous prevents you from doing so.

19.4.2 Unregistering a Non-Oracle Queue

A non-Oracle queue can be unregistered with DBMS_MGWADM.UNREGISTER_FOREIGN_QUEUE, but only if there are no subscribers or schedules referencing it.

Example 19-14 unregisters the queue destq of the link mqlink.

Example 19-14 Unregistering a Non-Oracle Queue

BEGIN
  dbms_mwgadm.unregister_foreign_queue(name =>'destq', link_name=>'mqlink');
END;

19.4.3 View for Registered Non-Oracle Queues

You can use the MGW_FOREIGN_QUEUES view to check which non-Oracle queues are registered and what link each uses, as shown in Example 19-15.

Example 19-15 Checking Which Queues Are Registered

SQL> select name, link_name, provider_queue from MGW_FOREIGN_QUEUES;
 
NAME   LINK_NAME   PROVIDER_QUEUE
------------------------------------
DESTQ  MQLINK      my_mq_queue

19.5 Configuring Oracle Messaging Gateway Propagation Jobs

Propagating messages between an Oracle Streams AQ queue and a non-Oracle messaging system queue requires a propagation job. A propagation job consists of a propagation subscriber and a propagation schedule. The propagation subscriber specifies the source and destination queues, while the propagation schedule specifies when the propagation job is processed. A propagation schedule is associated with a propagation subscriber that has the same propagation source, destination, and type.

You can create a propagation job to propagate messages between JMS destinations. You can also create a propagation job to propagate messages between non-JMS queues. Messaging Gateway does not support message propagation between a JMS destination and a non-JMS queue.

This section contains these topics:

19.5.1 Propagation Subscriber Overview

A propagation subscriber specifies what messages are propagated and how the messages are propagated.

Messaging Gateway allows bidirectional message propagation. An outbound propagation moves messages from Oracle Streams AQ to non-Oracle messaging systems. An inbound propagation moves messages from non-Oracle messaging systems to Oracle Streams AQ.

If the propagation source is a queue (point-to-point), then the Messaging Gateway agent moves all messages from the source queue to the destination queue. If the propagation source is a topic (publish/subscribe), then the Messaging Gateway agent creates a subscriber of the propagation source queue in the messaging system. The agent only moves messages that are published to the source queue after the subscriber is created.

When propagating a message, the Messaging Gateway agent converts the message from the format in the source messaging system to the format in the destination messaging system. Users can customize the message conversion by providing a message transformation. If message conversion fails, then the message will be moved to an exception queue, if one has been provided, so that the agent can continue to propagate messages for the subscriber.

A Messaging Gateway exception queue is different from an Oracle Streams AQ exception queue. Messaging Gateway moves a message to a Messaging Gateway exception queue when message conversion fails. Oracle Streams AQ moves a message to an Oracle Streams AQ exception queue after MAX_RETRIES dequeue attempts on the message.

Messages moved to an Oracle Streams AQ exception queue may result in unrecoverable failures on the associated Messaging Gateway subscriber. To avoid the problem, the MAX_RETRIES parameter of any Oracle Streams AQ queue that is used as the propagation source of a Messaging Gateway propagation job should be set to a value much larger than 16.

If the messaging system of the propagation source queue supports message selection, then a message selection rule can be specified for a propagation subscriber. Only messages that satisfy the message selector will be propagated.

Users can also specify subscriber options for certain types of propagation subscribers to control how messages are propagated, such as options for JMS message delivery mode and TIB/Rendezvous queue policies.

Messaging Gateway provides MGW_SUBSCRIBERS and MGW_SCHEDULES views for users to check configuration and status of Messaging Gateway subscribers and schedules.

19.5.2 Creating an Oracle Messaging Gateway Propagation Subscriber

Messaging Gateway subscribers are created by DBMS_MGWADM.ADD_SUBSCRIBER.

If the propagation source for non-JMS propagation is an Oracle Streams AQ queue, then the queue must be a multiconsumer queue. Messaging Gateway creates a corresponding Oracle Streams AQ subscriber MGW_subscriber_id for the messaging system subscriber subscriber_id when DBMS_MGWADM.ADD_SUBSCRIBER is called.

If the propagation source is a JMS topic, such as an Oracle Java Message Service (OJMS) topic or a WebSphere MQ JMS topic, then a JMS subscriber MGW_subscriber_id is created on the topic in the source messaging system by the Messaging Gateway agent. If the agent is not running, then the subscriber will not be created until the agent is restarted.

If the propagation source is a queue, then only one propagation job can be created using that queue as the propagation source. If the propagation source is a topic, then multiple propagation jobs can be set up using that topic as the propagation source with each propagation job having its own corresponding subscriber on the topic in the messaging system.

Example 19-16 creates Messaging Gateway propagation subscriber sub_aq2mq.

Example 19-16 Creating a Propagation Subscriber

BEGIN
  dbms_mgwadm.add_subscriber(
    subscriber_id => 'sub_aq2mq',
    propagation_type => dbms_mgwadm.outbound_propagation,
    queue_name => 'mgwuser.srcq', 
    destination => 'destq@mqlink');
END;

Note:

If a WebSphere MQ JMS topic is involved in a propagation job and the interface type of the link is DBMS_MGWADM.JMS_TOPIC_CONNECTION, then a durable subscriber MGL_subscriber_id is created on the log topic. The durable subscriber is removed when the Messaging Gateway subscriber is successfully removed.

19.5.3 Creating an Oracle Messaging Gateway Propagation Schedule

You can create a propagation schedule using DBMS_MGWADM.SCHEDULE_PROPAGATION. A propagation subscriber is not processed until an associated propagation schedule is created and enabled. A propagation schedule is associated with a propagation subscriber when the propagation type, source and destination match.

The latency parameter in a propagation schedule controls the polling interval of a propagation job. The polling interval determines how soon the agent can discover the available messages to propagate in the propagation source queue. The default polling interval is 5 seconds or the value set for oracle.mgw.polling_interval in Messaging Gateway initialization file mgw.ora.

Example 19-17 creates Messaging Gateway propagation schedule sch_aq2mq.

Example 19-17 Creating a Propagation Schedule

BEGIN
  dbms_mgwadm.schedule_propagation(
    schedule_id => 'sch_aq2mq',
    propagation_type => dbms_mgwadm.outbound_propagation,
    source => 'mgwuser.srcq',
    destination => 'destq@mqlink',
    latency => 2);
END;

19.5.4 Enabling and Disabling a Propagation Job

A propagation job is enabled if its propagation schedule is created and enabled. A propagation job is disabled if its propagation schedule is disabled or removed. Users can call DBMS_MGWADM.ENABLE_PROPAGATION_SCHEDULE to enable a propagation schedule and DBMS_MGWADM.DISABLE_PROPAGATION_SCHEDULE to disable a propagation schedule.

Example 19-18 enables the propagation schedule for propagation subscriber sub_aq2mq.

Example 19-18 Enabling a Messaging Gateway Propagation Schedule

BEGIN
  dbms_mgwadm.enable_propagation_schedule('sch_aq2mq');
END;

Example 19-19 disables the propagation schedule for propagation subscriber sub_aq2mq.

Example 19-19 Disabling a Messaging Gateway Propagation Schedule

BEGIN
  dbms_mgwadm.disable_propagation_schedule('sch_aq2mq');
END;

By default, the propagation schedule is enabled when it is first created.

To create a propagation job that is initially disabled, call the following APIs in the indicated order:

  1. DBMS_MGWADM.SCHEDULE_PROPAGATION

  2. DBMS_MGWADM.DISABLE_PROPAGATION_SCHEDULE

  3. DBMS_MGWADM.ADD_SUBSCRIBER

19.5.5 Resetting a Propagation Job

When a problem occurs with a propagation job, the Messaging Gateway agent retries the failed operation up to 16 times in an exponential backoff scheme before the propagation job stops. You can use DBMS_MGWADM.RESET_SUBSCRIBER to reset the failure count to zero to allow the agent to retry the failed operation immediately.

Example 19-20 resets the failure count for propagation subscriber sub_aq2mq.

Example 19-20 Resetting a Propagation Job

BEGIN
  dbms_mgwadm.reset_subscriber('sub_aq2mq');
END;

19.5.6 Altering a Propagation Subscriber and Schedule

After the propagation subscriber and schedule of a propagation job are created, you can alter the selection rule, transformation, exception queue, subscriber options, and latency of the propagation job using DBMS_MGWADM.ALTER_SUBSCRIBER and DBMS_MGWADM.ALTER_PROPAGATION_SCHEDULE. Subscribers and schedules can be altered with the Messaging Gateway agent running or shut down.

Example 19-21 adds an exception queue for subscriber sub_aq2mq.

Example 19-21 Altering Propagation Subscriber by Adding an Exception Queue

BEGIN
  dbms_mgwadm.alter_subscriber(
    subscriber_id => 'sub_aq2mq',
    exception_queue => 'mgwuser.my_ex_queue');
END;

Example 19-22 changes the polling interval for schedule sch_aq2mq.

Example 19-22 Altering Propagation Subscriber by Changing the Polling Interval

BEGIN
  dbms_mgwadm.alter_propagation_schedule(
    subscriber_id => 'sch_aq2mq',
    latency => 1);
END;

19.5.7 Removing a Propagation Subscriber and Schedule

You can remove a Messaging Gateway propagation subscriber with DBMS_MGWADM.REMOVE_SUBSCRIBER.

Before removing the Messaging Gateway subscriber from the Messaging Gateway configuration, Messaging Gateway does the following cleanup:

  • Removes from the messaging system the associated subscriber that may have been created by Messaging Gateway

  • Removes propagation log records from log queues for the subscriber being removed

Messaging Gateway may fail to do the cleanup because:

  • The Messaging Gateway agent is not running

  • Non-Oracle messaging system is not running

  • The Messaging Gateway agent is unable to interact with the source or destination messaging system

If Messaging Gateway cleanup fails for any reason, then the Messaging Gateway subscriber being removed is placed in the DELETE_PENDING state. The Messaging Gateway agent tries to clean up subscribers in DELETE_PENDING state when:

  • DBMS_MGWADM.REMOVE_SUBSCRIBER is called and the Messaging Gateway agent is running

  • The Messaging Gateway agent is starting and finds a subscriber in DELETE_PENDING state

You can specify DBMS_MGWADM.FORCE when calling DBMS_MGWADM.REMOVE_SUBSCRIBER to force Messaging Gateway to remove the Messaging Gateway subscriber from the Messaging Gateway configuration without placing it in the DELETE_PENDING mode in case of cleanup failures.

Calling DBMS_MGWADM.REMOVE_SUBSCRIBER with DBMS_MGWADM.FORCE may result in obsolete log records in the log queues and subscriptions in messaging systems, which may cause unnecessary message accumulation. Oracle recommends not using DBMS_MGWADM.FORCE when calling DBMS_MGWADM.REMOVE_SUBSCRIBER, if possible.

Example 19-23 removes propagation subscriber sub_aq2mq.

Example 19-23 Removing a Propagation Subscriber

BEGIN
  dbms_mgwadm.remove_subscriber(subscriber_id =>'sub_aq2mq');
END;

You can remove propagation schedules with DBMS_MGWADM.UNSCHEDULE_PROPAGATION. Removing a propagation schedule results in disabling the associated propagation job. It does not remove any subscriptions in messaging systems.

Example 19-24 removes propagation schedule sch_aq2mq.

Example 19-24 Removing a Propagation Schedule

BEGIN
  dbms_mgwadm.unschedule_propagation(schedule_id => 'sch_aq2mq');
END;

19.6 Configuration Properties

This section summarizes basic and optional properties related to Messaging Gateway links, foreign queues, and subscribers.

This section contains these topics:

19.6.1 WebSphere MQ System Properties

Table 19-1 summarizes the basic configuration properties for a WebSphere MQ messaging link. The table indicates which properties of SYS.MGW_MQSERIES_PROPERTIES are optional (NULL allowed), which can be altered, and if alterable, which values can be dynamically changed.

See Also:

"SYS.MGW_MQSERIES_PROPERTIES Type" in PL/SQL Packages and Types Reference

Table 19-1 WebSphere MQ Link Properties

Attribute NULL Allowed? Alter Value? Dynamic?
queue_manager no no no
hostname yes (1) no no
port yes (1) no no
channel yes (1) no no
interface_type yes (2) no no
max_connections yes (3) yes yes
username yes yes yes
password yes yes yes
inbound_log_queue yes (4) yes(4) yes
outbound_log_queue yes (5) yes(5) yes

Notes on Table 19-1

  1. If hostname is NULL, then the port and channel must be NULL. If the hostname is not NULL, then the port and channel must be not NULL. If the hostname is NULL, then a WebSphere MQ bindings connection is used; otherwise a client connection is used.

  2. If interface_type is NULL, then a default value of DBMS_MGWADM.MQSERIES_BASE_JAVA_INTERFACE is used.

  3. If max_connections is NULL, then a default value of 1 is used.

  4. Attribute inbound_log_queue can be NULL if the link is not used for inbound propagation. The log queue can be altered only when no inbound propagation subscriber references the link.

  5. Attribute outbound_log_queue can be NULL if the link is not used for outbound propagation. The log queue can be altered only when no outbound propagation subscriber references the link.

Table 19-2 summarizes the optional configuration properties supported when a WebSphere MQ Base Java interface is used to access the WebSphere MQ messaging system. Table 19-3 summarizes the optional configuration properties supported when a WebSphere MQ JMS interface is used. Each table lists the property name, where that property applies, whether the property can be altered, and if alterable, whether the value can be dynamically changed. Only the properties listed in the tables are supported, and any extra properties are ignored.

Table 19-2 Optional Configuration Properties for WebSphere MQ Base Java

Property Name Used For Alter Value? Dynamic?
MQ_ccsid
link yes no
MQ_ReceiveExit
link yes no
MQ_SendExit
link yes no
MQ_SecurityExit
link yes no
MQ_openOptions
foreign queue no no
MsgBatchSize
subscriber yes yes
PreserveMessageID
subscriber yes yes

Table 19-3 Optional Configuration Properties for WebSphere MQ JMS

Property Name Used For Alter Value? Dynamic?
MQ_ccsid
link yes no
MQ_ReceiveExit
link yes no
MQ_SendExit
link yes no
MQ_SecurityExit
link yes no
MQ_ReceiveExitInit
link yes no
MQ_SendExitInit
link yes no
MQ_SecurityExitInit
link yes no
MQ_BrokerControlQueue
link yes no
MQ_BrokerPubQueue
link yes no
MQ_BrokerQueueManager
link yes no
MQ_BrokerVersion
link yes no
MQ_PubAckInterval
link yes no
MQ_JmsDurSubQueue
link no no
MQ_JmsTargetClient
foreign queue no no
MQ_JmsDurSubQueue
foreign queue no no
MQ_CharacterSet
foreign queue no no
MsgBatchSize
subscriber yes yes
JMS_NoLocal
subscriber no no
JMS_DeliveryMode
subscriber yes yes
PreserveMessageID
subscriber yes yes

19.6.2 TIB/Rendezvous System Properties

Table 19-4 summarizes the basic configuration properties for a TIB/Rendezvous messaging link. It indicates which properties of SYS.MGW_TIBRV_PROPERTIES are optional (NULL allowed), which can be altered, and if alterable, which values can be dynamically changed.

See Also:

"SYS.MGW_TIBRV_PROPERTIES Type" in PL/SQL Packages and Types Reference

Table 19-4 TIB/Rendezvous Link Properties

Attribute NULL allowed? Alter value? Dynamic?
service yes(1) no no
daemon yes(1) no no
network yes(1) no no
cm_name yes(2) no no
cm_ledger yes(2) no no

Notes on Table 19-4:

  1. System default values will be used if service, daemon, or network are NULL.

  2. The cm_name and cm_ledger attributes are reserved for future use when TIB/Rendezvous certified messages are supported. At present, a NULL must be specified for these parameters when a TIB/Rendezvous link is configured.

Table 19-5 summarizes the optional configuration properties supported when a TIB/Rendezvous messaging system is used. The table lists the property name, where that property applies, whether the property can be altered, and if alterable, whether the value can be dynamically changed. Only the properties listed in the table are supported, and any extra properties will be ignored.

Table 19-5 Optional Properties for TIB/Rendezvous

Property Name Used For Alter Value? Dynamic?
RV_discardAmount subscriber yes no
RV_limitPolicy
subscriber yes no
RV_maxEvents
subscriber yes no
AQ_MsgProperties
subscriber yes yes
MsgBatchSize
subscriber yes yes
PreserveMessageID
subscriber yes yes

19.6.3 Optional Link Configuration Properties

This section describes optional link properties you can specify using the options parameter of DBMS_MGWADM.CREATE_MSGSYSTEM_LINK and DBMS_MGWADM.ALTER_MSGSYSTEM_LINK. Each listing also indicates which messaging system might use that property.

MQ_BrokerControlQueue

This property is used by WebSphere MQ JMS. It specifies the name of the broker control queue and corresponds to WebSphere MQ JMS administration tool property BROKERCONQ. The WebSphere MQ default is SYSTEM.BROKER.CONTROL.QUEUE.

MQ_BrokerPubQueue

This property is used by WebSphere MQ JMS. It specifies the name of the broker publish queue and corresponds to WebSphere MQ JMS administration tool property BROKERPUBQ. The WebSphere MQ default is SYSTEM.BROKER.DEFAULT.STREAM.

MQ_BrokerQueueManager

This property is used by WebSphere MQ JMS. It specifies the name of the broker queue manager and corresponds to WebSphere MQ administration tool property BROKERQMGR. If it is not set, then no default is used.

MQ_BrokerVersion

This property is used by WebSphere MQ JMS. It specifies the broker version number and corresponds to WebSphere MQ JMS administration tool property BROKERVER. The WebSphere MQ default is 0.

MQ_ccsid

This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It specifies the character set identifier to be used to translate information in the WebSphere MQ message header. This should be the integer value of the character set (for example, 819) rather than a descriptive string. If it is not set, then the WebSphere MQ default character set 819 is used.

MQ_JmsDurSubQueue

This property is used by WebSphere MQ JMS. It applies to WebSphere MQ JMS topic links only. The SYS.MGW_MQSERIES_PROPERITES attributes, inbound_log_queue and outbound_log_queue, specify the names of WebSphere MQ JMS topics used for propagation logging. This property specifies the name of the WebSphere MQ queue from which durable subscription messages are retrieved by the log topic subscribers. The WebSphere MQ default queue is SYSTEM.JMS.D.SUBSCRIBER.QUEUE.

MQ_PubAckInterval

This property is used by WebSphere MQ JMS. It specifies the interval, in number of messages, between publish requests that require acknowledgment from the broker and corresponds to WebSphere MQ JMS administration tool property PUBACKINT. The WebSphere MQ default is 25.

MQ_ReceiveExit

This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It specifies the fully qualified Java classname of a class implementing the MQReceiveExit interface. This class must be in the CLASSPATH of the Messaging Gateway agent. There is no default.

MQ_ReceiveExitInit

This initialization string is used by WebSphere MQ JMS. It is passed by WebSphere MQ JMS to the constructor of the class specified by MQ_ReceiveExit and corresponds to WebSphere MQ JMS administration tool property RECEXITINIT. There is no default.

MQ_SecurityExit

This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It specifies the fully qualified Java classname of a class implementing the MQSecurityExit interface. This class must be in the CLASSPATH of the Messaging Gateway agent. There is no default.

MQ_SecurityExitInit

This initialization string is used by WebSphere MQ JMS. It is passed by WebSphere MQ JMS to the constructor of the class specified by MQ_SecurityExit and corresponds to WebSphere MQ JMS administration tool property SECEXITINIT. There is no default.

MQ_SendExit

This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It specifies the fully qualified Java classname of a class implementing the MQSendExit interface. This class must be in the CLASSPATH of the Messaging Gateway agent. There is no default.

MQ_SendExitInit

This initialization string is used by WebSphere MQ JMS. It is passed by WebSphere MQ JMS to the constructor of the class specified by MQ_SendExit. It corresponds to WebSphere MQ JMS administration tool property SENDEXITINIT. There is no default.

19.6.4 Optional Foreign Queue Configuration Properties

This section describes optional foreign queue properties that you can specify using the options parameter of DBMS_MGWADM.REGISTER_FOREIGN_QUEUE. Each listing also indicates which messaging system might use that property.

MQ_CharacterSet

This property is used by WebSphere MQ JMS. It is used only for outbound propagation to a JMS queue or topic. It specifies the character set to be used to encode text strings sent to the destination. It should be the integer value of the character set (for example, 1208) rather than a descriptive string. The default value used by Messaging Gateway is 1208 (UTF8).

MQ_JmsDurSubQueue

This property is used by WebSphere MQ JMS. It is a string representing the name of the WebSphere MQ queue from which durable subscription messages are retrieved by subscribers on this topic. It applies only to WebSphere MQ JMS topics. The WebSphere MQ default queue is SYSTEM.JMS.D.SUBSCRIBER.QUEUE.

MQ_JmsTargetClient

This property is used by WebSphere MQ JMS. It is used only for outbound propagation to a JMS queue or topic. Supported values are TRUE and FALSE. TRUE indicates that WebSphere MQ should store the message as a JMS message. FALSE indicates that WebSphere MQ should store the message in non-JMS format so that non-JMS applications can access it. Default is TRUE.

MQ_openOptions

This property is used by WebSphere MQ Base Java. It specifies the value used for the openOptions argument of the WebSphere MQ Base Java MQQueueManager.accessQueue method. No value is required. But if one is given, then the Messaging Gateway agent adds MQOO_OUTPUT to the specified value for an enqueue (put) operation. MQOO_INPUT_SHARED is added for a dequeue (get) operation. The default is MQOO_OUTPUT for an enqueue/put operation; MQOO_INPUT_SHARED for a dequeue/get operation.

19.6.5 Optional Subscriber Configuration Properties

This section describes optional subscriber properties that you can specify using the options parameter of DBMS_MGWADM.ADD_SUBSCRIBER and DBMS_MGWADM.ALTER_SUBSCRIBER. Each listing also indicates which messaging system might use that property.

AQ_MsgProperties

This property is used by TIB/Rendezvous. It specifies how Oracle Streams AQ message properties will be used during message propagation. Supported values are TRUE and FALSE. The default value is FALSE.

For an outbound propagation subscriber, if the value is TRUE (case insensitive), then the Messaging Gateway agent will add a field for most Oracle Streams AQ message properties to the message propagated to the TIB/Rendezvous subject.

For an inbound propagation subscriber, if the value is TRUE (case insensitive), then the Messaging Gateway agent will search the source message for a field with a reserved name, and if it exists, use its value to set the corresponding Oracle Streams AQ message property. A default value will be used if the field does not exist or does not have an expected datatype.

JMS_DeliveryMode

This property is used by WebSphere MQ JMS and Oracle JMS. You can use this property when the propagation destination is a JMS messaging system. It sets the delivery mode of messages enqueued to the propagation destination queue by a JMS MessageProducer. The default is PRESERVE_MSG. Supported values and their associated delivery modes are:

  • PERSISTENT (DeliveryMode.PERSISTENT)

  • NON_PERSISTENT (DeliveryMode.NON_PERSISTENT)

  • PRESERVE_MSG (delivery mode of the source JMS message is used)

JMS_NoLocal

This property is used by WebSphere MQ JMS and Oracle JMS. You can use it when the propagation source is a JMS messaging system. It sets the noLocal parameter of a JMS TopicSubscriber. TRUE indicates that messages that have been published to this topic through the same Messaging Gateway link will not be propagated. The default value FALSE indicates that such messages will be propagated from the topic.

MsgBatchSize

This property can be used by any supported messaging system. It specifies the maximum number of messages, if available, to be propagated in one transaction. The default is 30.

PreserveMessageID

This property is used by WebSphere MQ Base Java, WebSphere MQ JMS, TIB/Rendezvous, and Oracle JMS. It specifies whether Messaging Gateway should preserve the original message identifier when the message is propagated to the destination messaging system. The exact details depend on the capabilities of the messaging systems involved. Supported values are TRUE and FALSE. The default value is FALSE.

RV_discardAmount

This property is used by TIB/Rendezvous. It specifies the discard amount of a queue. It is meaningful only for an inbound propagation subscriber. The default is 0.

RV_limitPolicy

This property is used by TIB/Rendezvous. It specifies the limit policy for resolving overflow of a queue limit. It is meaningful only for an inbound propagation subscriber. The default is DISCARD_NONE. Supported values and their associated limit policies are: DISCARD_NONE, DISCARD_FIRST, DISCARD_LAST and DISCARD_NEW.

  • DISCARD_NONE (TibrvQueue.DISCARD_NONE)

  • DISCARD_FIRST (TibrvQueue.DISCARD_FIRST)

  • DISCARD_LAST (TibrvQueue.DISCARD_LAST)

  • DISCARD_NEW (TibrvQueue.DISCARD_NEW)

RV_maxEvents

This property is used by TIB/Rendezvous. It specifies the maximum event limit of a queue. It is meaningful only for an inbound propagation subscriber. The default is 0.