DBMS_MGWADM, 5 of 6

Summary of DBMS_MGWADM Subprograms

Table 31-15 DBMS_MGWADM Subprograms

Subprogram	Description
ALTER_AGENT Procedure	Alters Messaging Gateway agent parameters
DB_CONNECT_INFO Procedure	Configures connection information used by the Messaging Gateway agent for connections to the Oracle database
STARTUP Procedure	Starts the Messaging Gateway agent
SHUTDOWN Procedure	Shuts down the Messaging Gateway agent
CLEANUP_GATEWAY Procedure	Cleans up Messaging Gateway
SET_LOG_LEVEL Procedure	Dynamically alters the Messaging Gateway agent logging level
CREATE_MSGSYSTEM_LINK Procedure	Creates a messaging system link to an MQSeries messaging system
ALTER_MSGSYSTEM_LINK Procedure	Alters the properties of an MQSeries messaging system link
REMOVE_MSGSYSTEM_LINK Procedure	Removes a messaging system link for a non-Oracle messaging system
REGISTER_FOREIGN_QUEUE Procedure	Registers a non-Oracle queue entity in Messaging Gateway
UNREGISTER_FOREIGN_QUEUE Procedure	Removes a non-Oracle queue entity in Messaging Gateway
ADD_SUBSCRIBER Procedure	Adds a subscriber used to consume messages from a source queue for propagation to a destination
ALTER_SUBSCRIBER Procedure	Alters the parameters of a subscriber used to consume messages from a source queue for propagation to a destination
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
UNSCHEDULE_PROPAGATION Procedure	Removes a propagation schedule
ALTER_PROPAGATION_SCHEDULE Procedure	Alters a propagation schedule
ENABLE_PROPAGATION_SCHEDULE Procedure	Enables a propagation schedule
DISABLE_PROPAGATION_SCHEDULE Procedure	Disables a propagation schedule

ALTER_AGENT Procedure

This procedure alters Messaging Gateway agent parameters.

Syntax

DBMS_MGWADM.ALTER_AGENT (
   max_connections  IN BINARY_INTEGER  DEFAULT NULL,
   max_memory       IN BINARY_INTEGER  DEFAULT NULL);

Parameters

Table 31-16 ALTER_AGENT Procedure Parameters

Parameter	Description
`max_connections`	The maximum number of messaging connections to the Oracle database used by the gateway agent. If `NULL,` the current value is unchanged. If nonnull, the value must be `1` or greater.
`max_memory`	The maximum heap size, in MB, used by the gateway agent. If `NULL,` the current value is unchanged. If nonnull, the value must be `64` or greater.

Usage Notes

The default values for configuration parameters are set when Messaging Gateway is installed.

The max_memory parameter changes take effect the next time the gateway agent is active. If the agent is currently active, the gateway must be shut down and started for the changes to take effect.

The max_connections parameter specifies the maximum number of JDBC messaging connections created and used by the AQ driver. This parameter is dynamically changed for a larger value only. In release 9.2, the gateway agent must be shut down and restarted before a smaller value takes effect.

DB_CONNECT_INFO Procedure

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

Syntax

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

Parameters

Table 31-17 DB_CONNECT_INFO Procedure Parameters

Parameter	Description
`username`	The user name used for connections to the Oracle database. `NULL` is not allowed
`password`	The password used for connections to the Oracle database. `NULL` is not allowed
`database`	The database connect string used by the gateway agent. `NULL` indicates that a local connection should be used.

Usage Notes

The gateway agent connects to the Oracle database as the user configured by this API. An Oracle administrator should create the user, grant it the role MGW_AGENT_ROLE, and then call this procedure to configure Messaging Gateway. The MGW_AGENT_ROLE is used to grant this user special privileges needed to access gateway configuration information stored in the database, enqueue or dequeue messages to and from Oracle queues, and perform certain AQ administration tasks.

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 31-18 STARTUP Procedure Parameters

Parameter	Description
instance	Specifies which instance can execute 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 executed. 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.

SHUTDOWN Procedure

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

Syntax

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

Parameters

Table 31-19 SHUTDOWN Procedure Parameters

Parameter Description

Parameter	Description
sdmode	The shutdown mode. Values: `SHUTDOWN_NORMAL` for normal shutdown. The gateway agent may attempt to complete any propagation work currently in progress. `SHUTDOWN_IMMEDIATE` for immediate shutdown. The gateway terminates any propagation work currently in progress and shuts down immediately.

sdmode

The shutdown mode. Values:

SHUTDOWN_NORMAL for normal shutdown. The gateway agent may attempt to complete any propagation work currently in progress.
SHUTDOWN_IMMEDIATE for immediate shutdown. The gateway terminates any propagation work currently in progress and shuts down immediately.

