58 DBMS_MGWADM

DBMS_MGWADM defines the Messaging Gateway administrative interface. The package and object types are owned by SYS.

Note:

You must run the catmgw.sql script to load the Messaging Gateway packages and types into the database.

See Also:

Oracle Streams Advanced Queuing User's Guide and Reference contains information on loading database objects and using DBMS_MGWADM

This chapter contains the following topics:

Using DBMS_MGWADM
- Constants
- Views
Data Structures
Summary of DBMS_MGWADM Subprograms

Constants

DBMS_MGWADM Constants—Cleanup Actions
DBMS_MGWADM Constants—Force Values
DBMS_MGWADM Constants—Logging Levels
DBMS_MGWADM Constants—Named Property Constants
DBMS_MGWADM Constants—Other Constants
DBMS_MGWADM Constants—Propagation Types
DBMS_MGWADM Constants—Queue Domain Types
DBMS_MGWADM Constants—Shutdown Modes
DBMS_MGWADM Constants—WebSphere MQ Interface Types

Table 58-1 DBMS_MGWADM Constants—Cleanup Actions

Name	Type	Description
`CLEAN_STARTUP_STATE`	`CONSTANT BINARY_INTEGER`	Sets the Messaging Gateway agent to a known state so that it can be started
`CLEAN_LOG_QUEUES`	`CONSTANT BINARY_INTEGER`	Messaging Gateway agent will clean log queues for all configured messaging system links
`RESET_SUB_MISSING_LOG_REC`	`CONSTANT BINARY_INTEGER`	Messaging Gateway agent recovers a Messaging Gateway subscriber that has failed due to a missing log record
`RESET_SUB_MISSING_MESSAGE`	`CONSTANT BINARY_INTEGER`	Messaging Gateway agent recovers a Messaging Gateway subscriber that has failed due to a missing persistent source message

Table 58-2 DBMS_MGWADM Constants—Force Values

Name	Type	Description
`FORCE`	`CONSTANT BINARY_INTEGER`	Represents a forced action
`NO_FORCE`	`CONSTANT BINARY_INTEGER`	Represents a normal, nonforced action

Table 58-3 DBMS_MGWADM Constants—Logging Levels

Name	Type	Description
`BASIC_LOGGING`	`CONSTANT BINARY_INTEGER`	The standard (the least) information written to the log file
`TRACE_DEBUG_LOGGING`	`CONSTANT BINARY_INTEGER`	The greatest information written to the log file
`TRACE_HIGH_LOGGING`	`CONSTANT BINARY_INTEGER`	The third level of detail of logging information written to the log file
`TRACE_LITE_LOGGING`	`CONSTANT BINARY_INTEGER`	The second level detail of logging information written to the log file

Table 58-4 DBMS_MGWADM Constants—Named Property Constants

Name	Type	Description
`MGWPROP_PREFIX`	`CONSTANT VARCHAR2`	A constant (`MGWPROP$_`) for the reserved property name prefix
`MGWPROP_REMOVE`	`CONSTANT VARCHAR2`	A constant (`MGWPROP$_REMOVE`) for the reserved property name used to remove an existing property
`MGWPROP_REMOVE_ALL`	`CONSTANT VARCHAR2`	A constant (`MGWPROP$_REMOVE_ALL`) for the reserved property name used to remove all properties

Table 58-5 DBMS_MGWADM Constants—Other Constants

Name	Type	Description
`JMS_CONNECTION`	`CONSTANT BINARY_INTEGER`	Used to indicate that JMS connections will be used to access JMS destinations in a domain-independent manner that supports a unified messaging model
`JMS_QUEUE_CONNECTION`	`CONSTANT BINARY_INTEGER`	Used to indicate that JMS queue connections will be used to access JMS destinations
`JMS_TOPIC_CONNECTION`	`CONSTANT BINARY_INTEGER`	Used to indicate that JMS topic connections will be used to access JMS destinations
`NO_CHANGE`	`CONSTANT VARCHAR2`	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.

Table 58-6 DBMS_MGWADM Constants—Propagation Types

Name	Type	Description
`INBOUND_PROPAGATION`	`CONSTANT BINARY_INTEGER`	Represents the propagation type for non-Oracle to Oracle Streams AQ propagation. The propagation source is a queue in a foreign (non-Oracle) messaging system and the destination is a local Oracle Streams AQ queue.
`OUTBOUND_PROPAGATION`	`CONSTANT BINARY_INTEGER`	Represents the propagation type for Oracle Streams AQ to non-Oracle propagation. The propagation source is a local Oracle Streams AQ queue and the destination is a queue in a foreign (non-Oracle) messaging system.

Table 58-7 DBMS_MGWADM Constants—Queue Domain Types

Name	Type	Description
`DOMAIN_QUEUE`	`CONSTANT BINARY_INTEGER`	Represents a queue destination. A JMS queue (point-to-point model) is classified as a queue.
`DOMAIN_TOPIC`	`CONSTANT BINARY_INTEGER`	Represents a topic destination. A JMS topic (publish-subscribe model) is classified as a topic.

Table 58-8 DBMS_MGWADM Constants—Shutdown Modes

Name	Type	Description
`SHUTDOWN_IMMEDIATE`	`CONSTANT BINARY_INTEGER`	Represents the immediate shutdown mode
`SHUTDOWN_NORMAL`	`CONSTANT BINARY_INTEGER`	Represents the normal shutdown mode

