19 Working with Oracle Messaging Gateway

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.

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.

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.

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

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.

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.

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.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.

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;

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.

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;

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.

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.

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;

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.

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.

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.

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.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.

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

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.

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.

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

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.

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

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.

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.

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

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

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.