Usage Notes

In release 9.2, the sdmode parameter is ignored and all shutdown modes behave the same way.

CLEANUP_GATEWAY Procedure

This procedure cleans up Messaging Gateway. The procedure performs cleanup or recovery actions that may be needed when the gateway is left in some abnormal or unexpected condition. The MGW_GATEWAY view lists gateway status and configuration information that pertains to the cleanup actions.

Syntax

DBMS_MGWADM.CLEANUP_GATEWAY(
   action  IN BINARY_INTEGER);

Parameters

Table 31-20 CLEANUP_GATWAY Procedure Parameters

Parameter Description

Parameter	Description
`action`	The cleanup action to be performed. Values: `CLEAN_STARTUP_STATE` for gateway startup state recovery.

action

The cleanup action to be performed. Values:

CLEAN_STARTUP_STATE for gateway startup state recovery.

Usage Notes

The CLEAN_STARTUP_STATE action involves recovery tasks that set the gateway to a known state when the gateway agent has crashed or some other abnormal event occurs so that the gateway cannot be started. This should only be done when the gateway agent has been started but appears to have crashed or has been nonresponsive for an extended period of time.

Conditions or indications where this action may be needed:

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.

The cleanup tasks include:

Removing the queued job used to start the external gateway agent process.
Setting certain configuration information to a known state. For example, setting the agent status to NOT_STARTED.

The following considerations apply:

This fails if the agent status is NOT_STARTED or START_SCHEDULED.
This fails if no shutdown attempt has been made prior to calling this procedure, except if the agent status is STARTING.
This attempts to contact (ping) the gateway agent. If successful, the assumption is that the agent is active and this procedure fails. If the agent does not respond after several attempts have been made, the cleanup tasks are performed.
This procedure takes several seconds, possibly up to one minute, if the gateway agent never responds to the ping attempts. This is expected behavior under conditions where this particular cleanup action is appropriate and necessary.

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 31-21 SET_LOG_LEVEL Procedure Parameters

Parameter	Description
log_level	Level at which the Messaging Gateway agent logs information; refer to the `DBMS_MGWADM.<>_LOGGING` constants. `BASIC_LOGGING` generates the least information while `TRACE_DEBUG_LOGGING` generates the most information.

CREATE_MSGSYSTEM_LINK Procedure

This procedure creates a messaging system link to an MQSeries 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 31-22 CREATE_MSGSYSTEM_LINK Procedure Parameters

Parameter	Description
linkname	A user-defined name to identify the message system link
properties	Basic properties of an MQSeries 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

Refer to "Basic Link Properties (MGW_MQSERIES_PROPERTIES)" for more information about messaging link properties.

ALTER_MSGSYSTEM_LINK Procedure

This procedure alters the properties of an MQSeries 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 31-23 ALTER_MSGSYSTEM_LINK Procedure Parameters

Parameters	Description
linkname	The messaging system link name
properties	Basic properties for an MQSeries messaging system link. If `NULL`, no link properties are changed.
options	Optional link properties. `NULL` if no options are changed. If nonnull, 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, the current value is not changed.

Usage Notes

In release 9.2, the MGW_MQSERIES_PROPERTIES.MAX_CONNECTIONS parameter specifies the maximum number of messaging connections created and used for that messaging link. This parameter is dynamically changed for a larger value only. The gateway agent must be shut down and restarted before a smaller value takes effect.

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 option properties. Each property affects the current property list in a particular manner; add a new property, replace an existing property, remove an existing property, or remove all properties.

Some properties cannot be modified and this procedure will fail if you try. Other properties can be modified only under certain conditions, depending on the current configuration; for example, when there are no propagation subscribers or schedules that have a source or destination associated with the link.

For properties that can be changed, a few are dynamic, while others require Messaging Gateway to be shut down and restarted before they take effect.

Refer to "Basic Link Properties (MGW_MQSERIES_PROPERTIES)" for more information on messaging link properties.

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 31-24 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 fails if there is a registered foreign (non-Oracle) queue that references this link.

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 31-25 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,` the value provided for the `name` parameter is used as the provider queue name.
domain	The domain type of the queue. Values: `NULL` if the domain type is automatically determined based on the messaging system of the queue `DOMAIN_QUEUE` for a queue (point-to-point model) `DOMAIN_TOPIC` 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.

In release 9.2, domain is not used and must be NULL because the domain type can be automatically determined for the messaging systems currently supported.

Refer to "Basic Link Properties (MGW_MQSERIES_PROPERTIES)" for more information on messaging link properties.

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 31-26 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 fails if a subscriber or propagation schedule references the non-Oracle queue.

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

Parameters

Table 31-27 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. Values: `DBMS_MGWADM.OUTBOUND_PROPAGATION` for AQ to non-Oracle propagation `DBMS_MGWADM.INBOUND_PROPAGATION` for non-Oracle to 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 AQ payload and a gateway-defined ADT. The type of transformation needed depends on the value specified for `propagation_type.` If no transformation is provided (a `NULL` value is specified), the gateway makes a best effort to propagate messages based on the AQ payload type and the capabilities of the non-Oracle messaging system. For example, the gateway automatically propagates messages for an AQ queue having a `RAW` payload and non-Oracle messaging systems that support a `bytes' message body.
`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,` 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.