Table 58-9 DBMS_MGWADM Constants—WebSphere MQ Interface Types

Name	Type	Description
`MQSERIES_BASE_JAVA_INTERFACE`	`CONSTANT BINARY_INTEGER`	Represents the Base Java interface for the WebSphere MQ messaging system

Views

The views listed in Table 58-10 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.

Table 58-10 Database Views

Name	Description
MGW_GATEWAY View	Configuration and status information for Messaging Gateway
MGW_LINKS View	Names and types of messaging system links currently created
MGW_MQSERIES_LINKS View	Messaging system properties for WebSphere MQ links
MGW_TIBRV_LINKS View	Messaging system properties for TIB/Rendezvous links
MGW_FOREIGN_QUEUES View	Queue properties of registered queues
MGW_SUBSCRIBERS View	Subscriber properties, status, and statistical information
MGW_SCHEDULES View	Schedule properties and status

MGW_GATEWAY View

This view lists configuration and status information for Messaging Gateway, as shown in Table 58-11.

Table 58-11 MGW_GATEWAY View Properties

Name	Type	Description
`AGENT_DATABASE`	`VARCHAR2`	The database connect string used by the Messaging Gateway agent. `NULL` indicates that a local connection is used.
`AGENT_INSTANCE`	`NUMBER`	The database instance on which the Messaging Gateway agent is currently running. This should be `NULL` if the agent is not running.
`AGENT_JOB`	`NUMBER`	Job number of the queued job used to start the Messaging Gateway agent process. The job number is set when Messaging Gateway is started and cleared when it shuts down.
`AGENT_PING`	`VARCHAR2`	Gateway agent ping status. Values: `NULL` means no ping attempt was made. `REACHABLE` means ping attempt was successful. `UNREACHABLE` means ping attempt failed. `AGENT_PING` attempts to contact the Messaging Gateway agent. There is a short delay (up to 5 seconds) if the ping attempt fails. No ping is attempted if the `AGENT_STATUS` is `NOT_STARTED` or `START_SCHEDULED`.
`AGENT_START_TIME`	`TIMESTAMP`	The time when the Messaging Gateway agent job currently running was started. This should be `NULL` if the agent is not running.
`AGENT_STATUS`	`VARCHAR2`	Status of the Messaging Gateway agent. Values: `NOT_STARTED` means the Messaging Gateway agent has not been started `START_SCHEDULED` means Messaging Gateway agent has been scheduled to start. That is, Messaging Gateway has been started using `DBMS_MGWADM.STARTUP`, but the queued job used to start the Messaging Gateway agent has not yet run. `STARTING` means Messaging Gateway agent is starting. That is, Messaging Gateway has been started using `DBMS_MGWADM.STARTUP`, the queued job has run, and the Messaging Gateway agent is starting up. `INITIALIZING` means the Messaging Gateway agent has started and is initializing `RUNNING` means the Messaging Gateway agent is running `SHUTTING_DOWN` means the Messaging Gateway agent is shutting down `BROKEN` means an unexpected condition has been encountered that prevents the Messaging Gateway agent from starting. `DBMS_MGWADM.CLEANUP_GATEWAY` must be called before the agent can be started.
`AGENT_USER`	`VARCHAR2`	Database username used by the Messaging Gateway agent to connect to the database
`LAST_ERROR_DATE`	`DATE`	Date of last Messaging Gateway agent error. The last error information is cleared when Messaging Gateway is started. It is set if the Messaging Gateway agent fails to start or terminates due to an abnormal condition.
`LAST_ERROR_MSG`	`VARCHAR2`	Message for last Messaging Gateway agent error
`LAST_ERROR_TIME`	`VARCHAR2`	Time of last Messaging Gateway agent error
`MAX_CONNECTIONS`	`NUMBER`	Maximum number of messaging connections to Oracle Database
`MAX_MEMORY`	`NUMBER`	Maximum heap size used by the Messaging Gateway agent (in MB)
`MAX_THREADS`	`NUMBER`	Maximum number of messaging threads created by the Messaging Gateway agent

MGW_LINKS View

This view lists the names and types of messaging system links currently defined. Table 58-12 lists the MGW_LINKS view properties.

Table 58-12 MGW_LINKS View Properties

Name	Type	Description
`LINK_COMMENT`	`VARCHAR2`	User comment for the link
`LINK_NAME`	`VARCHAR2`	Name of the messaging system link
`LINK_TYPE`	`VARCHAR2`	Type of messaging system link. Values `MQSERIES` is for WebSphere MQ links. `TIBRV` is for TIB/Rendezvous links.

MGW_MQSERIES_LINKS View

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 58-13 lists the MGW_MQSERIES_LINKS view properties.

Table 58-13 MGW_MQSERIES_LINKS View Properties

