Parameters

Table 31-16 ALTER_AGENT Procedure Parameters

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

Parameters

Table 31-17 DB_CONNECT_INFO Procedure Parameters

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

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

Parameters

Table 31-19 SHUTDOWN Procedure Parameters

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

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

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.

Parameters

Table 31-23 ALTER_MSGSYSTEM_LINK Procedure Parameters

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.

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.

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.

Parameters

Table 31-28 ALTER_SUBSCRIBER Procedure Parameters

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.

Parameters

Table 31-29 REMOVE_SUBSCRIBER Procedure Parameters

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.

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.

Parameters

Table 31-33 ALTER_PROPAGATION_SCHEDULE Procedure Parameters

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.