Oracle® Streams Advanced Queuing User's Guide and Reference 10g Release 2 (10.2) Part Number B14257-01 |
|
|
View PDF |
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:
See Also:
"DBMS_MGWADM" and "DBMS_MGWMSG" in PL/SQL Packages and Types ReferenceMessages 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:
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
.
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.
This section contains these topics:
After the Messaging Gateway agent is configured, you can start the agent with DBMS_MGWADM.STARTUP
, as shown in Example 19-4.
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".
You can use DBMS_MGWADM.SHUTDOWN
to shut down the Messaging Gateway agent, as shown in Example 19-5.
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".
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.
See Also:
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.
See Also:
"DBMS_MGWADM" and "DBMS_JOB" in PL/SQL Packages and Types Reference
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:
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:
"Understanding the mgw.ora Initialization File" for information on setting the CLASSPATH of the Messaging Gateway agent
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:
"Registering a WebSphere MQ JMS Queue or Topic" for more information on JMS queues and topics
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;
See Also:
"TIB/Rendezvous System Properties"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 runningYou 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
.
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
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:
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;
The domain must be DBMS_MGWADM.DOMAIN_QUEUE
or NULL, because only point-to-point queues are supported for WebSphere MQ.
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.
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.
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
.
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.
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:
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.
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 isDBMS_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.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
.
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:
DBMS_MGWADM.SCHEDULE_PROPAGATION
DBMS_MGWADM.DISABLE_PROPAGATION_SCHEDULE
DBMS_MGWADM.ADD_SUBSCRIBER
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
.
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
.
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
.
This section summarizes basic and optional properties related to Messaging Gateway links, foreign queues, and subscribers.
This section contains these topics:
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 ReferenceTable 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
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.
If interface_type
is NULL
, then a default value of DBMS_MGWADM.MQSERIES_BASE_JAVA_INTERFACE
is used.
If max_connections
is NULL
, then a default value of 1
is used.
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.
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 |
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 ReferenceTable 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:
System default values will be used if service
, daemon
, or network
are NULL
.
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 |
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.
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
.
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
.
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.
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
.
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.
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
.
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
.
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.
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.
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.
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.
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.
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.
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.
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).
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
.
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
.
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.
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.
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.
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)
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.
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.
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
.
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.
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
)
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.