Name	Type	Description
`CHANNEL`	`VARCHAR2`	Connection channel
`HOSTNAME`	`VARCHAR2`	Name of the WebSphere MQ host
`INBOUND_LOG_QUEUE`	`VARCHAR2`	Inbound propagation log queue
`INTERFACE_TYPE`	`VARCHAR2`	Messaging interface type. Values: `BASE_JAVA` is for WebSphere MQ Base Java interface `JMS_CONNECTION` is for WebSphere MQ JMS unified, domain-independent connections `JMS_QUEUE_CONNECTION` is for WebSphere MQ JMS queue connections `JMS_TOPIC_CONNECTION` is for WebSphere MQ JMS topic connections
`LINK_COMMENT`	`VARCHAR2`	User comment for the link
`LINK_NAME`	`VARCHAR2`	Name of the messaging system link
`MAX_CONNECTIONS`	`NUMBER`	Maximum number of messaging connections
`OPTIONS`	`SYS.MGW_PROPERTIES`	Link options
`OUTBOUND_LOG_QUEUE`	`VARCHAR2`	Outbound propagation log queue
`PORT`	`NUMBER`	Port number
`QUEUE_MANAGER`	`VARCHAR2`	Name of the WebSphere MQ queue manager

MGW_TIBRV_LINKS View

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 58-14 lists the MGW_TIBRV_LINKS view properties.

Table 58-14 MGW_TIBRV_LINKS View Properties

Property Name	Type	Description
`CM_LEDGER`	`VARCHAR2`	TIB/Rendezvous CM ledger file name
`CM_NAME`	`VARCHAR2`	TIB/Rendezvous CM correspondent name
`DAEMON`	`VARCHAR2`	TIB/Rendezvous daemon parameter for rvd transport
`LINK_COMMENT`	`VARCHAR2`	User comment for the link
`LINK_NAME`	`VARCHAR2`	Name of the messaging system link
`NETWORK`	`VARCHAR2`	TIB/Rendezvous network parameter for rvd transport
`OPTIONS`	`SYS.MGW_PROPERTIES`	Link options
`SERVICE`	`VARCHAR2`	TIB/Rendezvous service parameter for rvd transport

MGW_FOREIGN_QUEUES View

This view lists information for foreign queues. The view includes most of the queue properties specified when the queue is registered. Table 58-15 lists the MGW_FOREIGN_QUEUES view properties.

Table 58-15 MGW_FOREIGN_QUEUES View Properties

Name	Type	Description
`DOMAIN`	`VARCHAR2`	Queue domain type. Values: `NULL` means the queue domain type is automatically determined by the messaging system `QUEUE` is for a queue (point-to-point) model `TOPIC` is for a topic (publish-subscribe) model
`LINK_NAME`	`VARCHAR2`	Name of the messaging system link
`NAME`	`VARCHAR2`	Name of the registered queue
`OPTIONS`	`SYS.MGW_PROPERTIES`	Optional queue properties
`PROVIDER_QUEUE`	`VARCHAR2`	Message provider (native) queue name
`QUEUE_COMMENT`	`VARCHAR2`	User comment for the foreign queue

MGW_SUBSCRIBERS View

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 58-16 lists the MGW_SUBSCRIBERS view properties.

Table 58-16 MGW_SUBSCRIBERS View Properties

Name	Type	Description
`DESTINATION`	`VARCHAR2`	Destination queue to which messages are propagated
`EXCEPTIONQ_MSGS`	`NUMBER`	Number of messages moved to the propagation exception queue since the last time the agent was started
`EXCEPTION_QUEUE`	`VARCHAR2`	Exception queue used for logging purposes
`FAILURES`	`NUMBER`	Number of propagation failures
`LAST_ERROR_DATE`	`DATE`	Date of last propagation error
`LAST_ERROR_MSG`	`VARCHAR2`	Message for last propagation error
`LAST_ERROR_TIME`	`VARCHAR2`	Time of last propagation error
`OPTIONS`	`SYS.MGW_PROPERTIES`	Subscriber options
`PROP_STYLE`	`VARCHAR2`	Message propagation style. Values: `NATIVE` is for native message propagation `JMS` is for JMS message propagation
`PROPAGATED_MSGS`	`NUMBER`	Number of messages propagated to the destination queue since the last time the agent was started
`PROPAGATION_TYPE`	`VARCHAR2`	Propagation type. Values: `OUTBOUND` is for Oracle Streams AQ to non-Oracle propagation `INBOUND` is for non-Oracle to Oracle Streams AQ propagation
`QUEUE_NAME`	`VARCHAR2`	Subscriber source queue
`RULE`	`VARCHAR2`	Subscription rule
`STATUS`	`VARCHAR2`	Subscriber status. Values: `ENABLED` means the subscriber is enabled `DELETE_PENDING` means subscriber removal is pending, usually because `DBMS_MGWADM.REMOVE_SUBSCRIBER` has been called but certain cleanup tasks pertaining to this subscriber are still outstanding
`SUBSCRIBER_ID`	`VARCHAR2`	Propagation subscriber identifier
`TRANSFORMATION`	`VARCHAR2`	Transformation used for message conversion

MGW_SCHEDULES View

This view lists configuration and status information for Messaging Gateway schedules. The view includes most of the schedule properties specified when the schedule is created, as well as other status information. Table 58-17 lists the MGW_SCHEDULES view properties.

Table 58-17 MGW_SCHEDULES View Properties

