Release 1 (9.0.1)
Part Number A90837-01
 Contents |
 Index |
| Oracle9i Messaging Gateway Supplement Release 1 (9.0.1) Part Number A90837-01 |
|
DBMS_MGWADM
DBMS_MGWADM defines the Messaging Gateway administrative interface. The package and object types are owned by SYS.
The following topics are discussed in this chapter:
This type specifies a named property. MGW_PROPERTY is used to specify optional properties for messaging links and foreign queues.
TYPE SYS.MGW_PROPERTY IS OBJECT( name VARCHAR2(100), value VARCHAR2(1000));
| Attribute | Description |
|---|---|
|
|
Property name |
|
|
Property value |
This method constructs a new MGW_PROPERTY instance. All attributes are assigned a value of NULL.
STATIC FUNCTION CONSTRUCT RETURN SYS.MGW_PROPERTY;
This method constructs a new MGW_PROPERTY instance initialized using the given parameters.
STATIC FUNCTION CONSTRUCT( p_name IN VARCHAR2, p_value IN VARCHAR2) RETURN SYS.MGW_PROPERTY;
| Parameter | Description |
|---|---|
|
|
Property name |
|
|
Property value |
This type specifies an array of properties.
TYPE SYS.MGW_PROPERTIES AS VARRAY (100) OF SYS.MGW_PROPERTY;
Unless noted otherwise, Messaging Gateway uses named properties as follows:
'MGWPROP$_' prefix are reserved. They are used for special purposes and are invalid when used as a normal property name.
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:
If a property of the given name already exists, the current value is replaced with the new value; otherwise the new property is added to the end of the list.
MGW_PROPERTY.NAME = 'MGWPROP$_REMOVE' MGW_PROPERTY.VALUE = <name of property to remove>
No action is taken if the property name does not exist in the original list.
The DBMS_MGWADM package defines constants to represent the reserved property names. Refer to the MGWPROP_< > constants.
This type specifies basic properties for an MQSeries messaging system link.
TYPE SYS.MGW_MQSERIES_PROPERTIES IS OBJECT ( queue_manager VARCHAR2(64), hostname VARCHAR2(64), port INTEGER, channel VARCHAR2(64), interface_type INTEGER, max_connections INTEGER, username VARCHAR2(64), password VARCHAR2(64), inbound_log_queue VARCHAR2(64), outbound_log_queue VARCHAR2(64));
This method constructs a new MGW_MQSERIES_PROPERTIES instance. All attributes are assigned a value of NULL.
STATIC FUNCTION CONSTRUCT RETURN SYS.MGW_MQSERIES_PROPERTIES ;
This method constructs a new 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.
STATIC FUNCTION ALTER_CONSTRUCT RETURN SYS.MGW_MQSERIES_PROPERTIES ;
The following sections discuss properties of MQSeries related to links and queues. Refer to IBM MQSeries documentation for more information.
Table 5-6 summarizes the basic configuration properties for an MQSeries messaging link. (Refer to "Notes on Table 5-6" for an explanation of the numbers in parentheses.) The table indicates which properties are optional (NULL allowed), which can be altered, and if alterable, which values can be dynamically changed.
NULL, the port and channel must be NULL. If the hostname is nonnull, the port and channel must be nonnull. If the hostname is NULL, an MQSeries bindings connection is used; otherwise a client connection is used.
NULL, a default value of DBMS_MGWADM.MQSERIES_BASE_JAVA_INTERFACE is used.
NULL, a default value of 1 is used.
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.
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.
This section describes optional configuration properties supported for an MQSeries messaging link. These properties are specified by using the options parameter of DBMS_MGWADM.CREATE_MSGSYSTEM_LINK and DBMS_MGWADM.ALTER_MSGSYSTEM_LINK.
This property specifies the character set identifier to be used. This should be the character set's integer value (for example, 819) rather than a descriptive string. If not set, the MQSeries default character set 819 is used.
Default: 819
Alterable: yes
Dynamic: no
This property specifies the fully qualified Java classname of a class implementing the MQReceiveExit interface. If not set, no default is used. This class must be in the CLASSPATH of the Messaging Gateway agent.
Default: none
Alterable: yes
Dynamic: no
This property specifies the fully qualified Java classname of a class implementing the MQSendExit interface. If not set, no default is used. This class must be in the CLASSPATH of the Messaging Gateway agent.
Default: none
Alterable: yes
Dynamic: no
This property specifies the fully qualified Java classname of a class implementing the MQSecurityExit interface. If not set, no default is used. This class must be in the CLASSPATH of the Messaging Gateway agent.
Default: none
Alterable: yes
Dynamic: no
This section describes optional configuration properties supported for a registered queue of an MQSeries messaging link. These properties are specified by using the options parameter of DBMS_MGWADM.REGISTER_FOREIGN_QUEUE.
This property specifies the value used for the openOptions argument of the MQSeries Base Java MQQueueManager.accessQueue method. No value is required but if one is given, 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.
Default: MQOO_OUTPUT for an enqueue/put operation; MQOO_INPUT_SHARED for a dequeue/get operation
Alterable: no
Dynamic: no
This procedure alters Messaging Gateway agent parameters.
DBMS_MGWADM.ALTER_AGENT ( max_connections IN BINARY_INTEGER DEFAULT NULL, max_memory IN BINARY_INTEGER DEFAULT NULL);
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.0.1, the gateway agent must be shut down and restarted before a smaller value takes effect.
This procedure configures connection information used by the Messaging Gateway agent for connections to the Oracle database.
DBMS_MGWADM.DB_CONNECT_INFO ( username IN VARCHAR2, password IN VARCHAR2, database IN VARCHAR2 );
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.
This procedure starts Messaging Gateway. It must be called before any propagation activity can take place.
DBMS_MGWADM.STARTUP
Messaging Gateway cannot be started until an agent user has been configured using DB_CONNECT_INFO.
This procedure shuts down Messaging Gateway. No propagation activity occurs until the gateway is started.
DBMS_MGWADM.SHUTDOWN ( sdmode IN BINARY_INTEGER DEFAULT DBMS_MGWADM.SHUTDOWN_NORMAL);
In release 9.0.1, the sdmode parameter is ignored and all shutdown modes behave the same way.
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.
DBMS_MGWADM.CLEANUP_GATEWAY( action IN BINARY_INTEGER);
| Parameter | Description |
|---|---|
|
|
The cleanup action to be performed. Valid values:
|
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:
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:
NOT_STARTED.
The following considerations apply:
NOT_STARTED or START_SCHEDULED.
STARTING.
This procedure dynamically alters the Messaging Gateway agent logging level. Messaging Gateway must be running.
DBMS_MGWADM.SET_LOG_LEVEL ( log_level IN BINARY_INTEGER);
This procedure creates a messaging system link to an MQSeries messaging system.
DBMS_MGWADM.CREATE_MSGSYSTEM_LINK( linkname IN VARCHAR2, properties IN sys.mgw_mqseries_properties, options IN sys.mgw_properties DEFAULT NULL, comment IN VARCHAR2 DEFAULT NULL);
Refer to "Basic Link Properties (MGW_MQSERIES_PROPERTIES)" for more information about messaging link properties.
This procedure alters the properties of an MQSeries messaging system link.
DBMS_MGWADM.ALTER_MSGSYSTEM_LINK ( linkname IN VARCHAR2, properties IN SYS.MGW_MQSERIES_PROPERTIES, options IN SYS.MGW_PROPERTIES DEFAULT NULL, comment IN VARCHAR2 DEFAULT DBMS_MGWADM.NO_CHANGE);
In release 9.0.1, 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.
This procedure removes a messaging system link for a non-Oracle messaging system.
DBMS_MGWADM.REMOVE_MSGSYSTEM_LINK( linkname IN VARCHAR2);
| Parameters | Description |
|---|---|
|
linkname |
The messaging system link name. |
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.
This procedure registers a non-Oracle queue entity in Messaging Gateway.
DBMS_MGWADM.REGISTER_FOREIGN_QUEUE( name IN VARCHAR2, linkname IN VARCHAR2, provider_queue IN VARCHAR2 DEFAULT NULL, domain IN INTEGER DEFAULT NULL, options IN sys.mgw_properties DEFAULT NULL, comment IN VARCHAR2 DEFAULT NULL);
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.0.1, 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.
This procedure removes a non-Oracle queue entity in Messaging Gateway.
DBMS_MGWADM.UNREGISTER_FOREIGN_QUEUE( name IN VARCHAR2, linkname IN VARCHAR2);
| Parameter | Description |
|---|---|
|
name |
The queue name. |
|
linkname |
The link name for the messaging system on which the queue exists. |
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.
This procedure adds a subscriber used to consume messages from a source queue for propagation to a destination.
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);
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:
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:
This procedure alters the parameters of a subscriber used to consume messages from a source queue for propagation to a destination.
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 );
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:
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:
This procedure removes a subscriber used to consume messages from a source queue for propagation to a destination.
DBMS_MGWADM.REMOVE_SUBSCRIBER ( subscriber_id IN VARCHAR2, force IN BINARY_INTEGER DEFAULT DBMS_MGWADM.NO_FORCE );
For outbound propagation, a local subscriber is removed from the AQ queue.
This procedure resets the propagation error state for a subscriber.
DBMS_MGWADM.RESET_SUBSCRIBER ( subscriber_id IN VARCHAR2 );
| Parameter | Description |
|---|---|
|
|
Identifies the subscriber. |
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.
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 );
In release 9.0.1, 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:
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.
This procedure removes a propagation schedule.
DBMS_MGWADM.UNSCHEDULE_PROPAGATION ( schedule_id IN VARCHAR2 );
| Parameter | Description |
|---|---|
|
|
Identifies the propagation schedule to be removed. |
This procedure alters a propagation schedule.
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 );
In release 9.0.1, propagation window parameters are ignored.
This procedure enables a propagation schedule.
DBMS_MGWADM.ENABLE_PROPAGATION_SCHEDULE ( schedule_id IN VARCHAR2 );
| Parameter | Description |
|---|---|
|
|
Identifies the propagation schedule to be enabled. |
This procedure disables a propagation schedule.
DBMS_MGWADM.DISABLE_PROPAGATION_SCHEDULE ( schedule_id IN VARCHAR2 );
| Parameter | Description |
|---|---|
|
|
Identifies the propagation schedule to be disabled. |
The views listed in Table 5-27 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.
This view lists configuration and status information for Messaging Gateway, as shown in Table 5-28.
This view lists the names and types of messaging system links currently defined.
| Name | Type | Description |
|---|---|---|
|
|
|
Name of the messaging system link. |
|
|
|
Type of messaging system link. Values: |
|
|
|
User comment for the link |
This view lists information for the MQSeries messaging system links. The view includes most of the messaging system properties specified when the link is created.
This view lists information for foreign queues. The view includes most of the queue properties specified when the queue is registered.
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.
This view lists configuration and status information for Messaging Gateway schedules. The view includes most of the schedule properties specified when the schedule is created, as well as other status information.
|
 Copyright © 2001 Oracle Corporation. All Rights Reserved. |
|