Usage Notes

For OUTBOUND_PROPAGATION, parameters are interpreted as follows:

queue_name - specifies the local 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 AQ subscriber rule. This is NULL if no rule is needed.
transformation - specifies the transformation used to convert the AQ payload to a gateway-defined ADT.

The gateway propagation dequeues messages from the AQ queue using the transformation to convert the AQ payload to a known gateway-defined ADT. The message is then enqueued in the foreign messaging system based on the gateway ADT.
exception_queue - specifies the name of a local AQ queue to which messages are moved if an exception occurs. This must have a syntax of schema.queue.

For INBOUND_PROPAGATION, parameters 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 AQ queue to which message 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 a gateway-defined ADT to the AQ payload type.

The gateway propagation dequeues messages from the foreign messaging system and converts the message body to a known gateway-defined ADT. The transformation is used to convert the gateway ADT to an AQ payload type when the message is enqueued to the 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.

For OUTBOUND_PROPAGATION, a local subscriber is added to the AQ queue. The subscriber is of the form aq$_agent(`MGW_<subscriber_id>',NULL,NULL).

For INBOUND_PROPAGATION, whether or not a subscriber is needed depends on the requirements of the non-Oracle messaging system.

For OUTBOUND_PROPAGATION, the exception queue has the following considerations:

The user is responsible for creating the 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 NORMAL_QUEUE rather than EXCEPTION_QUEUE. Enqueue restrictions prevent the gateway propagation from using an AQ queue of type EXCEPTION_QUEUE as a gateway exception queue.

For INBOUND_PROPAGATION, the exception queue has the following considerations:

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

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

Parameters

Table 31-28 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's propagation type. A `NULL` value indicates that no subscription rule is needed. If `DBMS_MGWADM.NO_CHANGE,` the current value is unchanged.
`transformation`	Specifies the transformation needed to convert between the AQ payload and a gateway-defined ADT. The type of transformation needed depends on the subscriber's propagation type. A `NULL` value indicates that no transformation is needed. If `DBMS_MGWADM.NO_CHANGE,` the current value is unchanged.
`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 no exception queue is associated with the subscriber, propagation stops if a problem occurs. The syntax and interpretation of this parameter depend on the subscriber's propagation type. A `NULL` value indicates that no exception queue is used. If `DBMS_MGWADM.NO_CHANGE,` the current value is unchanged. The source queue and exception queue cannot be the same queue.

Usage Notes

For a subscriber having a propagation type of OUTBOUND_PROPAGATION, parameters are interpreted as follows:

rule - specifies an optional AQ subscriber rule.
transformation - specifies the transformation used to convert the AQ payload to a gateway-defined ADT.

The gateway propagation dequeues messages from the AQ queue using the transformation to convert the AQ payload to a known gateway-defined ADT. The message is then enqueued in the foreign messaging system based on the gateway ADT.
exception_queue - specifies the name of a local AQ queue to which messages are moved if an exception occurs. This must have a syntax of schema.queue.

For a subscriber having a propagation type of INBOUND_PROPAGATION, parameters are interpreted as follows:

rule - specifies an optional subscriber rule that is valid for the foreign messaging system.
transformation - specifies the transformation used to convert a gateway-defined ADT to the AQ payload type.

The gateway propagation dequeues messages from the foreign messaging system and converts the message body to a known gateway-defined ADT. The transformation is used to convert the gateway ADT to an AQ payload type when the message is enqueued to the 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.

For OUTBOUND_PROPAGATION, the exception queue has the following considerations:

The user is responsible for creating the AQ queue to be used as the exception queue.
The payload type of the source and exception queues must match.
The exception queue must be created as a queue type of NORMAL_QUEUE rather than EXCEPTION_QUEUE. Enqueue restrictions prevent gateway propagation from using an AQ queue of type EXCEPTION_QUEUE as a gateway exception queue.

For INBOUND_PROPAGATION, the exception queue has the following considerations:

The exception queue must be a registered non-Oracle queue.
The source and exception queues must use the same messaging system 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 31-29 REMOVE_SUBSCRIBER Procedure Parameters

Parameter Description

Parameter	Description
`subscriber_id`	Identifies the subscriber to be removed
`force`	Specifies whether this procedure should succeed even if the gateway is not able to perform all cleanup actions pertaining to this subscriber. Values: `NO_FORCE (0)` if this should fail if unable to cleanup successfully. `FORCE (1)` if this should succeed even though all cleanup actions may not be done. The gateway agent uses various resources of the Oracle database and non-Oracle messaging system for its propagation work; for example, it enqueues messages to log queues, creates subscribers, and so on. These resources are typically associated with each subscriber and need to be released when the subscriber is no longer needed. Typically, this procedure should only be called when the gateway agent is running and able to access the non-Oracle messaging system associated with this subscriber.

subscriber_id

Identifies the subscriber to be removed

force

Specifies whether this procedure should succeed even if the gateway is not able to perform all cleanup actions pertaining to this subscriber. Values:

NO_FORCE (0) if this should fail if unable to cleanup successfully.
FORCE (1) if this should succeed even though all cleanup actions may not be done.

The gateway agent uses various resources of the Oracle database and non-Oracle messaging system for its propagation work; for example, it enqueues messages to log queues, creates subscribers, and so on. These resources are typically associated with each subscriber and need to be released when the subscriber is no longer needed. Typically, this procedure should only be called when the 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 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 31-30 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 the 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 60 );