Name	Type	Description
`DESTINATION`	`VARCHAR2`	Propagation destination
`LATENCY`	`NUMBER`	Propagation window latency (in seconds)
`NEXT_TIME`	`VARCHAR2`	Reserved for future use
`PROPAGATION_TYPE`	`VARCHAR2`	Propagation type. Values: `OUTBOUND` is for Oracle Streams AQ to non-Oracle propagation `INBOUND` is for non-Oracle to Oracle Streams AQ propagation
`PROPAGATION_WINDOW`	`NUMBER`	Reserved for future use
`SCHEDULE_DISABLED`	`VARCHAR2`	Indicates whether the schedule is disabled. `Y` means the schedule is disabled. `N` means the schedule is enabled.
`SCHEDULE_ID`	`VARCHAR2`	Propagation schedule identifier
`SOURCE`	`VARCHAR2`	Propagation source
`START_DATE`	`DATE`	Reserved for future use
`START_TIME`	`VARCHAR2`	Reserved for future use

Data Structures

The DBMS_MGWADM package defines the following OBJECT types.

Object Types

SYS.MGW_MQSERIES_PROPERTIES Object Type
SYS.MGW_PROPERTIES Object Type
SYS.MGW_PROPERTY Object Type
SYS.MGW_TIBRV_PROPERTIES Object Type

SYS.MGW_MQSERIES_PROPERTIES Object Type

This type specifies basic properties for a WebSphere MQ messaging system link.

Syntax

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 );

Attributes

Table 58-18 SYS.MGW_MQSERIES_PROPERTIES Attributes

Attribute	Description
`queue_manager`	The name of the WebSphere MQ queue manager
`hostname`	The host on which the WebSphere MQ messaging system resides. If hostname is `NULL,` then a WebSphere MQ bindings connection is used. If not `NULL`, then a client connection is used and requires that a port and channel be specified.
`port`	The port number. This is used only for client connections; that is, when `hostname` is not `NULL`.
`channel`	The channel used when establishing a connection to the queue manager. This is used only for client connections; that is, when `hostname` is not `NULL`.
`interface_type`	The type of messaging interface to use. Values: `DBMS_MGWADM.MQSERIES_BASE_JAVA_INTERFACE` if the WebSphere MQ Base Java interface should be used. `DBMS_MGWADM.JMS_CONNECTION` if the link is to be used to access JMS destinations in a unified, domain-independent manner. `DBMS_MGWADM.JMS_QUEUE_CONNECTION` if the link is to be used for accessing JMS queues `DBMS_MGWADM.JMS_TOPIC_CONNECTION` if the link is to be used for accessing JMS topics.
`max_connections`	The maximum number of messaging connections to the WebSphere MQ messaging system
`username`	The username used for authentication to the WebSphere MQ messaging system
`password`	The password used for authentication to the WebSphere MQ messaging system
`inbound_log_queue`	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: For `MQSERIES_BASE_JAVA_INTERFACE`, this is the name of a physical WebSphere MQ queue created using WebSphere MQ administration tools. For the `JMS_CONNECTION` interface and the `JMS_QUEUE_CONNECTION` interface, this is the name of a physical WebSphere MQ queue created using WebSphere MQ administration tools. For `JMS_TOPIC_CONNECTION` interface, this specifies the name of a WebSphere MQ JMS topic. The physical WebSphere MQ queue used by subscribers of that topic must be created using WebSphere MQ administration tools. By default, the physical queue used is `SYSTEM.JMS.D.SUBSCRIBER.QUEUE`.
`outbound_log_queue`	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: For `MQSERIES_BASE_JAVA_INTERFACE`, this is the name of a physical WebSphere MQ queue created using WebSphere MQ administration tools. For the `JMS_CONNECTION` interface and the `JMS_QUEUE_CONNECTION` interface, this is the name of a physical WebSphere MQ queue created using WebSphere MQ administration tools. For `JMS_TOPIC_CONNECTION` interface, this specifies the name of a WebSphere MQ JMS topic. The physical WebSphere MQ queue used by subscribers of that topic must be created using WebSphere MQ administration tools. By default, the physical queue used is `SYSTEM.JMS.D.SUBSCRIBER.QUEUE`.

Methods

Table 58-19 SYS.MGW_MQSERIES_PROPERTIES Methods

Method	Description
`construct`	Constructs a new `SYS.MGW_MQSERIES_PROPERTIES` instance. All attributes are assigned a value of `NULL`
`alter_construct`	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`.

SYS.MGW_PROPERTIES Object Type

This type specifies an array of properties.

Syntax

TYPE SYS.MGW_PROPERTIES AS VARRAY (2000) OF SYS.MGW_PROPERTY;

Attributes

Table 58-20 SYS.MGW_PROPERTIES Attributes

Attribute	Description
`name`	Property name
`value`	Property value

Usage Notes

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:

"The DBMS_MGWADM package defines constants to represent the reserved property names on Table 58-4, "DBMS_MGWADM Constants—Named Property Constants"

SYS.MGW_PROPERTY Object Type

This type specifies a named property which is used to specify optional properties for messaging links, foreign queues, and subscribers.

Syntax

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 );

Attributes

Table 58-21 SYS.MGW_PROPERTY Attributes

Attribute	Description
`name`	Property name
`value`	Property value

Methods

Table 58-22 SYS.MGW_PROPERTY Methods

Method	Description
`construct --- (1)`	Constructs a new `MGW_PROPERTY` instance. All attributes are assigned a value of `NULL`
`construct --- (2)`	Constructs a new `MGW_PROPERTY` instance initialized using the given parameters

SYS.MGW_TIBRV_PROPERTIES Object Type

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.

Syntax

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 );

Attributes

Table 58-23 SYS.MGW_TIBRV_PROPERTIES Attributes

Attribute	Description
`service`	The service parameter for the rvd transport
`daemon`	The daemon parameter for the rvd transport
`network`	The network parameter for the rvd transport
`cm_name`	The CM correspondent name. Reserved for future use.
`cm_ledger`	The CM ledger file name. Reserved for future use.

Methods

Table 58-24 SYS.MGW_TIBRV_PROPERTIES Methods

Method	Description
`construct`	Constructs a new `SYS`.`MGW_TIBRV_PROPERTIES` instance. All attributes will be assigned a value of `NULL.`
`alter_construct`	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`.

