Skip Headers

PL/SQL Packages and Types Reference
10g Release 1 (10.1)

Part Number B10802-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

51
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

Table 51-1  DBMS_MGWADM Constants--Propagation Types
Name Type Description

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.

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.

Table 51-2  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 51-3  DBMS_MGWADM Constants--Force Values
Name Type Description

NO_FORCE

CONSTANT BINARY_INTEGER

Represents a normal, nonforced action

FORCE

CONSTANT BINARY_INTEGER

Represents a forced action

Table 51-4  DBMS_MGWADM Constants--Shutdown Modes
Name Type Description

SHUTDOWN_NORMAL

CONSTANT BINARY_INTEGER

Represents the normal shutdown mode

SHUTDOWN_IMMEDIATE

CONSTANT BINARY_INTEGER

Represents the immediate shutdown mode

Table 51-5  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 51-6  DBMS_MGWADM Constants--Logging Levels
Name Type Description

BASIC_LOGGING

CONSTANT BINARY_INTEGER

Represents the detail of logging information written to the log file. The logging level ranges from BASIC_LOGGING for standard (the least) information to TRACE_DEBUG_LOGGING for the greatest information.

TRACE_LITE_LOGGING

CONSTANT BINARY_INTEGER

TRACE_HIGH_LOGGING

CONSTANT BINARY_INTEGER

TRACE_DEBUG_LOGGING

CONSTANT BINARY_INTEGER

Table 51-7  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

Table 51-8  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 51-9  DBMS_MGWADM Constants--Other Constants
Name Type Description

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.

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.


Types

SYS.MGW_PROPERTY Type

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

Syntax
TYPE SYS.MGW_PROPERTY IS OBJECT(
   name  VARCHAR2(100),
   value VARCHAR2(1000),

-- Methods  
STATIC FUNCTION CONSTRUCT
RETURN SYS.MGW_PROPERTY,
  
STATIC FUNCTION CONSTRUCT(
   p_name   IN VARCHAR2,
   p_value  IN VARCHAR2)
RETURN SYS.MGW_PROPERTY );

Attributes
Table 51-10  SYS.MGW_PROPERTY Attributes
Attribute Description

name

Property name

value

Property value

CONSTRUCT Method

This method constructs a new MGW_PROPERTY instance. All attributes are assigned a value of NULL.

Syntax

STATIC FUNCTION CONSTRUCT
RETURN SYS.MGW_PROPERTY;

CONSTRUCT Method, Initialized With Given Parameters

This method constructs a new MGW_PROPERTY instance initialized using the given parameters.

Syntax

STATIC FUNCTION CONSTRUCT(
   p_name   IN VARCHAR2,
   p_value  IN VARCHAR2)
RETURN SYS.MGW_PROPERTY;

Parameters

Table 51-11  SYS.MGW_PROPERTY.CONSTRUCT Initialization Parameters
Parameter Description

p_name

Property name

p_value

Property value

SYS.MGW_PROPERTIES Type

This type specifies an array of properties.

Syntax

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

Usage Notes

Unless noted otherwise, Messaging Gateway uses named properties as follows:

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:

The DBMS_MGWADM package defines constants to represent the reserved property names. See "WebSphere MQ System Properties" for more information.

SYS.MGW_MQSERIES_PROPERTIES 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 51-12  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_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 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 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.

CONSTRUCT Method

This method constructs a new SYS.MGW_MQSERIES_PROPERTIES instance. All attributes are assigned a value of NULL.

Syntax

STATIC FUNCTION CONSTRUCT
RETURN SYS.MGW_MQSERIES_PROPERTIES;

ALTER_CONSTRUCT Method

This method constructs a new SYS.MGW_MQSERIES_PROPERTIES instance for altering the properties of an existing messaging link. All attributes having a VARCHAR2 data type are assigned a value of DBMS_MGWADM.NO_CHANGE. Attributes of other data types are assigned a value of NULL.

Syntax

STATIC FUNCTION ALTER_CONSTRUCT
RETURN SYS.MGW_MQSERIES_PROPERTIES;