Parameters

Table 31-31 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. Values: `DBMS_MGWADM.OUTBOUND_PROPAGATION` for AQ to non-Oracle propagation `DBMS_MGWADM.INBOUND_PROPAGATION` for non-Oracle to 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`	Specifies the initial start time for the propagation window for messages from the source queue to the destination
`duration`	Specifies the duration of the propagation window, in seconds. A `NULL` value means that the propagation window is forever, or until the propagation is unscheduled.
`next_time`	Specifies the date function to compute the start of the next propagation window from the end of the current window. A `NULL` value means that the propagation is stopped at the end of the current window.
`latency`	Specifies the maximum wait, in seconds, in the propagation window for a message to be propagated after it is enqueued. However, if for example, the latency is 60 seconds, and if no messages are waiting to be propagated, then during the propagation window, no messages are propagated from the source to the destination for at least 60 more seconds. If the latency is 0, then a message is propagated as soon as it is enqueued.

Usage Notes

In release 9.2, all window parameters are ignored.

For OUTBOUND_PROPAGATION, parameters are as follows:

source - specifies the local AQ queue, which 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.

For INBOUND_PROPAGATION, parameters are interpreted as follows:

source - specifies the foreign queue, which is the propagation source. This must have a syntax of registered_queue@message_link.
destination - specifies the local AQ queue to which message are propagated. This must have a syntax of schema.queue.

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

UNSCHEDULE_PROPAGATION Procedure

This procedure removes a propagation schedule.

Syntax

DBMS_MGWADM.UNSCHEDULE_PROPAGATION (
   schedule_id   IN VARCHAR2 );

Parameters

Table 31-32 UNSCHEDULE_PROPAGATION Procedure Parameters

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

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

Parameters

Table 31-33 ALTER_PROPAGATION_SCHEDULE Procedure Parameters

Parameter	Description
`schedule_id`	Identifies the propagation schedule to be altered
`duration`	Specifies the duration of the propagation window, in seconds. A `NULL` value means that the propagation window is forever, or until the propagation is unscheduled.
`next_time`	Specifies the date function to compute the start of the next propagation window from the end of the current window. A `NULL` value means that the propagation is stopped at the end of the current window.
`latency`	Specifies the maximum wait, in seconds, in the propagation window for a message to be propagated after it is enqueued. However, if for example, the latency is 60 seconds, and if no messages are waiting to be propagated, then during the propagation window, no messages are propagated from the source to the destination for at least 60 additional seconds. If the latency is 0, then a message is propagated as soon as it is enqueued.

Usage Notes

In release 9.2, propagation window parameters are ignored.

Caution:

This procedure always overwrites the existing value for each parameter. If a given parameter is not specified, the existing values are overwritten with the default value.

ENABLE_PROPAGATION_SCHEDULE Procedure

This procedure enables a propagation schedule.

Syntax

DBMS_MGWADM.ENABLE_PROPAGATION_SCHEDULE (
   schedule_id  IN VARCHAR2 );

Parameters

Table 31-34 ENABLE_PROPAGATION_SCHEDULE Procedure Parameters

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

DISABLE_PROPAGATION_SCHEDULE Procedure

This procedure disables a propagation schedule.

Syntax

DBMS_MGWADM.DISABLE_PROPAGATION_SCHEDULE (
   schedule_id  IN VARCHAR2 );

Parameters

Table 31-35 DISABLE_PROPAGATION_SCHEDULE Procedure Parameters

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