DBMS_MGWADM
defines the Messaging Gateway administrative interface. The package and object types are owned by SYS
.
Note:
You must run thecatmgw.sql
script to load the Messaging Gateway packages and types into the database.See Also:
Oracle Database Advanced Queuing User's Guide contains information on loading database objects and usingDBMS_MGWADM
This chapter contains the following topics:
Security Model
Constants
Deprecated Subprograms
Oracle recommends that you do not use deprecated procedures in new applications. Support for deprecated features is for backward compatibility only.
The following subprograms are deprecated with Oracle Database 11g Release 1having been superseded by improved technology:
ADD_SUBSCRIBER Procedure - use instead CREATE_JOB Procedure
ALTER_PROPAGATION_SCHEDULE Procedure - use instead ALTER_JOB Procedure
ALTER_SUBSCRIBER Procedure - use instead ALTER_JOB Procedure
DB_CONNECT_INFO Procedure - use instead ALTER_AGENT Procedures
DISABLE_PROPAGATION_SCHEDULE Procedure - use instead DISABLE_JOB Procedure
ENABLE_PROPAGATION_SCHEDULE Procedure - use instead ENABLE_JOB Procedure
REMOVE_SUBSCRIBER Procedure - use instead REMOVE_JOB Procedure
RESET_SUBSCRIBER Procedure - use instead RESET_JOB Procedure
SCHEDULE_PROPAGATION Procedure - use instead CREATE_JOB Procedure
UNSCHEDULE_PROPAGATION Procedure - use instead REMOVE_JOB Procedure
DBMS_MGWADM Constants—target_type Argument of SET_OPTION and REMOVE_OPTION Procedures
DBMS_MGWADM Constants—conntype Argument of CREATE_AGENT and ALTER_AGENT Procedures
Table 97-1 DBMS_MGWADM Constants—Cleanup Actions
Name | Type | Description |
---|---|---|
|
|
Sets the Messaging Gateway agent to a known state so that it can be started |
|
|
Messaging Gateway agent will clean log queues for all configured messaging system links |
|
|
Messaging Gateway agent recovers a Messaging Gateway subscriber that has failed due to a missing log record |
|
|
Messaging Gateway agent recovers a Messaging Gateway subscriber that has failed due to a missing persistent source message |
Table 97-2 DBMS_MGWADM Constants—Force Values
Name | Type | Description |
---|---|---|
|
|
Represents a forced action |
|
|
Represents a normal, nonforced action |
Table 97-3 DBMS_MGWADM Constants—Logging Levels
Name | Type | Description |
---|---|---|
|
|
The standard (the least) information written to the log file |
|
|
The greatest information written to the log file |
|
|
The third level of detail of logging information written to the log file |
|
|
The second level detail of logging information written to the log file |
Table 97-4 DBMS_MGWADM Constants—Named Property Constants
Name | Type | Description |
---|---|---|
|
|
A constant ( |
|
|
A constant ( |
|
|
A constant ( |
Table 97-5 DBMS_MGWADM Constants—Other Constants
Name | Type | Description |
---|---|---|
|
|
Used to indicate that JMS connections will be used to access JMS destinations in a domain-independent manner that supports a unified messaging model |
|
|
Used to indicate that JMS queue connections will be used to access JMS destinations |
|
|
Used to indicate that JMS topic connections will be used to access JMS destinations |
|
|
Indicates that an existing value should be preserved (not changed). This is used for certain APIs where the desire is to change one or more parameters but leave others unchanged. |
|
|
Name of the Messaging Gateway default agent |
Table 97-6 DBMS_MGWADM Constants—Propagation Types
Name | Type | Description |
---|---|---|
|
|
Represents the propagation type for non-Oracle to Oracle Database Advanced Queuing propagation. The propagation source is a queue in a foreign (non-Oracle) messaging system and the destination is a local Oracle Database Advanced Queuing queue. |
|
|
Represents the propagation type for Oracle Database Advanced Queuing to non-Oracle propagation. The propagation source is a local Oracle Database Advanced Queuing queue and the destination is a queue in a foreign (non-Oracle) messaging system. |
Table 97-7 DBMS_MGWADM Constants—Queue Domain Types
Name | Type | Description |
---|---|---|
|
|
Represents a queue destination. A JMS queue (point-to-point model) is classified as a queue. |
|
|
Represents a topic destination. A JMS topic (publish-subscribe model) is classified as a topic. |
Table 97-8 DBMS_MGWADM Constants—Shutdown Modes
Name | Type | Description |
---|---|---|
|
|
Represents the immediate shutdown mode |
|
|
Represents the normal shutdown mode |
Table 97-9 DBMS_MGWADM Constants—WebSphere MQ Interface Types
Name | Type | Description |
---|---|---|
|
|
Represents the Base Java interface for the WebSphere MQ messaging system |
Table 97-10 DBMS_MGWADM Constants—target_type Argument of SET_OPTION and REMOVE_OPTION Procedures
Name | Type | Description |
---|---|---|
|
|
Used for an agent option used to set a Java System property |
|
|
Used for a messaging system link option |
|
|
Used for a propagation job option |
The DBMS_MGWADM
package defines the following OBJECT
types.
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 );
Table 97-12 SYS.MGW_MQSERIES_PROPERTIES Attributes
Attribute | Description |
---|---|
|
The name of the WebSphere MQ queue manager |
|
The host on which the WebSphere MQ messaging system resides. If hostname is |
|
The port number. This is used only for client connections; that is, when |
|
The channel used when establishing a connection to the queue manager. This is used only for client connections; that is, when |
|
The type of messaging interface to use. Values:
|
|
The maximum number of messaging connections to the WebSphere MQ messaging system |
|
The username used for authentication to the WebSphere MQ messaging system |
|
The password used for authentication to the WebSphere MQ messaging system |
|
The name of the WebSphere MQ queue used for propagation recovery purposes when this messaging link is used for inbound propagation; that is, when queues associated with this link serve as a propagation source:
|
|
The name of the WebSphere MQ queue used for propagation recovery purposes when this messaging link is used for outbound propagation; that is, when queues associated with this link serve as a propagation destination:
|
Table 97-13 SYS.MGW_MQSERIES_PROPERTIES Methods
Method | Description |
---|---|
|
Constructs a new |
|
Constructs a new |
This type specifies an array of properties.
Unless noted otherwise, Messaging Gateway uses named properties as follows:
Names with the MGWPROP$_
prefix are reserved. They are used for special purposes and are invalid when used as a normal property name.
A property name can exist only once in a property list; that is, a list can contain only one value for a given name. The name is case-insensitive.
In general, a property list is order-independent, and the property names may appear in any order. An alter property list is an exception.
You can use a new property list to alter an existing property list. Each new property modifies the original list in one of the following ways: adds a new property, modifies a property, removes a property, or removes all properties.
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:
Add or modify property
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.
Remove property
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.
Remove all properties
MGW_PROPERTY.NAME = 'MGWPROP$_REMOVE_ALL' MGW_PROPERTY.VALUE = not used
See Also:
"TheDBMS_MGWADM
package defines constants to represent the reserved property names on Table 97-4, "DBMS_MGWADM Constants—Named Property Constants"This type specifies a named property which is used to specify optional properties for messaging links, foreign queues, and subscribers.
TYPE SYS.MGW_PROPERTY IS OBJECT( name VARCHAR2(500), value VARCHAR2(4000), -- Methods STATIC FUNCTION construct --- (1) RETURN SYS.MGW_PROPERTY, STATIC FUNCTION construct( --- (2) p_name IN VARCHAR2, p_value IN VARCHAR2) RETURN SYS.MGW_PROPERTY );
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 );
Table 97-17 SYS.MGW_TIBRV_PROPERTIES Attributes
Attribute | Description |
---|---|
|
The service parameter for the rvd transport |
|
The daemon parameter for the rvd transport |
|
The network parameter for the rvd transport |
|
The CM correspondent name. Reserved for future use. |
|
The CM ledger file name. Reserved for future use. |
Table 97-18 SYS.MGW_TIBRV_PROPERTIES Methods
Method | Description |
---|---|
|
Constructs a new |
|
Constructs a new |
Table 97-19 DBMS_MGWADM Package Subprograms
Subprogram | Description |
---|---|
Adds a subscriber used to consume messages from a source queue for propagation to a destination |
|
Alters Messaging Gateway agent parameters |
|
Alters the properties of a propagation job |
|
Alters the properties of a TIB/Rendezvous messaging system link |
|
Alters the properties of a WebSphere MQ messaging system link |
|
Alters a propagation schedule |
|
Alters the parameters of a subscriber used to consume messages from a source queue for propagation to a destination |
|
Cleans up Messaging Gateway |
|
Creates a Messaging Gateway agent that will be used to process propagation jobs |
|
Creates a job used to propagate message from a source to a destination |
|
Creates a messaging system link to a TIB/Rendezvous messaging system |
|
Creates a messaging system link to a WebSphere MQ messaging system |
|
Configures connection information used by the Messaging Gateway agent for connections to Oracle Database |
|
Disables a propagation job |
|
Disables a propagation schedule |
|
Enables a propagation job |
|
Enables a propagation schedule |
|
Registers a non-Oracle queue entity in Messaging Gateway |
|
Removes a Messaging Gateway agent |
|
Removes a propagation job |
|
Removes a messaging system link for a non-Oracle messaging system |
|
Removes a Messaging Gateway configuration option |
|
Removes a subscriber used to consume messages from a source queue for propagation to a destination |
|
Resets the propagation error state for a propagation job |
|
Resets the propagation error state for a subscriber |
|
Schedules message propagation from a source to a destination |
|
Dynamically alters the Messaging Gateway agent logging level |
|
Sets a Messaging Gateway configuration option |
|
Shuts down the Messaging Gateway agent |
|
Starts the Messaging Gateway agent |
|
Removes a non-Oracle queue entity in Messaging Gateway |
|
Removes a propagation schedule |
This procedure adds a subscriber used to consume messages from a source queue for propagation to a destination.
Note:
This subprogram has been deprecated as a result of improved technology (see CREATE_JOB Procedure), and is retained only for reasons of backward compatibility.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);
Table 97-20 ADD_SUBSCRIBER Procedure Parameters
Parameter | Description |
---|---|
|
Specifies a user-defined name that identifies this subscriber |
|
Specifies the type of message propagation. |
|
Specifies the source queue to which this subscriber is being added. The syntax and interpretation of this parameter depend on the value specified for |
|
Specifies the destination queue to which messages consumed by this subscriber are propagated. The syntax and interpretation of this parameter depend on the value specified for |
|
Specifies an optional subscription rule used by the subscriber to dequeue messages from the source queue. This is |
|
Specifies the transformation needed to convert between the Oracle Database Advanced Queuing payload and an ADT defined by Messaging Gateway. The type of transformation needed depends on the value specified for If |
|
Specifies a queue used for exception message logging purposes. This queue must be on the same messaging system as the propagation source. If The source queue and exception queue cannot be the same queue. |
|
Optional subscriber properties. |
See Also:
"Handling Arbitrary Payload Types Using Message Transformations", in Oracle Database Advanced Queuing User's Guide for more information regarding message conversion and transformationIf 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 Database Advanced Queuing queues. Otherwise the native Oracle Database Advanced Queuing 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
.
See Also:
For additional information regarding subscriber optionsOUTBOUND_PROPAGATION Subscribers
The parameters for a subscriber used for outbound propagation are interpreted as follows:
queue_name
specifies the local Oracle Database Advanced Queuing 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 Database Advanced Queuing subscriber rule if the native Oracle Database Advanced Queuing 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 Database Advanced Queuing payload to an ADT defined by Messaging Gateway.
Messaging Gateway propagation dequeues messages from the Oracle Database Advanced Queuing queue using the transformation to convert the Oracle Database Advanced Queuing 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 Database Advanced Queuing queue to which messages are moved if an exception occurs. This must have a syntax of schema.queue
.
If the native Oracle Database Advanced Queuing interface is used, then a subscriber will be added to the Oracle Database Advanced Queuing 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:
The user is responsible for creating the Oracle Database Advanced Queuing queue to be used as the exception queue.
The payload type of the source and exception queue must match.
The exception queue must be created as a queue type of DBMS_AQADM.NORMAL_QUEUE
rather than DBMS_AQADM.EXCEPTION_QUEUE
. Enqueue restrictions prevent Messaging Gateway propagation from using an Oracle Database Advanced Queuing queue of type EXCEPTION_QUEUE
as a Messaging Gateway exception queue.
INBOUND_PROPAGATION Subscribers
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 Database Advanced Queuing 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 Database Advanced Queuing 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 Database Advanced Queuing payload type when the message is enqueued to the Oracle Database Advanced Queuing 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:
The exception queue must be a registered non-Oracle queue.
The source and exception queues must use the same messaging system link.
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, service IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE );
DBMS_MGWADM.ALTER_AGENT ( agent_name IN VARCHAR2, username IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE, password IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE, database IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE, conntype IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE, max_memory IN PLS_INTEGER DEFAULT NULL, max_threads IN PLS_INTEGER DEFAULT NULL, service IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE, initfile IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE, comment IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE );
Table 97-21 ALTER_AGENT Procedure Parameters
Parameter | Description |
---|---|
|
The maximum number of messaging connections to Oracle Database used by the Messaging Gateway agent. If it is Caution: This parameter has been deprecated. |
|
The maximum heap size, in MB, used by the Messaging Gateway agent. If it is |
|
The number of messaging threads that the Messaging Gateway agent creates. If it is |
|
Specifies the database service that the Oracle Scheduler job class used by this agent will have affinity to. In an Oracle RAC environment, this means that the Messaging Gateway agent will run on only those database instances that are assigned to the service. If |
|
Identifies the Messaging Gateway agent. |
|
Specifies the username used for connections to the Oracle Database. |
|
Specifies the password used for connections to the Oracle Database. |
|
Specifies the database connect string used for connections to the Oracle Database. |
|
Specifies the type of connection to the Oracle Database, |
|
Specifies a Messaging Gateway initialization file used by this agent. |
|
Optional comments for this agent. |
Note:
Themax_connections
parameter included in previous versions of this subprogram has been deprecated and is non-operationalDefault 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.
The service
parameter is used to set an Oracle Scheduler job class attribute. The job class is used to create a Scheduler job that starts the Messaging Gateway agent. An Oracle administrator must create the database service. If the value is NULL, the job class will belong to an internal service that is mapped to all instances.
The max_connections
parameter is being deprecated as of the Oracle RDBMS 11g release. The number of messaging connections used by the Messaging Gateway Agent is based on the value of the max_threads
parameter.
The username
, password
, and database
parameters specify connection information used by the Messaging Gateway agent for connections to the Oracle Database. An Oracle administrator should create the user and grant it the role MGW_AGENT_ROLE
.
This procedure alters the properties of a propagation job.
DBMS_MGWADM.ALTER_JOB ( job_name 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, poll_interval IN PLS_INTEGER DEFAULT 0, options IN SYS.MGW_PROPERTIES DEFAULT NULL, comments IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE );
Table 97-22 ALTER_JOB Procedure Parameters
Parameter | Description |
---|---|
|
Identifies the propagation job |
|
Specifies an optional subscription rule used to dequeue messages from the propagation source. The syntax and interpretation of this parameter depend on the propagation type. A |
|
Specifies the transformation needed to convert between the Oracle Streams AQ payload and an ADT defined by Messaging Gateway. The type of transformation needed depends on the value specified for A |
|
Specifies a queue used for exception message logging purposes. This queue must be on the same messaging system as the propagation source. In cases in which no exception queue is associated with the job, propagation stops if a problem occurs. The syntax and interpretation of this parameter depend on the propagation type. A |
|
Specifies the polling interval, in seconds, used by the Messaging Gateway agent when checking for messages in the source queue. If no messages are available the agent will not poll again until the polling interval has passed. Once the agent detects a message it will continue propagating messages as long as any are available. Values:
|
|
Optional job properties. If |
|
An optional comment for this agent, or |
If the non-Oracle messaging link being accessed for the propagation job 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.
The subscriber rule cannot be altered when propagating from a JMS source. Instead, the propagation job must be dropped and re-created 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:
SYS.MGW_PROPERTY Object Type for more information about the options parameter
OUTBOUND_PROPAGATION Jobs for outbound propagation parameter interpretation
INBOUND_PROPAGATION Jobs for inbound propagation parameter interpretation
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 );
Table 97-23 ALTER_MSGSYSTEM_LINK Procedure Parameters for TIB/Rendezvous
Parameters | Description |
---|---|
|
The messaging system link name |
|
Basic properties for a TIB/Rendezvous messaging system link. If |
|
Optional link properties. If |
|
A user-specified description, or |
To retain an existing value for a messaging link property with a VARCHAR2
datatype, specify DBMS_MGWADM.NO_CHANGE
for that particular property. To preserve an existing value for a property of another datatype, 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.
See Also:
SYS.MGW_PROPERTIES Object TypeSome 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" in Oracle Database Advanced Queuing User's Guide for more information about the messaging system properties and optionsThis 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);
Table 97-24 ALTER_MSGSYSTEM_LINK Procedure Parameters for WebSphere MQ
Parameters | Description |
---|---|
|
The messaging system link name |
|
Basic properties for a WebSphere MQ messaging system link. If it is |
|
Optional link properties. |
|
An optional description or |
To retain an existing value for a messaging link property with a VARCHAR2
datatype, specify DBMS_MGWADM.NO_CHANGE
for that particular property. To preserve an existing value for a property of another datatype, 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.
See Also:
SYS.MGW_PROPERTIES Object TypeSome 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" in Oracle Database Advanced Queuing User's Guide for more information about the messaging system properties and optionsThis procedure alters a propagation schedule.
Note:
This subprogram has been deprecated as a result of improved technology (see ALTER_JOB Procedure), and is retained only for reasons of backward compatibility.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);
Table 97-25 ALTER_PROPAGATION_SCHEDULE Procedure Parameters
Parameter | Description |
---|---|
|
Identifies the propagation schedule to be altered |
|
Reserved for future use |
|
Reserved for future use |
|
Specifies the polling interval, in seconds, used by the Messaging Gateway agent when checking for messages in the source queue. If no messages are available in the source queue, then the agent will not poll again until the polling interval has passed. Once the agent detects a message it will continue propagating messages as long as any are available. Values: |
This procedure alters the parameters of a subscriber used to consume messages from a source queue for propagation to a destination.
Note:
This subprogram has been deprecated as a result of improved technology (see ALTER_JOB Procedure ), and is retained only for reasons of backward compatibility.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 );
Table 97-26 ALTER_SUBSCRIBER Procedure Parameters
Parameter | Description |
---|---|
|
Identifies the subscriber to be altered |
|
Specifies an optional subscription rule used by the subscriber to dequeue messages from the source queue. The syntax and interpretation of this parameter depend on the subscriber propagation type. A |
|
Specifies the transformation needed to convert between the Oracle Database Advanced Queuing payload and an ADT defined by Messaging Gateway. The type of transformation needed depends on the subscriber propagation type. A |
|
Specifies a queue used for exception message logging. This queue must be on the same messaging system as the propagation source. If no exception queue is associated with the subscriber, then propagation stops if a problem occurs. The syntax and interpretation of this parameter depend on the subscriber propagation type. A The source queue and exception queue cannot be the same queue. |
|
Optional subscriber properties. If |
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 Database Advanced Queuing queues. Otherwise the native Oracle Database Advanced Queuing 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:
SYS.MGW_PROPERTIES Object Type for more information on the options parameter
"WebSphere MQ System Properties" in Oracle Database Advanced Queuing User's Guide for more information about WebSphere MQ subscriber options
"TIB/Rendezvous System Properties" in Oracle Database Advanced Queuing User's Guide for more information about TIB/Rendezvous subscriber options
"OUTBOUND_PROPAGATION Subscribers for outbound propagation parameter interpretation
"INBOUND_PROPAGATION Subscribers for inbound propagation parameter interpretation
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);
DBMS_MGWADM.CLEANUP_GATEWAY( agent_name IN VARCHAR2, action IN BINARY_INTEGER, sarg IN VARCHAR2 DEFAULT NULL );
Table 97-27 CLEANUP_GATEWAY Procedure Parameters
Parameter | Description |
---|---|
|
The cleanup action to be performed. Values:
|
|
Optional argument whose meaning depends on the value specified for |
|
Identifies the Messaging Gateway agent. |
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:
Removing the Scheduler job used to start the external Messaging Gateway agent process.
Setting certain configuration information to a known state. For example, setting the agent status to NOT_STARTED.
Execution of this command fails if:
The agent status is NOT_STARTED
or START_SCHEDULED.
No shutdown attempt has been made prior to calling this procedure, except if the agent status is STARTING.
The Messaging Gateway agent is successfully contacted.
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.
Note:
Terminate any Messaging Gateway agent process that may still be running after aCLEAN_STARTUP_STATE
action has been successfully performed. This should be done before calling DBMS_MGWADM
.STARTUP
to start Messaging Gateway. The process is usually named extprocmgwextproc
.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:
TheCLEAN_LOG_QUEUES
action is performed only on agent startup. If this procedure is called when the agent is running, then the Messaging Gateway agent ignores it.sarg
specifies a Messaging Gateway job name (or subscriber ID) to be reset. It must not be NULL
.
The Messaging Gateway agent recovers a Messaging Gateway propagation job 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 job name (or subscriber ID) to be reset. It must not be NULL
.
The Messaging Gateway agent recovers a Messaging Gateway propagation job 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 propagation job. The procedure will fail if the Messaging Gateway agent is not running.
This procedure creates a Messaging Gateway agent that will be used to process propagation jobs.
DBMS_MGWADM.CREATE_AGENT ( agent_name IN VARCHAR2, username IN VARCHAR2 DEFAULT NULL, password IN VARCHAR2 DEFAULT NULL, database IN VARCHAR2 DEFAULT NULL, conntype IN VARCHAR2 DEFAULT DBMS_MGWADM.JDBC_OCI, max_memory IN PLS_INTEGER DEFAULT 64, max_threads IN PLS_INTEGER DEFAULT 1, service IN VARCHAR2 DEFAULT NULL, initfile IN VARCHAR2 DEFAULT NULL, comment IN VARCHAR2 DEFAULT NULL );
Table 97-28 CREATE_AGENT Procedure Parameters
Parameter | Description |
---|---|
|
A name used to identify the agent |
|
Specifies the username used for connections to the Oracle Database |
|
Specifies the password used for connections to the Oracle Database. A password must be specified if a username is specified. |
|
Specifies the database connect string used for connections to the Oracle Database. |
|
Specifies the type of connection to the Oracle Database.Values: |
|
Specifies the maximum heap size, in MB, used by the Messaging Gateway agent |
|
Specifies the number of messaging threads that the Messaging Gateway agent creates. This determines the number of propagation jobs that the agent can concurrently process. |
|
Specifies the database service that the Oracle Scheduler job class used by this agent will have affinity to. In an Oracle RAC environment, this means that the Messaging Gateway agent will only run on those database instances that are assigned to the service. If NULL, then the job class will belong to the default service which is mapped to every instance. |
|
Specifies a Messaging Gateway initialization file used by this agent. NULL indicates that the default initialization file is used. If a value is specified, it should be the full path name of the file. |
|
An optional comment for this agent. |
The Messaging Gateway automatically configures a default agent when Messaging Gateway is installed. The name of the default agent is DEFAULT_AGENT
. This procedure can be used to create additional agents.
The username
, password
, and database
parameters specify connection information used by the Messaging Gateway agent for connections to the Oracle Database. An Oracle administrator should create the database user and grant it the role MGW_AGENT_ROLE
. It is not mandatory that the connection information be specified when this procedure is called but it must be set before the agent can be started.
The service
parameter is used to create an Oracle Scheduler job class. The job class is used to create a Scheduler job that starts the Messaging Gateway agent. An Oracle administrator must create the database service. If the value is NULL
, the job class will belong to an internal service that is mapped to all instances.
This procedure creates a job used to propagate message from a source to a destination.
DBMS_MGWADM.CREATE_JOB ( job_name IN VARCHAR2, propagation_type IN PLS_INTEGER, source IN VARCHAR2, destination IN VARCHAR2, rule IN VARCHAR2 DEFAULT NULL, transformation IN VARCHAR2 DEFAULT NULL, exception_queue IN VARCHAR2 DEFAULT NULL, poll_interval IN PLS_INTEGER DEFAULT NULL, options IN SYS.MGW_PROPERTIES DEFAULT NULL, enabled IN BOOLEAN DEFAULT TRUE, comments IN VARCHAR2 DEFAULT NULL);
Table 97-29 CREATE_JOB Procedure Parameters
Parameter | Description |
---|---|
|
A user defined name to identify the propagation job |
|
Specifies the type of message propagation.
|
|
Specifies the source queue whose messages are to be propagated. The syntax and interpretation of this parameter depend on the value specified for |
|
Specifies the destination queue to which messages are propagated. The syntax and interpretation of this parameter depend on the value specified for |
|
Specifies an optional subscription rule used to dequeue messages from the source queue. This should be |
|
Specifies the transformation needed to convert between the Oracle Streams AQ payload and an ADT defined by Messaging Gateway. The type of transformation needed depends on the value specified for If no transformation is specified the Oracle Streams AQ payload type must be supported by Messaging Gateway. |
|
Specifies a queue used for exception message logging purposes. This queue must be on the same messaging system as the propagation source. If The source queue and exception queue cannot be the same queue. |
|
Specifies the polling interval, in seconds, used by the Messaging Gateway agent when checking for messages in the source queue. If no messages are available the agent will not poll again until the polling interval has passed. Once the agent detects a message it will continue propagating messages as long as any are available. Values: |
|
Optional job properties, |
|
Specifies whether this propagation job is enabled after creation. Values:
|
|
An optional comment for this job. |
The job must be enabled and Messaging Gateway agent started in order for messages to be propagated.
If the non-Oracle messaging link being accessed for the propagation job 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 an outbound propagation job are interpreted as follows:
source
specifies the local Oracle Streams AQ queue that is the propagation source. This must have syntax of schema.queue. This can be either a multiple consumer queue or a single consumer queue.
destination
specifies the non-Oracle queue to which messages are propagated. This must have syntax of registered_queue
@message_link
.
rule
specifies an optional Oracle Streams AQ subscriber rule if the native Oracle Stream AQ interface is used, or a JMS selector if the Oracle JMS interface is used. If NULL
, then no rule or selector is used. This parameter must be NULL
if the native Oracle Stream AQ interface is used and the propagation source is a single consumer queue.
transformation
specifies the transformation used to convert the Oracle Streams AQ payload to an ADT defined by Messaging Gateway. The full transformation name (schema
.name
) should be used if one is specified.
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 non-Oracle 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. The syntax must be schema
.queue
.
If the native Oracle Streams AQ interface is used and the source is a multiple consumer queue, then a subscriber will be added to the Oracle Streams AQ queue when this procedure is called, whether or not the Messaging Gateway agent is running. The local subscriber will be of the form sys
.aq$_agent
('MGW_job_name
', 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_job_name
. 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 conditions:
The user is responsible for creating the Oracle Streams AQ queue to be used as the exception queue.
The payload type of the source queue and exception queue must match.
The exception queue must be created as a queue type of DBMS_AQADM
.NORMAL_QUEUE
. Enqueue restrictions prevent Messaging Gateway from using an Oracle Streams AQ queue of type DBMS_AQADM
.EXCEPTION_QUEUE
as a Messaging Gateway exception queue.
The parameters for an inbound propagation job are interpreted as follows:
source
specifies the non-Oracle queue that is the propagation source. The syntax must be registered_queue
@message_link
.
destination
specifies the local Oracle Streams AQ queue to which messages are propagated. The syntax must be schema
.queue
.
rule
specifies an optional subscriber rule that is valid for the non-Oracle messaging system. This should be 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. The full transformation name (schema
.name
) should be used if one is specified
Messaging Gateway propagation dequeues messages from the non-Oracle 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 registered non-Oracle queue to which messages are moved if an exception occurs. The syntax must be registered_queue@message_link
.
Whether or not a subscriber is needed for the source queue depends on the requirements of the non-Oracle messaging system. If a durable subscriber is necessary, then the Messaging Gateway agent will create it. If the agent is not running when this procedure is called, then the subscriber will be created on the non-Oracle messaging system the next time the agent starts.
The exception queue has the following conditions:
The exception queue must be a registered non-Oracle queue.
The source queue and exception queue must use the same messaging system link.
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 );
DBMS_MGWADM.CREATE_MSGSYSTEM_LINK ( linkname IN VARCHAR2, agent_name IN VARCHAR2, properties IN SYS.MGW_TIBRV_PROPERTIES, options IN SYS.MGW_PROPERTIES DEFAULT NULL, comment IN VARCHAR2 DEFAULT NULL );
Table 97-30 CREATE_MSGSYSTEM_LINK Procedure Parameters for TIB/Rendezvous
Parameter | Description |
---|---|
|
A user-defined name to identify this messaging system link |
|
Basic properties of a TIB/Rendezvous messaging system link. |
|
Optional link properties. |
|
A user-specified description. |
|
Specifies the Messaging Gateway agent that will be used to process all propagation jobs associated with this link. |
The Messaging Gateway default agent will process the propagation jobs associated with this link if an agent name is not specified.
See Also:
"TIB/Rendezvous System Properties" in Oracle Database Advanced Queuing User's Guide for more information about the messaging system properties and optionsThis 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);
DBMS_MGWADM.CREATE_MSGSYSTEM_LINK( linkname IN VARCHAR2, agent_name IN VARCHAR2, properties IN SYS.MGW_MQSERIES_PROPERTIES, options IN SYS.MGW_PROPERTIES DEFAULT NULL, comment IN VARCHAR2 DEFAULT NULL);
Table 97-31 CREATE_MSGSYSTEM_LINK Procedure Parameters for WebSphere MQ
Parameter | Description |
---|---|
|
A user-defined name to identify the messaging system link |
|
Basic properties of a WebSphere MQ messaging system link |
|
Optional link properties. |
|
A user-specified description. |
|
Specifies the Messaging Gateway agent that will be used to process all propagation jobs associated with this link. |
The Messaging Gateway default agent will process the propagation jobs associated with this link if an agent name is not specified.
See Also:
"WebSphere MQ System Properties" in Oracle Database Advanced Queuing User's Guide for more information about the messaging system properties and optionsThis procedure configures connection information used by the Messaging Gateway default agent for connections to Oracle Database.
Note:
This subprogram has been deprecated as a result of improved technology (see ALTER_AGENT Procedures), and is retained only for reasons of backward compatibility.DBMS_MGWADM.DB_CONNECT_INFO ( username IN VARCHAR2, password IN VARCHAR2, database IN VARCHAR2 DEFAULT NULL);
Table 97-32 DB_CONNECT_INFO Procedure Parameters
Parameter | Description |
---|---|
|
The username used for connections to Oracle Database. |
|
The password used for connections to Oracle Database. |
|
The database connect string used by the Messaging Gateway agent. Oracle strongly recommends that a not |
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 Database Advanced Queuing queues, and perform certain Oracle Database Advanced Queuing administration tasks.
This procedure disables a propagation schedule.
Note:
This subprogram has been deprecated as a result of improved technology (see DISABLE_JOB Procedure), and is retained only for reasons of backward compatibility.This procedure enables a propagation schedule.
Note:
This subprogram has been deprecated as a result of improved technology (see ENABLE_JOB Procedure), and is retained only for reasons of backward compatibility.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);
Table 97-37 REGISTER_FOREIGN_QUEUE Procedure Parameters
Parameters | Description |
---|---|
|
The registered queue name. This name identifies the foreign queue within Messaging Gateway and need not match the name of the queue in the foreign messaging system. |
|
The link name for the messaging system on which this queue exists |
|
The message provider (native) queue name. If |
|
The domain type of the queue. |
|
Optional queue properties |
|
A user-specified description. Can be |
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:
For more information when registering queues for the WebSphere MQ messaging system or the TIB/Rendezvous messaging system, specifically "Optional Foreign Queue Configuration Properties" in Oracle Database Advanced Queuing User's Guide.This procedure removes a propagation job.
DBMS_MGWADM.REMOVE_JOB( job_name IN VARCHAR2, force IN PLS_INTEGER DEFAULT DBMS_MGWADM.NO_FORCE);
Table 97-39 REMOVE_JOB Procedure Parameters
Parameters | Description |
---|---|
|
Identifies the propagation job |
force |
Specifies whether the procedure should succeed even if Messaging Gateway is not able to perform all cleanup actions pertaining to this propagation job. Values:
|
The Messaging Gateway agent uses various resources of the Oracle Database and the non-Oracle messaging system for its propagation work. These resources need to be released when the job is removed. For example, Messaging Gateway may create a durable subscriber on the source queue that should be removed when the job is removed. Therefore, this procedure should normally be called when the Messaging Gateway agent is running and able to access the non-Oracle messaging system associated with this job.
For outbound propagation, a local subscriber is removed from the Oracle Streams AQ queue when the propagation source is a multiple consumer queue.
This procedure removes a messaging system link for a non-Oracle messaging system.
This procedure removes a Messaging Gateway configuration option. It can be used to remove an agent option, a messaging link option, or a propagation job option.
DBMS_MGWADM.REMOVE_OPTION ( target_type IN PLS_INTEGER, target_name IN VARCHAR2, option_name IN VARCHAR2);
Table 97-41 REMOVE_OPTION Procedure Parameters
Parameter | Description |
---|---|
|
Specifies the target type of the Messaging Gateway entity:
|
|
Name or identifier of the target. The value for this parameter depends on the value specified for |
option_name |
Option name. This must not be |
See Also:
Table 97-10, "DBMS_MGWADM Constants—target_type Argument of SET_OPTION and REMOVE_OPTION Procedures" regarding options for theoption_type
parameterDBMS_MGWADM.AGENT_JAVA_PROP Target
The procedure removes an agent option used to set a Java System property when the Messaging Gateway agent is started. The agent must be restarted for the change to take effect.
The parameters are interpreted as follows:
target_name
specifies the name of the Messaging Gateway agent. DBMS_MGWADM
.DEFAULT_AGENT
can be used for the default agent.
option_name
specifies the Java System property
encrypted
can be either TRUE
or FALSE
DBMS_MGWADM.MSGLINK_OPTION Target
The procedure removes a single option for a Messaging Gateway messaging system link. This is equivalent to calling DBMS_MGWADM
.ALTER_MSGSYSTEM_LINK
and using the options parameter to remove an option.
The parameters are interpreted as follows:
target_name
specifies the name of the message system link
option_name
specifies the option to set
encrypted
must be FALSE
The procedure removes a single option for a Messaging Gateway propagation job. This is equivalent to calling DBMS_MGWADM
.ALTER_JOB
and using the options parameter to remove an option.
The parameters are interpreted as follows:
target_name
specifies the name of the propagation job
option_name
specifies the option to set
encrypted
must be FALSE
This procedure removes a subscriber used to consume messages from a source queue for propagation to a destination.
Note:
This subprogram has been deprecated as a result of improved technology (see REMOVE_JOB Procedure), and is retained only for reasons of backward compatibility.DBMS_MGWADM.REMOVE_SUBSCRIBER ( subscriber_id IN VARCHAR2, force IN BINARY_INTEGER DEFAULT DBMS_MGWADM.NO_FORCE );
Table 97-42 REMOVE_SUBSCRIBER Procedure Parameters
Parameter | Description |
---|---|
|
Identifies the subscriber to be removed |
|
Specifies whether this procedure should succeed even if Messaging Gateway is not able to perform all cleanup actions pertaining to this subscriber. Values:
|
The Messaging Gateway agent uses various resources of Oracle Database and the non-Oracle messaging system for its propagation work. These resources are typically associated with each subscriber and need to be released when the subscriber is no longer needed. Therefore, this procedure should only be called when the Messaging Gateway agent is running and able to access the non-Oracle messaging system associated with this subscriber.
For outbound propagation, a local subscriber is removed from the Oracle Database Advanced Queuing queue.
This procedure resets the propagation error state for a propagation job.
This procedure can be used to reset a propagation job that has been set to a failed state and propagation activities have been stopped. The administrator should correct the problem and then call this procedure to allow the agent to retry the propagation job. The STATUS
field of the MGW_JOBS
view indicates the job status.
This procedure resets the propagation error state for a subscriber.
Note:
This subprogram has been deprecated as a result of improved technology (see RESET_JOB Procedure), and is retained only for reasons of backward compatibility.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.
Note:
This subprogram has been deprecated as a result of improved technology (see CREATE_JOB Procedure), and is retained only for reasons of backward compatibility.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);
Table 97-45 SCHEDULE_PROPAGATION Procedure Parameters
Parameter | Description |
---|---|
|
Specifies a user-defined name that identifies the schedule |
|
Specifies the type of message propagation. |
|
Specifies the source queue whose messages are to be propagated. The syntax and interpretation of this parameter depend on the value specified for |
|
Specifies the destination queue to which messages are propagated. The syntax and interpretation of this parameter depend on the value specified for |
|
Reserved for future use |
|
Reserved for future use |
|
Reserved for future use |
|
Specifies the polling interval, in seconds, used by the Messaging Gateway agent when checking for messages in the source queue. If no messages are available in the source queue, then the agent will not poll again until the polling interval has passed. Once the agent detects a message it will continue propagating messages as long as any are available. Values: |
For outbound propagation, parameters are interpreted as follows:
source
specifies the local Oracle Database Advanced Queuing 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 Database Advanced Queuing 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 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);
DBMS_MGWADM.SET_LOG_LEVEL ( agent_name IN VARCHAR2, log_level IN BINARY_INTEGER);
Table 97-46 SET_LOG_LEVEL Procedure Parameters
Parameter | Description |
---|---|
|
Level at which the Messaging Gateway agent logs information. |
|
Identifies the Messaging Gateway agent. |
This procedure sets a Messaging Gateway configuration option. It can be used to set an agent option, a messaging link option, or a propagation job option.
DBMS_MGWADM.SET_OPTION ( target_type IN PLS_INTEGER, target_name IN VARCHAR2, option_name IN VARCHAR2, option_value IN VARCHAR2, encrypted IN BOOLEAN DEFAULT FALSE );
Table 97-47 SET_OPTION Procedure Parameters
Parameter | Description |
---|---|
|
Specifies the target type of the Messaging Gateway entity:
|
|
Name or identifier of the target. The value for this parameter depends on the value specified for |
option_name |
Option name. This must not be |
|
Option value |
|
Indicates whether the value should be stored as encrypted:
|
See Also:
Table 97-10, "DBMS_MGWADM Constants—target_type Argument of SET_OPTION and REMOVE_OPTION Procedures" regarding options for theoption_type
parameterDBMS_MGWADM.AGENT_JAVA_PROP Target
The procedure will store an agent option used to set a Java System property when the Messaging Gateway agent is started. The agent must be restarted for the change to take effect.
The parameters are interpreted as follows:
target_name
specifies the name of the Messaging Gateway agent. DBMS_MGWADM
.DEFAULT_AGENT
can be used for the default agent.
option_name
specifies the Java System property
encrypted
can be either TRUE
or FALSE
DBMS_MGWADM.MSGLINK_OPTION Target
The procedure will set or alter a single option for a Messaging Gateway messaging system link. This is equivalent to calling DBMS_MGWADM
.ALTER_MSGSYSTEM_LINK
and using the options parameter to set an option.
The parameters are interpreted as follows:
target_name
specifies the name of the message system link
option_name
specifies the option to set
encrypted
must be FALSE
The procedure will set or alter a single option for a Messaging Gateway propagation job. This is equivalent to calling DBMS_MGWADM
.ALTER_JOB
and using the options parameter to set an option.
The parameters are interpreted as follows:
target_name
specifies the name of the propagation job
option_name
specifies the option to set
encrypted
must be FALSE
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);
DBMS_MGWADM.SHUTDOWN ( agent_name IN VARCHAR2);
Table 97-48 SHUTDOWN Procedure Parameters
Parameter | Description |
---|---|
|
The shutdown mode. The only value currently supported is |
|
Identifies the Messaging Gateway agent. |
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);
DBMS_MGWADM.STARTUP( agent_name IN VARCHAR2);
Table 97-49 STARTUP Procedure Parameters
Parameter | Description |
---|---|
|
Specifies which instance can run the job queue job used to start the Messaging Gateway agent. If this is zero, then the job can be run by any instance. Caution: This parameter has been deprecated. |
|
If this is Caution: This parameter has been deprecated. |
|
Identifies the Messaging Gateway agent. |
The Messaging Gateway default agent will be started if an agent name is not specified.
The force
and instance
parameters are no longer used and will be ignored. If the instance
affinity parameters were being used to start the default agent on a specific instance, the administrator will need to create a database service and then assign that service to the default agent using the DBMS_MGWADM
.ALTER_AGENT
procedure.
The Messaging Gateway agent cannot be started until an agent user has been configured by the DBMS_MGWADM
.CREATE_AGENT
or DBMS_MGWADM
.ALTER_AGENT
subprograms.
This procedure removes a non-Oracle queue entity in Messaging Gateway.
This procedure does not remove the physical queue in the non-Oracle messaging system.
All propagation jobs, subscribers and schedules referencing this queue must be removed before it can be unregistered. This procedure fails if a propagation job, subscriber, or propagation schedule references the non-Oracle queue.
This procedure removes a propagation schedule.
Note:
This subprogram has been deprecated as a result of improved technology (see REMOVE_JOB Procedure), and is retained only for reasons of backward compatibility.