SYS.MGW_TIBRV_PROPERTIES 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 51-13  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.

CONSTRUCT Function

Constructs a new SYS.MGW_TIBRV_PROPERTIES instance. All attributes will be assigned a value of NULL.

Syntax

STATIC FUNCTION construct 
RETURN SYS.MGW_TIBRV_PROPERTIES;

ALTER_CONSTRUCT Function

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.

Syntax

STATIC FUNCTION alter_construct 
RETURN SYS.MGW_TIBRV_PROPERTIES;

Properties

WebSphere MQ System Properties

This section summarizes basic and optional properties of WebSphere MQ related to Messaging Gateway links, foreign queues, and subscribers.

See Also:

Your WebSphere MQ (MQSeries) documentation for more information

Table 51-14 summarizes the basic configuration properties for a WebSphere MQ messaging link. The table indicates which properties of SYS.MGW_MQSERIES_PROPERTIES are optional (NULL allowed), which can be altered, and if alterable, which values can be dynamically changed.

See Also:

"SYS.MGW_MQSERIES_PROPERTIES Type"

Table 51-14  WebSphere MQ Link Properties
Attribute NULL Allowed? Alter Value? Dynamic?

queue_manager

no

no

no

hostname

yes (1)

no

no

port

yes (1)

no

no

channel

yes (1)

no

no

interface_type

yes (2)

no

no

max_connections

yes (3)

yes

yes

username

yes

yes

yes

password

yes

yes

yes

inbound_log_queue

yes (4)

yes(4)

yes

outbound_log_queue

yes (5)

yes(5)

yes

Notes on Table 51-14
  1. If hostname is NULL, then the port and channel must be NULL. If the hostname is not NULL, then the port and channel must be not NULL. If the hostname is NULL, then a WebSphere MQ bindings connection is used; otherwise a client connection is used.
  2. If interface_type is NULL, then a default value of DBMS_MGWADM.MQSERIES_BASE_JAVA_INTERFACE is used.
  3. If max_connections is NULL, then a default value of 1 is used.
  4. Attribute inbound_log_queue can be NULL if the link is not used for inbound propagation. The log queue can be altered only when no inbound propagation subscriber references the link.
  5. Attribute outbound_log_queue can be NULL if the link is not used for outbound propagation. The log queue can be altered only when no outbound propagation subscriber references the link.

Table 51-15 summarizes the optional configuration properties supported when a WebSphere MQ Base Java interface is used to access the WebSphere MQ messaging system. Table 51-16 summarizes the optional configuration properties supported when a WebSphere MQ JMS interface is used. Each table lists the property name, where that property applies, whether the property can be altered, and if alterable, whether the value can be dynamically changed. Only the properties listed in the tables are supported, and any extra properties will be ignored.

See Also:

For more information on optional configuration properties:

Table 51-15  Optional Configuration Properties for WebSphere MQ Base Java
Property Name Used For Alter Value? Dynamic?

MQ_ccsid

link

yes

no

MQ_ReceiveExit

link

yes

no

MQ_SendExit

link

yes

no

MQ_SecurityExit

link

yes

no

MQ_openOptions

foreign queue

no

no

MsgBatchSize

subscriber

yes

yes

Table 51-16  Optional Configuration Properties for WebSphere MQ JMS  
Property Name Used For Alter Value? Dynamic?

MQ_ccsid

link

yes

no

MQ_ReceiveExit

link

yes

no

MQ_SendExit

link

yes

no

MQ_SecurityExit

link

yes

no

MQ_ReceiveExitInit

link

yes

no

MQ_SendExitInit

link

yes

no

MQ_SecurityExitInit

link

yes

no

MQ_BrokerControlQueue

link

yes

no

MQ_BrokerPubQueue

link

yes

no

MQ_BrokerQueueManager

link

yes

no

MQ_BrokerVersion

link

yes

no

MQ_PubAckInterval

link

yes

no

MQ_JmsDurSubQueue