Summary of DBMS_MGWADM Subprograms

Table 58-25 DBMS_MGWADM Package Subprograms

Subprogram	Description
ADD_SUBSCRIBER Procedure	Adds a subscriber used to consume messages from a source queue for propagation to a destination
ALTER_AGENT Procedure	Alters Messaging Gateway agent parameters
ALTER_MSGSYSTEM_LINK Procedure for TIB/Rendezvous	Alters the properties of a TIB/Rendezvous messaging system link
ALTER_MSGSYSTEM_LINK Procedure for WebSphere MQ	Alters the properties of a WebSphere MQ messaging system link
ALTER_PROPAGATION_SCHEDULE Procedure	Alters a propagation schedule
ALTER_SUBSCRIBER Procedure	Alters the parameters of a subscriber used to consume messages from a source queue for propagation to a destination
CLEANUP_GATEWAY Procedure	Cleans up Messaging Gateway
CREATE_MSGSYSTEM_LINK Procedure for TIB/Rendezvous	Creates a messaging system link to a TIB/Rendezvous messaging system
CREATE_MSGSYSTEM_LINK Procedure for WebSphere MQ	Creates a messaging system link to a WebSphere MQ messaging system
DB_CONNECT_INFO Procedure	Configures connection information used by the Messaging Gateway agent for connections to Oracle Database
DISABLE_PROPAGATION_SCHEDULE Procedure	Disables a propagation schedule
ENABLE_PROPAGATION_SCHEDULE Procedure	Enables a propagation schedule
REGISTER_FOREIGN_QUEUE Procedure	Registers a non-Oracle queue entity in Messaging Gateway
REMOVE_MSGSYSTEM_LINK Procedure	Removes a messaging system link for a non-Oracle messaging system
REMOVE_SUBSCRIBER Procedure	Removes a subscriber used to consume messages from a source queue for propagation to a destination
RESET_SUBSCRIBER Procedure	Resets the propagation error state for a subscriber
SCHEDULE_PROPAGATION Procedure	Schedules message propagation from a source to a destination
SET_LOG_LEVEL Procedure	Dynamically alters the Messaging Gateway agent logging level
SHUTDOWN Procedure	Shuts down the Messaging Gateway agent
STARTUP Procedure	Starts the Messaging Gateway agent
UNREGISTER_FOREIGN_QUEUE Procedure	Removes a non-Oracle queue entity in Messaging Gateway
UNSCHEDULE_PROPAGATION Procedure	Removes a propagation schedule

ADD_SUBSCRIBER Procedure

This procedure adds a subscriber used to consume messages from a source queue for propagation to a destination.

Syntax

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);

Parameters

Table 58-26 ADD_SUBSCRIBER Procedure Parameters

Parameter	Description
`subscriber_id`	Specifies a user-defined name that identifies this subscriber
`propagation_type`	Specifies the type of message propagation. `DBMS_MGWADM.OUTBOUND_PROPAGATION` is for Oracle Streams AQ to non-Oracle propagation. `DBMS_MGWADM.INBOUND_PROPAGATION` is for non-Oracle to Oracle Streams AQ propagation
`queue_name`	Specifies the source queue to which this subscriber is being added. The syntax and interpretation of this parameter depend on the value specified for `propagation_type`.
`destination`	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 `propagation_type`.
`rule`	Specifies an optional subscription rule used by the subscriber to dequeue messages from the source queue. This is `NULL` if no rule is needed. The syntax and interpretation of this parameter depend on the value specified for `propagation_type`.
`transformation`	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 `propagation_type`. If `NULL`, then the Oracle Streams AQ payload type must be supported by Messaging Gateway.
`exception_queue`	Specifies a queue used for exception message logging purposes. This queue must be on the same messaging system as the propagation source. If `NULL,` then an exception queue is not used and propagation stops if a problem occurs. The syntax and interpretation of this parameter depend on the value specified for `propagation_type.` The source queue and exception queue cannot be the same queue.
`options`	Optional subscriber properties. `NULL` if there are none. Typically these are lesser used configuration properties supported by the messaging system.

Usage Notes

See Also:

"Handling Arbitrary Payload Types Using Message Transformations", 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.

See Also:

For additional information regarding subscriber options

OUTBOUND_PROPAGATION Subscribers

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:

The user is responsible for creating the Oracle Streams AQ 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 Streams AQ 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 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:

The exception queue must be a registered non-Oracle queue.
The source and exception queues must use the same messaging system link.

ALTER_AGENT Procedure

This procedure configures Messaging Gateway agent parameters.

Syntax

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);

Parameters

Table 58-27 ALTER_AGENT Procedure Parameters

