PL/SQL Packages and Types Reference 10g Release 1 (10.1) Part Number B10802-01 |
|
|
View PDF |
DBMS_MGWADM
defines the Messaging Gateway administrative interface. The package and object types are owned by SYS
.
Note: You must run the |
See Also:
Oracle Streams Advanced Queuing User's Guide and Reference contains information on loading database objects and using |
This chapter contains the following topics:
Name | Type | Description |
---|---|---|
|
|
Represents a normal, nonforced action |
|
|
Represents a forced action |
Name | Type | Description |
---|---|---|
|
|
Represents the normal shutdown mode |
|
|
Represents the immediate shutdown mode |
Name | Type | Description |
---|---|---|
|
|
Represents the Base Java interface for the WebSphere MQ messaging system |
This type specifies a named property. SYS.MGW_PROPERTY
is used to specify optional properties for messaging links, foreign queues, and subscribers.
TYPE SYS.MGW_PROPERTY IS OBJECT( name VARCHAR2(100), value VARCHAR2(1000), -- Methods STATIC FUNCTION CONSTRUCT RETURN SYS.MGW_PROPERTY, STATIC FUNCTION CONSTRUCT( p_name IN VARCHAR2, p_value IN VARCHAR2) RETURN SYS.MGW_PROPERTY );
Attribute | Description |
---|---|
|
Property name |
|
Property value |
This method constructs a new MGW_PROPERTY
instance. All attributes are assigned a value of NULL.
STATIC FUNCTION CONSTRUCT RETURN SYS.MGW_PROPERTY;
This method constructs a new MGW_PROPERTY
instance initialized using the given parameters.
STATIC FUNCTION CONSTRUCT( p_name IN VARCHAR2, p_value IN VARCHAR2) RETURN SYS.MGW_PROPERTY;
Parameter | Description |
---|---|
|
Property name |
|
Property value |
This type specifies an array of properties.
TYPE SYS.MGW_PROPERTIES AS VARRAY (100) OF SYS.MGW_PROPERTY;
Unless noted otherwise, Messaging Gateway uses named properties as follows:
MGWPROP$_
prefix are reserved. They are used for special purposes and are invalid when used as a normal property name.The alter list is processed in order, from the first element to the last element. Thus the order in which the elements appear in the alter list is meaningful, especially when the alter list is used to remove properties from an existing list.
The property name and value are used to determine how that element affects the original list. The following rules apply:
MGW_PROPERTY.NAME = property_name MGW_PROPERTY.VALUE = property_value
If a property of the given name already exists, then the current value is replaced with the new value; otherwise the new property is added to the end of the list.
MGW_PROPERTY.NAME = 'MGWPROP$_REMOVE' MGW_PROPERTY.VALUE = name_of_property_to_remove
No action is taken if the property name does not exist in the original list.
MGW_PROPERTY.NAME = 'MGWPROP$_REMOVE_ALL' MGW_PROPERTY.VALUE = not used
The DBMS_MGWADM
package defines constants to represent the reserved property names. See "WebSphere MQ System Properties" for more information.
This type specifies basic properties for a WebSphere MQ messaging system link.
TYPE SYS.MGW_MQSERIES_PROPERTIES IS OBJECT ( queue_manager VARCHAR2(64), hostname VARCHAR2(64), port INTEGER, channel VARCHAR2(64), interface_type INTEGER, max_connections INTEGER, username VARCHAR2(64), password VARCHAR2(64), inbound_log_queue VARCHAR2(64), outbound_log_queue VARCHAR2(64), -- Methods STATIC FUNCTION construct RETURN SYS.MGW_MQSERIES_PROPERTIES, STATIC FUNCTION alter_construct RETURN SYS.MGW_MQSERIES_PROPERTIES );
This method constructs a new SYS.MGW_MQSERIES_PROPERTIES
instance. All attributes are assigned a value of NULL.
STATIC FUNCTION CONSTRUCT RETURN SYS.MGW_MQSERIES_PROPERTIES;
This method constructs a new SYS.MGW_MQSERIES_PROPERTIES
instance for altering the properties of an existing messaging link. All attributes having a VARCHAR2
data type are assigned a value of DBMS_MGWADM.NO_CHANGE.
Attributes of other data types are assigned a value of NULL.
STATIC FUNCTION ALTER_CONSTRUCT RETURN SYS.MGW_MQSERIES_PROPERTIES;
A type that specifies basic properties for a TIB/Rendezvous messaging system link. The Messaging Gateway agent creates a TIB/Rendezvous transport of type TibrvRvdTransport
for each Messaging Gateway link.
TYPE SYS.MGW_TIBRV_PROPERTIES IS OBJECT( service VARCHAR2(128), daemon VARCHAR2(128), network VARCHAR2(256), cm_name VARCHAR2(256), cm_ledger VARCHAR2(256), -- Methods STATIC FUNCTION construct RETURN SYS.MGW_TIBRV_PROPERTIES, STATIC FUNCTION alter_construct RETURN SYS.MGW_TIBRV_PROPERTIES );
Constructs a new SYS.MGW_TIBRV_PROPERTIES
instance. All attributes will be assigned a value of NULL
.
STATIC FUNCTION construct RETURN SYS.MGW_TIBRV_PROPERTIES;
Constructs a new SYS.MGW_TIBRV_PROPERTIES
instance. This function is useful for altering the properties of an existing messaging link. All attributes having a VARCHAR2
data type will be assigned a value of DBMS_MGWADM.NO_CHANGE
. Attributes of other data types will be assigned a value of NULL
.
STATIC FUNCTION alter_construct RETURN SYS.MGW_TIBRV_PROPERTIES;
This section summarizes basic and optional properties of WebSphere MQ related to Messaging Gateway links, foreign queues, and subscribers.
Table 51-14 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.
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.interface_type
is NULL
, then a default value of DBMS_MGWADM.MQSERIES_BASE_JAVA_INTERFACE
is used.max_connections
is NULL
, then a default value of 1
is used.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.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 51-15 summarizes the optional configuration properties supported when a WebSphere MQ Base Java interface is used to access the WebSphere MQ messaging system. Table 51-16 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 will be ignored.
Property Name | Used For | Alter Value? | Dynamic? |
---|---|---|---|
link |
yes |
no | |
link |
yes |
no | |
link |
yes |
no | |
link |
yes |
no | |
foreign queue |
no |
no | |
subscriber |
yes |
yes |
This section summarizes basic and optional configuration properties of TIB/Rendezvous related to Messaging Gateway links, foreign queues and subscribers.
Table 51-17 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.
Attribute | NULL allowed? | Alter value? | Dynamic? |
---|---|---|---|
|
yes(1) |
no |
no |
|
yes(1) |
no |
no |
|
yes(1) |
no |
no |
|
yes(2) |
no |
no |
|
yes(2) |
no |
no |
service
, daemon
, or network
are NULL
.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 51-18 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.
Property Name | Used For | Alter Value? | Dynamic? |
---|---|---|---|
subscriber |
yes |
no | |
subscriber |
yes |
no | |
subscriber |
yes |
no | |
subscriber |
yes |
yes | |
subscriber |
yes |
yes |
DBMS_MGWADM.register_foreign_queue
procedure is used to register a TIB/Rendezvous subject with the Messaging Gateway. The provider_queue
parameter specifies a TIB/Rendezvous subject name. Wildcards are allowed in the subject name.
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.
Used by: WebSphere MQ JMS.
This property specifies the name of the broker control queue. It corresponds to WebSphere MQ JMS administration tool property BROKERCONQ
. The default used by WebSphere MQ is SYSTEM.BROKER.CONTROL.QUEUE
.
Used by: WebSphere MQ JMS
This property specifies the name of the broker publish queue. It corresponds to WebSphere MQ JMS administration tool property BROKERPUBQ
. The default used by WebSphere MQ is SYSTEM.BROKER.DEFAULT.STREAM
.
Used by: WebSphere MQ JMS
This property specifies the name of the broker queue manager. It corresponds to WebSphere MQ administration tool property BROKERQMGR
. If not set, then no default will be used.
Used by: WebSphere MQ JMS
This property specifies the broker version number. It corresponds to WebSphere MQ JMS administration tool property BROKERVER
. The default used by WebSphere MQ is 0
.
Used by: WebSphere MQ Base Java and WebSphere MQ JMS
This property specifies the character set identifier to be used. 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.
Used by: WebSphere MQ JMS
This property 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 default queue used by WebSphere MQ is SYSTEM.JMS.D.SUBSCRIBER.QUEUE
.
Used by: WebSphere MQ JMS
This property specifies the interval, in number of messages, between publish requests that require acknowledgment from the broker. It corresponds to WebSphere MQ JMS administration tool property PUBACKINT
. The default used by WebSphere MQ is 25
.
Used by: WebSphere MQ Base Java and WebSphere MQ JMS
This property 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.
Used by: WebSphere MQ JMS
Initialization string that is passed by WebSphere MQ JMS to the constructor of the class specified by MQ_ReceiveExit
. Corresponds to WebSphere MQ JMS administration tool property RECEXITINIT
. There is no default.
Used by: WebSphere MQ Base Java and WebSphere MQ JMS
This property 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.
Used by: WebSphere MQ JMS
Initialization string that is passed by WebSphere MQ JMS to the constructor of the class specified by MQ_SecurityExit
. It corresponds to WebSphere MQ JMS administration tool property SECEXITINIT
. There is no default.
Used by: WebSphere MQ Base Java and WebSphere MQ JMS
This property 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.
Used by: WebSphere MQ JMS
Initialization string that 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.
Used by: WebSphere MQ JMS
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 default queue used by WebSphere MQ is SYSTEM.JMS.D.SUBSCRIBER.QUEUE
.
Used by: WebSphere MQ JMS
Supported values are TRUE
and FALSE
. This property is only used for outbound propagation to a JMS queue or topic. 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
.
Used by: WebSphere MQ Base Java
This property 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
Used by: TIB/Rendezvous
This property 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.
See Also:
Oracle Streams Advanced Queuing User's Guide and Reference for the message conversion details |
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
. Supported values are PERSISTENT
, NON_PERSISTENT
and PRESERVE_MSG
. The default is PRESERVE_MSG
.
PERSISTENT
, then the delivery mode will be DeliveryMode.PERSISTENT
.NON_PERSISTENT
, then the delivery mode will be DeliveryMode.NON_PERSISTENT
.PRESERVE_MSG
, then the delivery mode of the source JMS message will be used when the message is propagated to the destination queue.Used by: WebSphere MQ JMS and Oracle JMS
You can use this property when the propagation source is a JMS messaging system. It sets the noLocal
parameter of a JMS TopicSubscriber
. Supported values are TRUE
and FALSE
. The default is FALSE
.
TRUE
indicates that messages that have been published to this topic through the same Messaging Gateway link will not be propagated.FALSE
indicates that such messages will be propagated from the topic.Used by: any
This property specifies the maximum number of messages, if available, to be propagated in one transaction. The default is 30.
Used by: TIB/Rendezvous
This property specifies the discard amount of a queue. It is meaningful only for an inbound propagation subscriber. The default is 0.
Used by: TIB/Rendezvous
This property specifies the limit policy for resolving overflow of a queue limit. It is meaningful only for an inbound propagation subscriber. Supported values are DISCARD_NONE
, DISCARD_FIRST
, DISCARD_LAST
and DISCARD_NEW
. The default is DISCARD_NONE
.
DISCARD_NONE
, then the limit policy is set to TibrvQueue.DISCARD_NONE
.DISCARD_FIRST
, then the limit policy is set to TibrvQueue.DISCARD_FIRST
.DISCARD_LAST
, then the limit policy is set to TibrvQueue.DISCARD_LAST
.DISCARD_NEW
, then the limit policy is set to TibrvQueue.DISCARD_NEW
.Used by: TIB/Rendezvous
This property specifies the maximum event limit of a queue. It is meaningful only for an inbound propagation subscriber. The default is 0.
The views listed in Table 51-19 provide Messaging Gateway configuration, status, and statistical information. Unless otherwise indicated, the SELECT
privilege is granted to MGW_ADMINISTRATOR_ROLE
so that only Messaging Gateway administrators have access to the views. All views are owned by SYS
.
This view lists configuration and status information for Messaging Gateway, as shown in Table 51-20.
This view lists the names and types of messaging system links currently defined. Table 51-21 lists the MGW_LINKS
view properties.
This view lists information for the WebSphere MQ messaging system links. The view includes most of the messaging system properties specified when the link is created. Table 51-22 lists the MGW_MQSERIES_LINKS
view properties.
This view lists information for TIB/Rendezvous messaging system links. The view includes most of the messaging system properties specified when the link was created. Table 51-23 lists the MGW_TIBRV_LINKS
view properties.
This view lists information for foreign queues. The view includes most of the queue properties specified when the queue is registered. Table 51-24 lists the MGW_FOREIGN_QUEUES
view properties.
This view lists configuration and status information for Messaging Gateway subscribers. The view includes most of the subscriber properties specified when the subscriber is added, as well as other status and statistical information. Table 51-25 lists the MGW_SUBSCRIBERS
view properties.
This procedure adds a subscriber used to consume messages from a source queue for propagation to a destination.
DBMS_MGWADM.ADD_SUBSCRIBER( subscriber_id IN VARCHAR2, propagation_type IN BINARY_INTEGER, queue_name IN VARCHAR2, destination IN VARCHAR2, rule IN VARCHAR2 DEFAULT NULL, transformation IN VARCHAR2 DEFAULT NULL, exception_queue IN VARCHAR2 DEFAULT NULL options IN SYS.MGW_PROPERTIES DEFAULT NULL);
See Also:
"Messaging Gateway Message Transformation", in Oracle Streams Advanced Queuing User's Guide and Reference for more information regarding message conversion and transformation |
If the non-Oracle messaging link being accessed for the subscriber uses a JMS interface, then the Messaging Gateway agent will use the Oracle JMS interface to access the Oracle Streams AQ queues. Otherwise the native Oracle Streams AQ interface will be used. Parameters are interpreted differently when the Messaging Gateway agent uses Oracle JMS for JMS connections.
Transformations are not currently supported if the Oracle JMS interface is used for propagation. The transformation parameter must be NULL
.
The parameters for a subscriber used for outbound propagation are interpreted as follows:
queue_name
specifies the local Oracle Streams AQ queue that is the propagation source. This must have a syntax of schema.queue
.destination
specifies the foreign queue to which messages are propagated. This must have a syntax of registered_queue@message_link
.rule
specifies an optional Oracle Streams AQ subscriber rule if the native Oracle Streams AQ interface is used, or a JMS selector if the Oracle JMS interface is used. If NULL
, then no rule or selector is used.transformation
specifies the transformation used to convert the Oracle Streams AQ payload to an ADT defined by Messaging Gateway.
Messaging Gateway propagation dequeues messages from the Oracle Streams AQ queue using the transformation to convert the Oracle Streams AQ payload to a known ADT defined by Messaging Gateway. The message is then enqueued in the foreign messaging system based on the Messaging Gateway ADT.
exception_queue
specifies the name of a local Oracle Streams AQ queue to which messages are moved if an exception occurs. This must have a syntax of schema.queue
.If the native Oracle Streams AQ interface is used, then a subscriber will be added to the Oracle Streams AQ queue when this procedure is called, whether or not Messaging Gateway is running. The local subscriber will be of the form sys.aq$_agent('MGW_
subscriber_id
'
, NULL,
NULL)
.
If the Oracle JMS interface is used, then the Messaging Gateway agent will create a JMS durable subscriber with the name of MGW_
subscriber_id
. If the agent is not running when this procedure is called, then the durable subscriber will be created the next time the agent starts.
The exception queue has the following caveats:
DBMS_AQADM.NORMAL_QUEUE
rather than DBMS_AQADM.EXCEPTION_QUEUE
. Enqueue restrictions prevent Messaging Gateway propagation from using an Oracle Streams AQ queue of type EXCEPTION_QUEUE
as a Messaging Gateway exception queue.The parameters for a subscriber used for inbound propagation are interpreted as follows:
queue_name
specifies the foreign queue that is the propagation source. This must have a syntax of registered_queue@message_link
.destination
specifies the local Oracle Streams AQ queue to which messages are propagated. This must have a syntax of schema.queue
.rule
specifies an optional subscriber rule that is valid for the foreign messaging system. This is NULL
if no rule is needed.transformation
specifies the transformation used to convert an ADT defined by Messaging Gateway to the Oracle Streams AQ payload type.
Messaging Gateway propagation dequeues messages from the foreign messaging system and converts the message body to a known ADT defined by Messaging Gateway. The transformation is used to convert the Messaging Gateway ADT to an Oracle Streams AQ payload type when the message is enqueued to the Oracle Streams AQ queue.
exception_queue
specifies the name of a foreign queue to which messages are moved if an exception occurs. This must have a syntax of registered_queue@message_link
.Whether or not a subscriber is needed depends on the requirements of the non-Oracle messaging system. If a durable subscriber is necessary, then it will be created by the Messaging Gateway agent. If the agent is not running at the time this procedure is called, then the creation of the subscriber on the non-Oracle messaging system will occur when the agent next starts.
The exception queue has the following caveats:
This procedure configures Messaging Gateway agent parameters.
DBMS_MGWADM.ALTER_AGENT ( max_connections IN BINARY_INTEGER DEFAULT NULL, max_memory IN BINARY_INTEGER DEFAULT NULL, max_threads IN BINARY_INTEGER DEFAULT NULL);
Default values for these configuration parameters are set when the Messaging Gateway agent is installed.
Changes to the max_memory
and max_threads
parameters take effect the next time the Messaging Gateway agent is active. If the Messaging Gateway agent is currently active, then it must be shut down and restarted for the changes to take effect.
Alters the properties of a TIB/Rendezvous messaging system link.
DBMS_MGWADM.ALTER_MSGSYSTEM_LINK ( linkname IN VARCHAR2, properties IN SYS.MGW_TIBRV_PROPERTIES, options IN SYS.MGW_PROPERTIES DEFAULT NULL, comment IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE );
To retain an existing value for a messaging link property with a VARCHAR2
data type, specify DBMS_MGWADM.NO_CHANGE
for that particular property. To preserve an existing value for a property of another data type, specify NULL
for that property.
The options
parameter specifies a set of properties used to alter the current optional properties. Each property affects the current property list in a particular manner: add a new property, replace an existing property, remove an existing property, or remove all properties.
Some properties cannot be modified, and this procedure will fail if an attempt is made to alter such a property. For properties and options that can be changed, a few are dynamic, and Messaging Gateway uses the new values immediately. Others require the Messaging Gateway agent to be shut down and restarted before they take effect.
See Also:
"TIB/Rendezvous System Properties" for more information about the messaging system properties and options |
This procedure alters the properties of a WebSphere MQ messaging system link.
DBMS_MGWADM.ALTER_MSGSYSTEM_LINK ( linkname IN VARCHAR2, properties IN SYS.MGW_MQSERIES_PROPERTIES, options IN SYS.MGW_PROPERTIES DEFAULT NULL, comment IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE);
To retain an existing value for a messaging link property with a VARCHAR2
data type, specify DBMS_MGWADM.NO_CHANGE
for that particular property. To preserve an existing value for a property of another data type, specify NULL
for that property.
The options
parameter specifies a set of properties used to alter the current optional properties. Each property affects the current property list in a particular manner: add a new property, replace an existing property, remove an existing property, or remove all properties.
Some properties cannot be modified, and this procedure will fail if an attempt is made to alter such a property. For properties and options that can be changed, a few are dynamic, and Messaging Gateway uses the new values immediately. Others require the Messaging Gateway agent to be shut down and restarted before they take effect.
See Also:
"WebSphere MQ System Properties" for more information about the messaging system properties and options |
This procedure alters a propagation schedule.
DBMS_MGWADM.ALTER_PROPAGATION_SCHEDULE ( schedule_id IN VARCHAR2, duration IN NUMBER DEFAULT NULL, next_time IN VARCHAR2 DEFAULT NULL, latency IN NUMBER DEFAULT NULL);
This procedure always overwrites the existing value for each parameter. If a given parameter is not specified, then the existing values are overwritten with the default value.
This procedure alters the parameters of a subscriber used to consume messages from a source queue for propagation to a destination.
DBMS_MGWADM.ALTER_SUBSCRIBER ( subscriber_id IN VARCHAR2, rule IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE, transformation IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE, exception_queue IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE options IN SYS.MGW_PROPERTIES DEFAULT NULL );
If the non-Oracle messaging link being accessed for the subscriber uses a JMS interface, then the Messaging Gateway agent will use the Oracle JMS interface to access the Oracle Streams AQ queues. Otherwise the native Oracle Streams AQ interface will be used. Parameters are interpreted differently when the Messaging Gateway agent uses Oracle JMS for JMS connections.
When propagating from a JMS source, the subscriber rule cannot be altered. Instead, the subscriber must be removed and added with the new rule. For JMS, changing the message selector on a durable subscription is equivalent to deleting and re-creating the subscription.
Transformations are not currently supported if the Oracle JMS interface is used for propagation. The transformation parameter must be DBMS_MGWADM.NO_CHANGE
(the default value).
The options
parameter specifies a set of properties used to alter the current optional properties. Each property affects the current property list in a particular manner: add a new property, replace an existing property, remove an existing property, or remove all properties.
See Also:
|
This procedure cleans up Messaging Gateway. The procedure performs cleanup or recovery actions that may be needed when Messaging Gateway is left in some abnormal or unexpected condition. The MGW_GATEWAY
view lists Messaging Gateway status and configuration information that pertains to the cleanup actions.
DBMS_MGWADM.CLEANUP_GATEWAY( action IN BINARY_INTEGER sarg IN VARCHAR2 DEFAULT NULL);
sarg
is not used and must be NULL
.
The CLEAN_STARTUP_STATE
action recovers Messaging Gateway to a known state when the Messaging Gateway agent has crashed or some other abnormal event occurs, and Messaging Gateway cannot be restarted. This should be done only when the Messaging Gateway agent has been started but appears to have crashed or has been nonresponsive for an extended period of time.
The CLEAN_STARTUP_STATE
action may be needed when the MGW_GATEWAY
view shows that the AGENT_STATUS
value is something other than NOT_STARTED
or START_SCHEDULED,
and the AGENT_PING
value is UNREACHABLE
for an extended period of time.
If the AGENT_STATUS
value is BROKEN
, then the Messaging Gateway agent cannot be started until the problem has been resolved and the CLEAN_STARTUP_STATE
action used to reset the agent status. A BROKEN
status can indicate that the Messaging Gateway start job detected a Messaging Gateway agent already running. This condition that should never occur under normal use.
Cleanup tasks include:
NOT_STARTED.
Execution of this command fails if:
NOT_STARTED
or START_SCHEDULED.
STARTING.
The assumption is that the agent is active, and this procedure fails. If the agent does not respond after several attempts have been made, then the cleanup tasks are performed. This procedure takes at least several seconds and possibly up to one minute. This is expected behavior under conditions where this particular cleanup action is appropriate and necessary.
sarg
is not used and must be NULL
.
The Messaging Gateway agent will clean log queues for all configured messaging system links. The agent will temporarily stop all propagation activity and then remove all obsolete and bad log records from the log queues for all links. The procedure will fail if the Messaging Gateway agent is not running.
This cleanup action is automatically performed each time the Messaging Gateway agent is started.
Note: For Oracle Database 10g, the |
sarg
specifies a Messaging Gateway subscriber ID to be reset. It must be not NULL
.
The Messaging Gateway agent recovers a Messaging Gateway subscriber that has failed due to a missing log record. The agent will reset the source and destination log records. The procedure will fail if the Messaging Gateway agent is not running.
Caution: If the messages in the source queue had already been propagated to the destination queue, then this action may result in duplicate messages. |
sarg
specifies a Messaging Gateway subscriber ID to be reset. It must be not NULL
.
The Messaging Gateway agent recovers a Messaging Gateway subscriber that has failed due to a missing persistent source message. The agent will treat the message as a non-persistent message and continue processing that subscriber. The procedure will fail if the Messaging Gateway agent is not running.
Creates a link to a TIB/Rendezvous messaging system.
DBMS_MGWADM.CREATE_MSGSYSTEM_LINK ( linkname IN VARCHAR2, properties IN SYS.MGW_TIBRV_PROPERTIES, options IN SYS.MGW_PROPERTIES DEFAULT NULL, comment IN VARCHAR2 DEFAULT NULL );
See Also:
"TIB/Rendezvous System Properties" for more information about the messaging system properties and options |
This procedure creates a messaging system link to a WebSphere MQ messaging system.
DBMS_MGWADM.CREATE_MSGSYSTEM_LINK( linkname IN VARCHAR2, properties IN SYS.MGW_MQSERIES_PROPERTIES, options IN SYS.MGW_PROPERTIES DEFAULT NULL, comment IN VARCHAR2 DEFAULT NULL);
See Also:
"WebSphere MQ System Properties" for more information about the messaging system properties and options |
This procedure configures connection information used by the Messaging Gateway agent for connections to Oracle Database.
DBMS_MGWADM.DB_CONNECT_INFO ( username IN VARCHAR2, password IN VARCHAR2, database IN VARCHAR2 DEFAULT NULL);
The Messaging Gateway agent connects to Oracle Database as the user configured by this procedure. An Oracle administrator should create the user, grant it the role MGW_AGENT_ROLE,
and then call this procedure to configure Messaging Gateway. Role MGW_AGENT_ROLE
is used to grant this user special privileges needed to access Messaging Gateway configuration information stored in the database, enqueue or dequeue messages to and from Oracle Streams AQ queues, and perform certain Oracle Streams AQ administration tasks.
This procedure disables a propagation schedule.
DBMS_MGWADM.DISABLE_PROPAGATION_SCHEDULE ( schedule_id IN VARCHAR2 );
Parameter | Description |
---|---|
|
Identifies the propagation schedule to be disabled |
This procedure enables a propagation schedule.
DBMS_MGWADM.ENABLE_PROPAGATION_SCHEDULE ( schedule_id IN VARCHAR2 );
Parameter | Description |
---|---|
|
Identifies the propagation schedule to be enabled |
This procedure registers a non-Oracle queue entity in Messaging Gateway.
DBMS_MGWADM.REGISTER_FOREIGN_QUEUE( name IN VARCHAR2, linkname IN VARCHAR2, provider_queue IN VARCHAR2 DEFAULT NULL, domain IN INTEGER DEFAULT NULL, options IN SYS.MGW_PROPERTIES DEFAULT NULL, comment IN VARCHAR2 DEFAULT NULL);
This procedure does not create the physical queue in the non-Oracle messaging system. The non-Oracle queue must be created using the administration tools for that messaging system.
See Also:
|
This procedure removes a messaging system link for a non-Oracle messaging system.
DBMS_MGWADM.REMOVE_MSGSYSTEM_LINK( linkname IN VARCHAR2);
Parameters | Description |
---|---|
|
The messaging system link name |
All registered queues associated with this link must be removed before the messaging system link can be removed. This procedure fails if there is a registered foreign (non-Oracle) queue that references this link.
This procedure removes a subscriber used to consume messages from a source queue for propagation to a destination.
DBMS_MGWADM.REMOVE_SUBSCRIBER ( subscriber_id IN VARCHAR2, force IN BINARY_INTEGER DEFAULT DBMS_MGWADM.NO_FORCE );
For outbound propagation, a local subscriber is removed from the Oracle Streams AQ queue.
This procedure resets the propagation error state for a subscriber.
DBMS_MGWADM.RESET_SUBSCRIBER ( subscriber_id IN VARCHAR2 );
Parameter | Description |
---|---|
|
Identifies the subscriber |
This procedure dynamically alters the Messaging Gateway agent logging level. The Messaging Gateway agent must be running.
DBMS_MGWADM.SET_LOG_LEVEL ( log_level IN BINARY_INTEGER);
Parameter | Description |
---|---|
|
Level at which the Messaging Gateway agent logs information. |
See Also:
Table 51-6, " DBMS_MGWADM Constants--Logging Levels" for details on the |
This procedure schedules message propagation from a source to a destination. The schedule must be enabled and Messaging Gateway started in order for messages to be propagated.
DBMS_MGWADM.SCHEDULE_PROPAGATION ( schedule_id IN VARCHAR2, propagation_type IN BINARY_INTEGER, source IN VARCHAR2, destination IN VARCHAR2, start_time IN DATE DEFAULT SYSDATE, duration IN NUMBER DEFAULT NULL, next_time IN VARCHAR2 DEFAULT NULL, latency IN NUMBER DEFAULT NULL);
For outbound propagation, parameters are interpreted as follows:
source
specifies the local Oracle Streams AQ queue from which messages are propagated. This must have a syntax of schema.queue
.destination
specifies the foreign queue to which messages are propagated. This must have a syntax of registered_queue@message_link
.For inbound propagation, parameters are interpreted as follows:
source
specifies the foreign queue from which messages are propagated. This must have a syntax of registered_queue@message_link
.destination
specifies the local Oracle Streams AQ queue to which messages are propagated. This must have a syntax of schema.queue
.The schedule is set to an enabled state when it is created.
This procedure shuts down the Messaging Gateway agent. No propagation activity occurs until Messaging Gateway is restarted.
DBMS_MGWADM.SHUTDOWN ( sdmode IN BINARY_INTEGER DEFAULT DBMS_MGWADM.SHUTDOWN_NORMAL);
This procedure starts the Messaging Gateway agent. It must be called before any propagation activity can take place.
DBMS_MGWADM.STARTUP( instance IN BINARY_INTEGER DEFAULT 0, force IN BINARY_INTEGER DEFAULT DBMS_MGWADM.NO_FORCE);
The Messaging Gateway agent cannot be started until an agent user has been configured using DB_CONNECT_INFO
.
This procedure submits a job queue job, which starts the Messaging Gateway agent when it runs. The instance
and force
parameters are used for job queue affinity, which you use to indicate whether a particular instance or any instance can run a submitted job.
This procedure removes a non-Oracle queue entity in Messaging Gateway.
DBMS_MGWADM.UNREGISTER_FOREIGN_QUEUE( name IN VARCHAR2, linkname IN VARCHAR2);
Parameter | Description |
---|---|
|
The queue name |
|
The link name for the messaging system on which the queue exists |
This procedure does not remove the physical queue in the non-Oracle messaging system.
All subscribers and schedules referencing this queue must be removed before it can be unregistered. This procedure fails if a subscriber or propagation schedule references the non-Oracle queue.
This procedure removes a propagation schedule.
DBMS_MGWADM.UNSCHEDULE_PROPAGATION ( schedule_id IN VARCHAR2 );
Parameter | Description |
---|---|
|
Identifies the propagation schedule to be removed |