link

no

no

MQ_JmsTargetClient

foreign queue

no

no

MQ_JmsDurSubQueue

foreign queue

no

no

MsgBatchSize

subscriber

yes

yes

JMS_NoLocal

subscriber

no

no

JMS_DeliveryMode

subscriber

yes

yes

TIB/Rendezvous System Properties

This section summarizes basic and optional configuration properties of TIB/Rendezvous related to Messaging Gateway links, foreign queues and subscribers.

See Also:

Your TIB/Rendezvous documentation for more information

Table 51-17 summarizes the basic configuration properties for a TIB/Rendezvous messaging link. It indicates which properties of SYS.MGW_TIBRV_PROPERTIES are optional (NULL allowed), which can be altered, and if alterable, which values can be dynamically changed.

See Also:

"SYS.MGW_TIBRV_PROPERTIES Type"

Table 51-17  TIB/Rendezvous Link Properties
Attribute NULL allowed? Alter value? Dynamic?

service

yes(1)

no

no

daemon

yes(1)

no

no

network

yes(1)

no

no

cm_name

yes(2)

no

no

cm_ledger

yes(2)

no

no

Notes on Table 51-17:
  1. System default values will be used if service, daemon, or network are NULL.
  2. The cm_name and cm_ledger attributes are reserved for future use when TIB/Rendezvous certified messages are supported. At present, a NULL must be specified for these parameters when a TIB/Rendezvous link is configured.

Table 51-18 summarizes the optional configuration properties supported when a TIB/Rendezvous messaging system is used. The table lists the property name, where that property applies, whether the property can be altered, and if alterable, whether the value can be dynamically changed. Only the properties listed in the table are supported, and any extra properties will be ignored.

Table 51-18  Optional Properties for TIB/Rendezvous
Property Name Used For Alter Value? Dynamic?

RV_discardAmount

subscriber

yes

no

RV_limitPolicy

subscriber

yes

no

RV_maxEvents

subscriber

yes

no

AQ_MsgProperties

subscriber

yes

yes

MsgBatchSize

subscriber

yes

yes

See Also:

For more information on optional configuration properties:

Registering a TIB/Rendezvous subject

DBMS_MGWADM.register_foreign_queue procedure is used to register a TIB/Rendezvous subject with the Messaging Gateway. The provider_queue parameter specifies a TIB/Rendezvous subject name. Wildcards are allowed in the subject name.

Optional Link Configuration Properties

This section describes optional link properties you can specify using the options parameter of DBMS_MGWADM.create_msgsystem_link and DBMS_MGWADM.alter_msgsystem_link. Each listing also indicates which messaging system might use that property.

MQ_BrokerControlQueue

Used by: WebSphere MQ JMS.

This property specifies the name of the broker control queue. It corresponds to WebSphere MQ JMS administration tool property BROKERCONQ. The default used by WebSphere MQ is SYSTEM.BROKER.CONTROL.QUEUE.

MQ_BrokerPubQueue

Used by: WebSphere MQ JMS

This property specifies the name of the broker publish queue. It corresponds to WebSphere MQ JMS administration tool property BROKERPUBQ. The default used by WebSphere MQ is SYSTEM.BROKER.DEFAULT.STREAM.

MQ_BrokerQueueManager

Used by: WebSphere MQ JMS

This property specifies the name of the broker queue manager. It corresponds to WebSphere MQ administration tool property BROKERQMGR. If not set, then no default will be used.

MQ_BrokerVersion

Used by: WebSphere MQ JMS

This property specifies the broker version number. It corresponds to WebSphere MQ JMS administration tool property BROKERVER. The default used by WebSphere MQ is 0.

MQ_ccsid

Used by: WebSphere MQ Base Java and WebSphere MQ JMS

This property specifies the character set identifier to be used. This should be the integer value of the character set (for example, 819) rather than a descriptive string. If it is not set, then the WebSphere MQ default character set 819 is used.

MQ_JmsDurSubQueue

Used by: WebSphere MQ JMS