Parameter	Description
`max_connections`	The maximum number of messaging connections to Oracle Database used by the Messaging Gateway agent. If it is `NULL,` then the current value is unchanged.
`max_memory`	The maximum heap size, in MB, used by the Messaging Gateway agent. If it is `NULL,` then the current value is unchanged.
`max_threads`	The number of messaging threads that the Messaging Gateway agent creates. If it is `NULL`, then the current value is unchanged.

Usage Notes

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.

ALTER_MSGSYSTEM_LINK Procedure for TIB/Rendezvous

Alters the properties of a TIB/Rendezvous messaging system link.

Syntax

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 );

Parameters

Table 58-28 ALTER_MSGSYSTEM_LINK Procedure Parameters for TIB/Rendezvous

Parameters	Description
`linkname`	The messaging system link name
`properties`	Basic properties for a TIB/Rendezvous messaging system link. If `NULL`, then no link properties will be changed.
`options`	Optional link properties. If `NULL`, then no options will be changed. If not `NULL`, then the properties specified in this list are combined with the current options properties to form a new set of link options.
`comment`	A user-specified description, or `NULL` if one is not desired. If `DBMS_MGWADM.NO_CHANGE`, then the current value will not be changed.

Usage Notes

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.

See Also:

SYS.MGW_PROPERTIES Object Type

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" in Oracle Streams Advanced Queuing User's Guide and Reference for more information about the messaging system properties and options

ALTER_MSGSYSTEM_LINK Procedure for WebSphere MQ

This procedure alters the properties of a WebSphere MQ messaging system link.

Syntax

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);

Parameters

Table 58-29 ALTER_MSGSYSTEM_LINK Procedure Parameters for WebSphere MQ

Parameters	Description
`linkname`	The messaging system link name
`properties`	Basic properties for a WebSphere MQ messaging system link. If it is `NULL`, then no link properties are changed.
`options`	Optional link properties. `NULL` if no options are changed. If not `NULL`, then the properties specified in this list are combined with the current options properties to form a new set of link options.
`comment`	An optional description or `NULL` if not desired. If `DBMS_MGWADM.NO_CHANGE` is specified, then the current value is not changed.

Usage Notes

See Also:

SYS.MGW_PROPERTIES Object Type

See Also:

"WebSphere MQ System Properties" in Oracle Streams Advanced Queuing User's Guide and Reference for more information about the messaging system properties and options

ALTER_PROPAGATION_SCHEDULE Procedure

This procedure alters a propagation schedule.

Syntax

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);

Parameters

Table 58-30 ALTER_PROPAGATION_SCHEDULE Procedure Parameters

Parameter	Description
`schedule_id`	Identifies the propagation schedule to be altered
`duration`	Reserved for future use
`next_time`	Reserved for future use
`latency`	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: `NULL` or value > 0. If `latency` is `NULL`, then the Messaging Gateway agent default polling interval will be used. The default polling interval is 5 seconds, but it can be overridden by the Messaging Gateway initialization file.

Usage Notes

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.

ALTER_SUBSCRIBER Procedure

This procedure alters the parameters of a subscriber used to consume messages from a source queue for propagation to a destination.

Syntax

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 );

Parameters

Table 58-31 ALTER_SUBSCRIBER Procedure Parameters

Parameter	Description
`subscriber_id`	Identifies the subscriber to be altered
`rule`	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 `NULL` value indicates that no subscription rule is needed. If `DBMS_MGWADM.NO_CHANGE,` then the current value is unchanged.
`transformation`	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 subscriber propagation type. A `NULL` value indicates that no transformation is needed. If `DBMS_MGWADM.NO_CHANGE,` then the current value is unchanged.
`exception_queue`	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 `NULL` value indicates that no exception queue is used. If `DBMS_MGWADM.NO_CHANGE,` then the current value is unchanged. The source queue and exception queue cannot be the same queue.
`options`	Optional subscriber properties. If `NULL`, then no options will be changed. If not `NULL`, then the properties specified in this list are combined with the current optional properties to form a new set of subscriber options.

Usage Notes

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

See Also:

SYS.MGW_PROPERTIES Object Type for more information on the options parameter
"WebSphere MQ System Properties" in Oracle Streams Advanced Queuing User's Guide and Reference for more information about WebSphere MQ subscriber options
"TIB/Rendezvous System Properties" in Oracle Streams Advanced Queuing User's Guide and Reference for more information about TIB/Rendezvous subscriber options
"OUTBOUND_PROPAGATION Subscribers for outbound propagation parameter interpretation
"INBOUND_PROPAGATION Subscribers for inbound propagation parameter interpretation

CLEANUP_GATEWAY Procedure

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.

Syntax

DBMS_MGWADM.CLEANUP_GATEWAY(
   action  IN BINARY_INTEGER,
   sarg    IN VARCHAR2 DEFAULT NULL);

Parameters

Table 58-32 CLEANUP_GATEWAY Procedure Parameters

Parameter	Description
`action`	The cleanup action to be performed. Values: `DBMS_MGWADM.CLEAN_STARTUP_STATE` for Messaging Gateway start up state recovery. `DBMS_MGWADM.CLEAN_LOG_QUEUES` for log queue cleanup. `DBMS_MGWADM.RESET_SUB_MISSING_LOG_REC` for subscriber recovery due to missing log record. `DBMS_MGWADM.RESET_SUB_MISSING_MESSAGE` for subscriber recovery due to missing message.
`sarg`	Optional argument whose meaning depends on the value specified for `action`. This should be `NULL` if it is not used for the specified action.