This property applies to WebSphere MQ JMS topic links only. The SYS.MGW_MQSERIES_PROPERITES attributes, inbound_log_queue and outbound_log_queue, specify the names of WebSphere MQ JMS topics used for propagation logging. This property specifies the name of the WebSphere MQ queue from which durable subscription messages are retrieved by the log topic subscribers. The default queue used by WebSphere MQ is SYSTEM.JMS.D.SUBSCRIBER.QUEUE.

MQ_PubAckInterval

Used by: WebSphere MQ JMS

This property specifies the interval, in number of messages, between publish requests that require acknowledgment from the broker. It corresponds to WebSphere MQ JMS administration tool property PUBACKINT. The default used by WebSphere MQ is 25.

MQ_ReceiveExit

Used by: WebSphere MQ Base Java and WebSphere MQ JMS

This property specifies the fully qualified Java classname of a class implementing the MQReceiveExit interface. This class must be in the CLASSPATH of the Messaging Gateway agent. There is no default.

MQ_ReceiveExitInit

Used by: WebSphere MQ JMS

Initialization string that is passed by WebSphere MQ JMS to the constructor of the class specified by MQ_ReceiveExit. Corresponds to WebSphere MQ JMS administration tool property RECEXITINIT. There is no default.

MQ_SecurityExit

Used by: WebSphere MQ Base Java and WebSphere MQ JMS

This property specifies the fully qualified Java classname of a class implementing the MQSecurityExit interface. This class must be in the CLASSPATH of the Messaging Gateway agent. There is no default.

MQ_SecurityExitInit

Used by: WebSphere MQ JMS

Initialization string that is passed by WebSphere MQ JMS to the constructor of the class specified by MQ_SecurityExit. It corresponds to WebSphere MQ JMS administration tool property SECEXITINIT. There is no default.

MQ_SendExit

Used by: WebSphere MQ Base Java and WebSphere MQ JMS

This property specifies the fully qualified Java classname of a class implementing the MQSendExit interface. This class must be in the CLASSPATH of the Messaging Gateway agent. There is no default.

MQ_SendExitInit

Used by: WebSphere MQ JMS

Initialization string that is passed by WebSphere MQ JMS to the constructor of the class specified by MQ_SendExit. It corresponds to WebSphere MQ JMS administration tool property SENDEXITINIT. There is no default.

Optional Foreign Queue Configuration Properties

This section describes optional foreign queue properties that you can specify using the options parameter of DBMS_MGWADM.register_foreign_queue. Each listing also indicates which messaging system might use that property.

MQ_JmsDurSubQueue

Used by: WebSphere MQ JMS

A string representing the name of the WebSphere MQ queue from which durable subscription messages are retrieved by subscribers on this topic. It applies only to WebSphere MQ JMS topics. The default queue used by WebSphere MQ is SYSTEM.JMS.D.SUBSCRIBER.QUEUE.

MQ_JmsTargetClient

Used by: WebSphere MQ JMS

Supported values are TRUE and FALSE. This property is only used for outbound propagation to a JMS queue or topic. TRUE indicates that WebSphere MQ should store the message as a JMS message. FALSE indicates that WebSphere MQ should store the message in non-JMS format so that non-JMS applications can access it. Default is TRUE.

MQ_openOptions

Used by: WebSphere MQ Base Java

This property specifies the value used for the openOptions argument of the WebSphere MQ Base Java MQQueueManager.accessQueue method. No value is required. But if one is given, then the Messaging Gateway agent adds MQOO_OUTPUT to the specified value for an enqueue (put) operation. MQOO_INPUT_SHARED is added for a dequeue (get) operation. The default is MQOO_OUTPUT for an enqueue/put operation; MQOO_INPUT_SHARED for a dequeue/get operation.

Optional Subscriber Configuration Properties

This section describes optional subscriber properties that you can specify using the options parameter of DBMS_MGWADM.add_subscriber and DBMS_MGWADM.alter_subscriber. Each listing also indicates which messaging system might use that property

AQ_MsgProperties

Used by: TIB/Rendezvous

This property specifies how Oracle Streams AQ message properties will be used during message propagation. Supported values are TRUE and FALSE. The default value is FALSE.

For an outbound propagation subscriber, if the value is TRUE (case insensitive), then the Messaging Gateway agent will add a field for most Oracle Streams AQ message properties to the message propagated to the TIB/Rendezvous subject.

For an inbound propagation subscriber, if the value is TRUE (case insensitive), then the Messaging Gateway agent will search the source message for a field with a reserved name, and if it exists, use its value to set the corresponding Oracle Streams AQ message property. A default value will be used if the field does not exist or does not have an expected datatype.

See Also:

Oracle Streams Advanced Queuing User's Guide and Reference for the message conversion details

JMS_DeliveryMode

Used by: WebSphere MQ JMS and Oracle JMS.

You can use this property when the propagation destination is a JMS messaging system. It sets the delivery mode of messages enqueued to the propagation destination queue by a JMS MessageProducer. Supported values are PERSISTENT, NON_PERSISTENT and PRESERVE_MSG. The default is PRESERVE_MSG.

JMS_NoLocal

Used by: WebSphere MQ JMS and Oracle JMS

You can use this property when the propagation source is a JMS messaging system. It sets the noLocal parameter of a JMS TopicSubscriber. Supported values are TRUE and FALSE. The default is FALSE.

MsgBatchSize

Used by: any

This property specifies the maximum number of messages, if available, to be propagated in one transaction. The default is 30.

RV_discardAmount

Used by: TIB/Rendezvous

This property specifies the discard amount of a queue. It is meaningful only for an inbound propagation subscriber. The default is 0.

RV_limitPolicy

Used by: TIB/Rendezvous

This property specifies the limit policy for resolving overflow of a queue limit. It is meaningful only for an inbound propagation subscriber. Supported values are DISCARD_NONE, DISCARD_FIRST, DISCARD_LAST and DISCARD_NEW. The default is DISCARD_NONE.

RV_maxEvents

Used by: TIB/Rendezvous

This property specifies the maximum event limit of a queue. It is meaningful only for an inbound propagation subscriber. The default is 0.


Database Views

The views listed in Table 51-19 provide Messaging Gateway configuration, status, and statistical information. Unless otherwise indicated, the SELECT privilege is granted to MGW_ADMINISTRATOR_ROLE so that only Messaging Gateway administrators have access to the views. All views are owned by SYS.

Table 51-19  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 51-20.

Table 51-20  MGW_GATEWAY View Properties
Name Type Description

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_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_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_USER

VARCHAR2

Database username used by the Messaging Gateway agent to connect to the database

AGENT_DATABASE

VARCHAR2

The database connect string used by the Messaging Gateway agent. NULL indicates that a local connection is used.

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_TIME

VARCHAR2

Time of last Messaging Gateway agent error

LAST_ERROR_MSG

VARCHAR2

Message for 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

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

MGW_LINKS View

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

Table 51-21  MGW_LINKS View Properties
Name Type Description

LINK_NAME

VARCHAR2

Name of the messaging system link

LINK_TYPE

VARCHAR2

Type of messaging system link. MQSERIES is for WebSphere MQ links. TIBRV is for TIB/Rendezvous links.

LINK_COMMENT

VARCHAR2

User comment for the link

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 51-22 lists the MGW_MQSERIES_LINKS view properties.

Table 51-22  MGW_MQSERIES_LINKS View Properties
Name Type Description

LINK_NAME

VARCHAR2

Name of the messaging system link

QUEUE_MANAGER

VARCHAR2

Name of the WebSphere MQ queue manager

HOSTNAME

VARCHAR2

Name of the WebSphere MQ host

PORT

NUMBER

Port number

CHANNEL

VARCHAR2

Connection channel

INTERFACE_TYPE

VARCHAR2