Usage Notes

CLEAN_STARTUP_STATE

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 queued 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 a CLEAN_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.

CLEAN_LOG_QUEUES

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

RESET_SUB_MISSING_LOG_REC

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.

RESET_SUB_MISSING_MESSAGE

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.

CREATE_MSGSYSTEM_LINK Procedure for TIB/Rendezvous

Creates a link to a TIB/Rendezvous messaging system.

Syntax

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 );

Parameters

Table 58-33 CREATE_MSGSYSTEM_LINK Procedure Parameters for TIB/Rendezvous

Parameter	Description
`linkname`	A user-defined name to identify this messaging system link
`properties`	Basic properties of a TIB/Rendezvous messaging system link.
`options`	Optional link properties. `NULL` if there are none. These are less frequently used configuration properties supported by the messaging system
`comment`	A user-specified description. `NULL` if one is not desired.

Usage Notes

See Also:

"TIB/Rendezvous System Properties" in Oracle Streams Advanced Queuing User's Guide and Reference for more information about the messaging system properties and options

CREATE_MSGSYSTEM_LINK Procedure for WebSphere MQ

This procedure creates a messaging system link to a WebSphere MQ messaging system.

Syntax

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);

Parameters

Table 58-34 CREATE_MSGSYSTEM_LINK Procedure Parameters for WebSphere MQ

Parameter	Description
`linkname`	A user-defined name to identify the messaging system link
`properties`	Basic properties of a WebSphere MQ messaging system link
`options`	Optional link properties. `NULL` if there are none. These are less frequently used configuration properties supported by the messaging system.
`comment`	A user-specified description. `NULL` if one is not desired

Usage Notes

See Also:

"WebSphere MQ System Properties" in Oracle Streams Advanced Queuing User's Guide and Reference for more information about the messaging system properties and options

DB_CONNECT_INFO Procedure

This procedure configures connection information used by the Messaging Gateway agent for connections to Oracle Database.

Syntax

DBMS_MGWADM.DB_CONNECT_INFO (
   username      IN VARCHAR2,
   password      IN VARCHAR2,
   database      IN VARCHAR2 DEFAULT NULL);

Parameters

Table 58-35 DB_CONNECT_INFO Procedure Parameters

Parameter	Description
`username`	The username used for connections to Oracle Database. `NULL` is not allowed
`password`	The password used for connections to Oracle Database. `NULL` is not allowed
`database`	The database connect string used by the Messaging Gateway agent. `NULL` indicates that a local connection should be used. Oracle strongly recommends that a not `NULL` value be specified. Usually it will be a net service name from `tnsnames.ora`.

Usage Notes

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.

DISABLE_PROPAGATION_SCHEDULE Procedure

This procedure disables a propagation schedule.

Syntax

DBMS_MGWADM.DISABLE_PROPAGATION_SCHEDULE (
   schedule_id  IN VARCHAR2 );

Parameters

Table 58-36 DISABLE_PROPAGATION_SCHEDULE Procedure Parameters

Parameter	Description
`schedule_id`	Identifies the propagation schedule to be disabled

ENABLE_PROPAGATION_SCHEDULE Procedure

This procedure enables a propagation schedule.

Syntax

DBMS_MGWADM.ENABLE_PROPAGATION_SCHEDULE (
   schedule_id  IN VARCHAR2 );

Parameters

Table 58-37 ENABLE_PROPAGATION_SCHEDULE Procedure Parameters

Parameter	Description
`schedule_id`	Identifies the propagation schedule to be enabled

REGISTER_FOREIGN_QUEUE Procedure

This procedure registers a non-Oracle queue entity in Messaging Gateway.

Syntax

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);

Parameters

Table 58-38 REGISTER_FOREIGN_QUEUE Procedure Parameters

Parameters	Description
`name`	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.
`linkname`	The link name for the messaging system on which this queue exists
`provider_queue`	The message provider (native) queue name. If `NULL,` then the value provided for the `name` parameter is used as the provider queue name.
`domain`	The domain type of the queue. `NULL` means the domain type is automatically determined based on the messaging system of the queue. `DBMS_MGWADM.DOMAIN_QUEUE` is for a queue (point-to-point model). `DBMS_MGWADM.DOMAIN_TOPIC` is for a topic (publish-subscribe model)
`options`	Optional queue properties
`comment`	A user-specified description. Can be `NULL`.

Usage Notes

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 Streams Advanced Queuing User's Guide and Reference.

REMOVE_MSGSYSTEM_LINK Procedure

This procedure removes a messaging system link for a non-Oracle messaging system.

Syntax

DBMS_MGWADM.REMOVE_MSGSYSTEM_LINK(
   linkname  IN VARCHAR2);

Parameters

Table 58-39 REMOVE_MSGSYSTEM_LINK Procedure Parameters

Parameters	Description
`linkname`	The messaging system link name

Usage Notes

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.

REMOVE_SUBSCRIBER Procedure

This procedure removes a subscriber used to consume messages from a source queue for propagation to a destination.

Syntax

DBMS_MGWADM.REMOVE_SUBSCRIBER (
   subscriber_id  IN VARCHAR2,
   force          IN BINARY_INTEGER DEFAULT DBMS_MGWADM.NO_FORCE );