Messaging interface type. BASE_JAVA is for WebSphere MQ Base Java interface. JMS_QUEUE_CONNECTION is for WebSphere MQ JMS queue connections. JMS_TOPIC_CONNECTION is for WebSphere MQ JMS topic connections.

MAX_CONNECTIONS

NUMBER

Maximum number of messaging connections

INBOUND_LOG_QUEUE

VARCHAR2

Inbound propagation log queue

OUTBOUND_LOG_QUEUE

VARCHAR2

Outbound propagation log queue

OPTIONS

SYS.MGW_PROPERTIES

Link options

LINK_COMMENT

VARCHAR2

User comment for the link

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 51-23 lists the MGW_TIBRV_LINKS view properties.

Table 51-23  MGW_TIBRV_LINKS View Properties
Property Name Type Description

LINK_NAME

VARCHAR2

Name of the messaging system link

SERVICE

VARCHAR2

TIB/Rendezvous service parameter for rvd transport

DAEMON

VARCHAR2

TIB/Rendezvous daemon parameter for rvd transport

NETWORK

VARCHAR2

TIB/Rendezvous network parameter for rvd transport

CM_NAME

VARCHAR2

TIB/Rendezvous CM correspondent name

CM_LEDGER

VARCHAR2

TIB/Rendezvous CM ledger file name

OPTIONS

SYS.MGW_PROPERTIES

Link options

LINK_COMMENT

VARCHAR2

User comment for the link

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 51-24 lists the MGW_FOREIGN_QUEUES view properties.

Table 51-24  MGW_FOREIGN_QUEUES View Properties
Name Type Description

NAME

VARCHAR2

Name of the registered queue

LINK_NAME

VARCHAR2

Name of the messaging system link

PROVIDER_QUEUE

VARCHAR2

Message provider (native) queue name

DOMAIN

VARCHAR2

Queue domain type. 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.

OPTIONS

SYS.MGW_PROPERTIES

Optional queue properties

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 51-25 lists the MGW_SUBSCRIBERS view properties.

Table 51-25  MGW_SUBSCRIBERS View Properties
Name Type Description

SUBSCRIBER_ID

VARCHAR2

Propagation subscriber identifier

PROPAGATION_TYPE

VARCHAR2

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

DESTINATION

VARCHAR2

Destination queue to which messages are propagated

RULE

VARCHAR2

Subscription rule

TRANSFORMATION

VARCHAR2

Transformation used for message conversion

EXCEPTION_QUEUE

VARCHAR2

Exception queue used for logging purposes

STATUS

VARCHAR2

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

FAILURES

NUMBER

Number of propagation failures

LAST_ERROR_DATE

DATE

Date of last propagation error

LAST_ERROR_TIME

VARCHAR2

Time of last propagation error

LAST_ERROR_MSG

VARCHAR2

Message for last propagation error

PROPAGATED_MSGS

NUMBER

Number of messages propagated to the destination queue since the last time the agent was started

EXCEPTIONQ_MSGS

NUMBER

Number of messages moved to the propagation exception queue since the last time the agent was started

PROP_STYLE

VARCHAR2

Message propagation style. NATIVE is for native message propagation. JMS is for JMS message propagation.

OPTIONS

SYS.MGW_PROPERTIES

Subscriber options

MGW_SCHEDULES View

Table 51-26  MGW_SCHEDULES View Properties
Name Type Description

SCHEDULE_ID

VARCHAR2

Propagation schedule identifier

PROPAGATION_TYPE

VARCHAR2

Propagation type. OUTBOUND is for Oracle Streams AQ to non-Oracle propagation. INBOUND is for non-Oracle to Oracle Streams AQ propagation.

SOURCE

VARCHAR2

Propagation source

DESTINATION

VARCHAR2

Propagation destination

START_DATE

DATE

Reserved for future use

START_TIME

VARCHAR2

Reserved for future use

PROPAGATION_WINDOW

NUMBER

Reserved for future use

NEXT_TIME

VARCHAR2

Reserved for future use

LATENCY

NUMBER

Propagation window latency (in seconds)

SCHEDULE_DISABLED

VARCHAR2

Indicates whether the schedule is disabled. Y means the schedule is disabled. N means the schedule is enabled.


Summary of DBMS_MGWADM Subprograms

Table 51-27  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

SET_LOG_LEVEL Procedure

Dynamically alters the Messaging Gateway agent logging level

SCHEDULE_PROPAGATION Procedure

Schedules message propagation from a source to a destination

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 51-28  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:

"Messaging Gateway Message Transformation", in Oracle Streams Advanced Queuing User's Guide and Reference for more information regarding message conversion and transformation

If the non-Oracle messaging link being accessed for the subscriber uses a JMS interface, then the Messaging Gateway agent will use the Oracle JMS interface to access the Oracle Streams AQ queues. Otherwise the native Oracle Streams AQ interface will be used. Parameters are interpreted differently when the Messaging Gateway agent uses Oracle JMS for JMS connections.

Transformations are not currently supported if the Oracle JMS interface is used for propagation. The transformation parameter must be NULL.

See Also:

For additional information regarding subscriber options

OUTBOUND_PROPAGATION Subscribers

The parameters for a subscriber used for outbound propagation are interpreted as follows:

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:

INBOUND_PROPAGATION Subscribers

The parameters for a subscriber used for inbound propagation are interpreted as follows:

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:


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 51-29  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 51-30  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 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" 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 51-31  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

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

"WebSphere MQ System Properties" 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 51-32  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 51-33  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

If the non-Oracle messaging link being accessed for the subscriber uses a JMS interface, then the Messaging Gateway agent will use the Oracle JMS interface to access the Oracle Streams AQ queues. Otherwise the native Oracle Streams AQ interface will be used. Parameters are interpreted differently when the Messaging Gateway agent uses Oracle JMS for JMS connections.

When propagating from a JMS source, the subscriber rule cannot be altered. Instead, the subscriber must be removed and added with the new rule. For JMS, changing the message selector on a durable subscription is equivalent to deleting and re-creating the subscription.

Transformations are not currently supported if the Oracle JMS interface is used for propagation. The transformation parameter must be DBMS_MGWADM.NO_CHANGE (the default value).

The options parameter specifies a set of properties used to alter the current optional properties. Each property affects the current property list in a particular manner: add a new property, replace an existing property, remove an existing property, or remove all properties.

See Also:

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 51-34  CLEANUP_GATEWAY Procedure Parameters
Parameter Description

action

The cleanup action to be performed. Values:

  • CLEAN_STARTUP_STATE for Messaging Gateway start up state recovery.
  • CLEAN_LOG_QUEUES for log queue cleanup.
  • RESET_SUB_MISSING_LOG_REC for subscriber recovery due to missing log record.
  • 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:

Execution of this command fails if:

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 51-35  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" 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 51-36  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" 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 51-37  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 51-38  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 51-39  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 51-40  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. DOMAIN_QUEUE is for a queue (point-to-point model). 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:

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 51-41  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 51-42  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. NO_FORCE (0) means the subscriber is not removed if Messaging Gateway is unable to clean up successfully. 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 51-43  RESET_SUBSCRIBER Procedure Parameters
Parameter Description

subscriber_id

Identifies the subscriber


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 51-44  SET_LOG_LEVEL Procedure Parameters
Parameter Description

log_level

Level at which the Messaging Gateway agent logs information. BASIC_LOGGING generates the least information while TRACE_DEBUG_LOGGING generates the most information.

See Also:

Table 51-6, " DBMS_MGWADM Constants--Logging Levels" for details on the log_level parameter


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 51-45  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:

For inbound propagation, parameters are interpreted as follows:

The schedule is set to an enabled state when it is created.


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 51-46  SHUTDOWN Procedure Parameters
Parameter Description

sdmode

The shutdown mode. The only value currently supported is 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 51-47  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 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 51-48  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 51-49  UNSCHEDULE_PROPAGATION Procedure Parameters
Parameter Description

schedule_id

Identifies the propagation schedule to be removed