Parameters

Table 58-40 REMOVE_SUBSCRIBER Procedure Parameters

Parameter Description

subscriber_id Identifies the subscriber to be removed

force

Specifies whether this procedure should succeed even if Messaging Gateway is not able to perform all cleanup actions pertaining to this subscriber. DBMS_MGWADM.NO_FORCE (0) means the subscriber is not removed if Messaging Gateway is unable to clean up successfully. DBMS_MGWADM.FORCE (1) means the subscriber is removed, even though all cleanup actions may not be done.

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.

Usage Notes

For outbound propagation, a local subscriber is removed from the Oracle Streams AQ queue.

RESET_SUBSCRIBER Procedure

This procedure resets the propagation error state for a subscriber.

Syntax

DBMS_MGWADM.RESET_SUBSCRIBER (
   subscriber_id  IN VARCHAR2 );

Parameters

Table 58-41 RESET_SUBSCRIBER Procedure Parameters

Parameter	Description
`subscriber_id`	Identifies the subscriber

SCHEDULE_PROPAGATION Procedure

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.

Syntax

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);

Parameters

Table 58-42 SCHEDULE_PROPAGATION Procedure Parameters

Parameter	Description
`schedule_id`	Specifies a user-defined name that identifies the schedule
`propagation_type`	Specifies the type of message propagation. `DBMS_MGWADM.OUTBOUND_PROPAGATION` is for Oracle Streams AQ to non-Oracle propagation. `DBMS_MGWADM.INBOUND_PROPAGATION` is for non-Oracle to Oracle Streams AQ propagation.
`source`	Specifies the source queue whose messages are to be propagated. The syntax and interpretation of this parameter depend on the value specified for `propagation_type`.
`destination`	Specifies the destination queue to which messages are propagated. The syntax and interpretation of this parameter depend on the value specified for `propagation_type`.
`start_time`	Reserved for future use
`duration`	Reserved for future use
`next_time`	Reserved for future use
`latency`	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: `NULL` or value > 0. If `latency` is `NULL`, then the Messaging Gateway agent default polling interval will be used. The default polling interval is 5 seconds but it can be overridden by the Messaging Gateway initialization file.

Usage Notes

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.

SET_LOG_LEVEL Procedure

This procedure dynamically alters the Messaging Gateway agent logging level. The Messaging Gateway agent must be running.

Syntax

DBMS_MGWADM.SET_LOG_LEVEL (
   log_level  IN BINARY_INTEGER);

Parameters

Table 58-43 SET_LOG_LEVEL Procedure Parameters

Parameter	Description
`log_level`	Level at which the Messaging Gateway agent logs information. `DBMS_MGWADM.BASIC_LOGGING` generates the least information while `DBMS_MGWADM.TRACE_DEBUG_LOGGING` generates the most information.

See Also:

Table 58-3, "DBMS_MGWADM Constants—Logging Levels" for details on the log_level parameter

SHUTDOWN Procedure

This procedure shuts down the Messaging Gateway agent. No propagation activity occurs until Messaging Gateway is restarted.

Syntax

DBMS_MGWADM.SHUTDOWN (
   sdmode  IN BINARY_INTEGER DEFAULT DBMS_MGWADM.SHUTDOWN_NORMAL);

Parameters

Table 58-44 SHUTDOWN Procedure Parameters

Parameter	Description
`sdmode`	The shutdown mode. The only value currently supported is `DBMS_MGWADM.SHUTDOWN_NORMAL` for normal shutdown. The Messaging Gateway agent may attempt to complete any propagation work currently in progress.

STARTUP Procedure

This procedure starts the Messaging Gateway agent. It must be called before any propagation activity can take place.

Syntax

DBMS_MGWADM.STARTUP(
   instance  IN  BINARY_INTEGER DEFAULT 0,
   force     IN  BINARY_INTEGER DEFAULT DBMS_MGWADM.NO_FORCE);

Parameters

Table 58-45 STARTUP Procedure Parameters

Parameter	Description
`instance`	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.
`force`	If this is `DBMS_MGWADM.FORCE`, then any positive integer is acceptable as the job instance. If this is `DBMS_MGWADM.NO_FORCE` (the default), then the specified instance must be running; otherwise the routine raises an exception.

Usage Notes

The Messaging Gateway agent cannot be started until an agent user has been configured using DBMS_MGWADM.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.

UNREGISTER_FOREIGN_QUEUE Procedure

This procedure removes a non-Oracle queue entity in Messaging Gateway.

Syntax

DBMS_MGWADM.UNREGISTER_FOREIGN_QUEUE(
   name         IN VARCHAR2,
   linkname     IN VARCHAR2);

Parameters

Table 58-46 UNREGISTER_FOREIGN_QUEUE Procedure Parameters

Parameter	Description
`name`	The queue name
`linkname`	The link name for the messaging system on which the queue exists

Usage Notes

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.

UNSCHEDULE_PROPAGATION Procedure

This procedure removes a propagation schedule.

Syntax

DBMS_MGWADM.UNSCHEDULE_PROPAGATION (
   schedule_id   IN VARCHAR2 );

Parameters

Table 58-47 UNSCHEDULE_PROPAGATION Procedure Parameters

Parameter	Description
`schedule_id`	Identifies the propagation schedule to be removed