Release 1 (9.0.1)
Part Number A90837-01
 Contents |
 Index |
| Oracle9i Messaging Gateway Supplement Release 1 (9.0.1) Part Number A90837-01 |
|
After Messaging Gateway is installed and the postinstallation steps are completed, Messaging Gateway is ready to be configured and run. This chapter describes how to configure, start, and stop Messaging Gateway. It also describes how to monitor the Messaging Gateway agent. An example configuration is provided to illustrate propagating messages from an AQ queue with payload type RAW to an MQSeries queue. All commands in the examples must be run as a user who has been granted MGW_ADMINISTRATOR_ROLE, except for the commands to create transformations.
The following topics are discussed in this chapter:
The Messaging Gateway agent runs as a process external to the database. To access Advanced Queuing and the Messaging Gateway administration packages, the Messaging Gateway agent needs to establish connections back to the database.
Before starting, configuration information must be registered, including information used to connect to the database and set resource limits.
The DBMS_MGWADM.DB_CONNECT_INFO procedure is used to configure Messaging Gateway with the name and password of the user that the Messaging Gateway agent will use for database connections, and the database connect string used to make the connection. The user must have been granted MGW_AGENT_ROLE before the Messaging Gateway agent can be started. If the database connect string is not specified, local connections are used by the Messaging Gateway agent.
You can also call DBMS_MGWADM.DB_CONNECT_INFO to set new connection information when the Messaging Gateway agent is running.
SQL> exec dbms_mgwadm.db_connect_info(`mgwagent', `mgwagent_password', `mydatabase')
The maximum number of connections in a connection pool available for the Messaging Gateway agent to connect to the database and the heap size, in megabytes, of the Messaging Gateway agent process can be set using DBMS_MGWADM.ALTER_AGENT. The number of connections in the connection pool can impact performance. The default values are 1 connection and 64 MB of memory.
The following sets the number of database connections to 2 and the heap size to 64M.
SQL> exec dbms_mgwadm.alter_agent(2, 64)
You can alter the maximum number of connections when the Messaging Gateway agent is running, but the value can only be increased. The maximum memory cannot be altered when Messaging Gateway is running. Entering a value of NULL does not alter the maximum memory attribute.
The following example, when executed with the Messaging Gateway agent running, updates the maximum number of connections to 3. The maximum memory is unchanged.
SQL> exec dbms_mgwadm.alter_agent(3, NULL)
After Messaging Gateway is installed and configured, start it as follows:
SQL> exec dbms_mgwadm.startup
You can determine the status of the Messaging Gateway agent by using the MGW_GATEWAY view and by monitoring the log file. Refer to "Monitoring the Messaging Gateway Log File".
Monitor the Messaging Gateway agent using the MGW_GATEWAY view as follows:
SQL> select * from mgw_gateway; AGENT_STATUS AGENT_PING AGENT_JOB AGENT_USER AGENT_DATABASE LAST_ERRO -------------------------------------------------------------------------- RUNNING REACHABLE 213 MGWAGENT (Continued) LAST_ERR LAST_ERROR_MSG MAX_CONNECTIONS MAX_MEMORY ----------------------------------------------------- 3 64
When Messaging Gateway has completed initialization, the AGENT_STATUS column shows the value RUNNING and the AGENT_PING column shows the value REACHABLE.
The first column, AGENT_STATUS, shows the status of the gateway agent. This column has the following possible values: NOT_STARTED, START_SCHEDULED, INITIALIZING, STARTING, RUNNING, and SHUTTING_DOWN. The second column, AGENT_PING, pings the Messaging Gateway agent. Its value is either REACHABLE or UNREACHABLE. The columns LAST_ERROR_MSG, LAST_ERROR_DATE, and LAST_ERROR_TIME give valuable information if an error in starting or running the Messaging Gateway agent occurs. Refer to "Summary of Database Views" in Chapter 5, "DBMS_MGWADM" for more information.
The following command shuts down the Messaging Gateway agent:
SQL> exec dbms_mgwadm.shutdown
When Messaging Gateway completes the shutdown procedure, the AGENT_STATUS column indicates NOT_STARTED.
By monitoring the MGW_GATEWAY view and the log file, you can determine the success of the shutdown procedure. If problems occur during shutdown or unexpected events occur that leave the Messaging Gateway administration in an inconsistent state, you can reset status information, as follows:
SQL> exec dbms_mgwadm.cleanup_gateway(dbms_gmwadm.CLEAN_STARTUP_STATE)
The Messaging Gateway agent process must not be running when this command is executed.
You can use SQL scripts to configure Messaging Gateway, as illustrated in the following script examples. Full examples can be found in the samples directory of the Messaging Gateway installation.
A Messaging Gateway link is a set of connection information to a non-Oracle messaging system. It is used whenever a connection is needed for either messaging or administrative work.
You can set the following information for a link to an MQSeries queue manager: the queue manager name, channel, host, port, username, and password for an MQSeries client connection. Log queues for inbound or outbound propagation must also be set for use by the Messaging Gateway agent in guaranteeing exactly-once delivery. The two queues can refer to the same physical queue, but better performance is achieved if they refer to different physical queues.
An options argument, a set of {name, value} pairs, both of which are strings, represents arguments specific to a non-Oracle messaging system interface. For MQSeries-recognized property names, these include:
`MQ_ccsid' for the corresponding MQEnvironment.CCSID property
`MQ_SendExit' for MQEnvironment.SEND_EXIT
`MQ_ReceiveExit' for MQEnvironment.RECEIVE_EXIT
`MQ_SecurityExit' for MQEnvironment.SECURITY_EXIT
The following example configures a Messaging Gateway link to an MQSeries queue manager. The link is named `mqlink' and is configured to use the MQSeries queue manager `my.queue.manager' on host `myhost.mydomain' and port 1414, using MQSeries channel `mychannel'. This example also uses the options parameter to register an MQSeries SendExit class. The class 'mySendExit' must be in the classpath of the Messaging Gateway agent (set in the mgw.ora file). Refer to "MQSeries System Properties" for supported options. Refer to "Modifying mgw.ora for the External Procedure" in Chapter 2, "Installing Messaging Gateway" for information on setting the classpath of the Messaging Gateway agent.
declare v_options sys.mgw_properties; v_prop sys.mgw_mqseries_properties; begin -- Set options. -- Specify an MQSeries send exit class `mySendExit' to be associated with the queue. v_options := sys.mgw_properties(sys.mgw_property('MQ_SendExit', 'mySendExit'') ); -- set certain MQSeries properties used for MQSeries v_prop := sys.mgw_mqseries_properties.construct(); v_prop.max_connections := 1; v_prop.username := 'mqm'; -- username given to queue manager v_prop.password := 'mqm'; -- password given to queue manager v_prop.hostname := 'myhost.mydomain' -- hostname for queue manager host v_prop.port := 1414; -- port (1414 is MQSeries default) v_prop.channel := 'mychannel'; -- MQSeries channel name v_prop.outbound_log_queue := 'mylogq'; -- name of MQSeries queue to be -- used for MGW logging on -- outbound jobs. v_prop.queue_manager := 'my.queue.manager'; -- queue manager name dbms_mgwadm.create_msgsystem_link( linkname => 'mqlink', -- link name properties => v_prop, -- MQSeries driver properties options => v_options ); -- options end;
Messaging Gateway does not impose a restriction on the number of links that you can configure.
Some link information can be altered. For an MQSeries link, the max_connections, username, password, inbound_log_queue, and outbound_log_queue properties can be altered after creation. In the following example, the `mqlink' link created in "Creating a Messaging Gateway Link" is altered so that the max_connections and password properties are changed.
If the type of a property is VARCHAR2, a value of DBMS_MGWADM.NO_CHANGE leaves the property unchanged. For properties of other types, a value of NULL leaves the property unchanged. Use the mgw_mqseries_properties.alter_construct function when altering an MQSeries link. This sets the appropriate values automatically. Then set the values that need to be changed.
declare v_options sys.mgw_properties; v_prop sys.mgw_mqseries_properties; begin -- Alter certain MQSeries properties used for MQSeries. v_prop := sys.mgw_mqseries_properties.alter_construct(); v_prop.max_connections := 2; -- max_connections increased v_prop.password := `newpasswd'; -- change password given to queue manager dbms_mgwadm.alter_msgsystem_link( linkname => 'mqlink', -- link name properties => v_prop, -- MQSeries driver properties -- options will not be changed comment => `link to queue manager, my.queue.manager. on my.host `); -- add comment end;
You can alter link information when the Messaging Gateway agent is running or when it is not. Refer to Chapter 5, "DBMS_MGWADM" for restrictions on changes when the Messaging Gateway agent is running.
You can remove a Messaging Gateway link to a non-Oracle messaging system only if all registered queues associated with this link have already been removed.
begin dbms_mgwadm.remove_msgsystem_link(`mqlink'); end;
The link can be removed whether or not the Messaging Gateway agent is running.
The MGW_LINKS view can be used to check which links have been configured. It lists the name and link type (which non-Oracle messaging system it applies to). To check configured link information, non-Oracle messaging system-specific views are available. For MQSeries, the MGW_MQSERIES_LINKS view has columns for most configurable information.
SQL> select * from MGW_LINKS;
LINK_NAME LINK_TYPE LINK_COMMENT
-------------------------------------
MQLINK MQSERIES
SQL> select link_name, queue_manager, channel, hostname from MGW_MQSERIES_LINKS;
LINK_NAME QUEUE_MANAGER CHANNEL HOSTNAME
----------------------------------------------------------
MQLINK my.queue.manager mychannel myhost.mydomain
All non-Oracle messaging system queues involved in propagation must be registered through the Messaging Gateway administration interface. Messaging Gateway does not create non-Oracle queues; it only uses the configured information to access them.
The following information is used to register a non-Oracle queue:
For MQSeries the only option is `MQ_openOptions'. This property corresponds to the openOptions argument of the MQSeries Base Java MQQueueManager.accessQueue method. If not specified, the value of openOptions defaults to MQC.MQOO_OUTPUT on enqueue and MQC.MQOO_INPUT_SHARED on dequeue.
-- Registering non-Oracle queue -- declare v_options sys.mgw_properties; begin -- No options set for this foreign queue. Below is a sample of how one would be set. -- v_options := sys.mgw_properties(sys.mgw_property(`MQ_openOptions', `2066')); -- Register the queue dbms_mgwadm.register_foreign_queue( name => 'destq', -- MGW non-Oracle queue name linkname => 'mqlink', -- name of link to use provider_queue => 'my_mq_queue', -- name of MQSeries queue domain => dbms_mgwadm.DOMAIN_QUEUE, -- single consumer queue options => v_options); end;
The domain parameter is set to DBMS_MGWADM.DOMAIN_QUEUE for point-to-point queues and DBMS_MGWADM.DOMAIN_TOPIC for publish-subscribe queues. Only point-to-point queues are supported for MQSeries.
After a non-Oracle queue is configured and registered, it cannot be altered. The registration information must be deleted and recreated.
A non-Oracle queue can be unregistered only if there are no subscribers or schedules referencing it.
begin dbms_mwgadm.unregister_foreign_queue(`destq', `mqlink'); end;
You can use the MGW_FOREIGN_QUEUES view to check which non-Oracle queues are registered.
SQL> select name, link_name, provider_queue from MGW_FOREIGN_QUEUES; NAME LINK_NAME PROVIDER_QUEUE ------------------------------------ DESTQ MQLINK my_mq_queue
You do not need to register AQ queues. When AQ queues are referenced, Messaging Gateway accesses them directly.
Propagating messages from one queue to another queue requires a propagation job. A propagation job consists of a propagation subscriber and a propagation schedule, hereafter called a subscriber and a schedule. The subscriber specifies the source and destination queues, while the schedule specifies when the propagation job is processed. A subscriber without an associated schedule is not processed. For a schedule to be associated with a subscriber, it must have the same propagation source and propagation destination.
A Messaging Gateway subscriber does not necessarily correspond to a subscriber in a non-Oracle messaging system, unless that system has such a notion. Note that a Messaging Gateway subscriber for an AQ queue is not the same thing as an AQ subscriber on that queue. However, creating a Messaging Gateway subscriber results in the creation of a corresponding AQ subscriber. Refer to "ADD_SUBSCRIBER Procedure" in Chapter 5, "DBMS_MGWADM" for more information.
A Messaging Gateway subscriber consists of the following information:
begin dbms_mgwadm.add_subscriber( subscriber_id => 'sub_aq2mq', -- MGW subscriber name propagation_type => dbms_mgwadm.outbound_propagation, -- outbound propaga queue_name => 'mgwuser.srcq', -- AQ queue name (source queue) destination => 'destq@mqlink'); -- MGW foreign queue with link --(destination queue) end;
This example does not specify a subscriber rule for selecting messages when dequeuing from the AQ queue. Refer to "Using Transformations" for an example in which a transformation is specified.
A Messaging Gateway schedule must be configured for a propagation job to be processed. The schedule determines when the propagation of messages occurs. In release 9.0.1, a schedule is used only for enabling and disabling propagation jobs. The scheduling parameters are not used in release 9.0.1.
begin dbms_mgwadm.schedule_propagation( schedule_id => 'sch_aq2mq', -- schedule name propagation_type => dbms_mgwadm.outbound_propagation, -- outbound propaga source => 'mgwuser.srcq', -- AQ queue name destination => 'destq@mqlink'); -- MGW foreign queue with link end;
When a schedule is created, it is in an enabled state. This means that if there is an associated subscriber, the corresponding propagation job will be active. That is, it will be polling for messages in the source queue. To disable (or enable) a propagation job, the associated schedule must be disabled (or enabled).
The following examples disable and enable the schedule `sch_aq2mq'.
begin dbms_mgwadm.disable_propagation_schedule(`sch_aq2mq'); end; begin dbms_mgwadm.enable_propagation_schedule(`sch_aq2mq'); end;
When a problem occurs in propagation, the Messaging Gateway agent retries the failed operation up to 16 times before the propagation job stops. To restart the propagation job with the error count reset to zero, use the reset_subscriber( ) procedure.
begin dbms_mgwadm.reset_subscriber(`sub_aq2mq'); end;
The following parameters can be altered after the subscriber is created: the selection rule, the transformation, and the exception queue. The value DBMS_MGWADM.NO_CHANGE indicates that the value of the parameter has not changed.
begin dbms_mgwadm.alter_subscriber( subscriber_id => 'sub_aq2mq', -- MGW subscriber name rule => dbms_mgwadm.NO_CHANGE, -- selection rule not changed -- not used with MQSeries transformation => dbms_mgwadm.NO_CHANGE, -- transformation invoked on -- dequeue not changed exception_queue => `mgwuser.my_ex_queue'); -- register exception -- queue: same type as source end;
Subscribers and schedules can be altered whether or not the Messaging Gateway agent is running.
In general, you should remove subscribers when the Messaging Gateway agent is running so that it can perform cleanup activities such as cleaning log queues and removing non-Oracle messaging system subscribers.
begin dbms_mgwadm.unschedule_propagation(`sch_aq2mq'); end; begin dbms_mgwadm.remove_subscriber(`sub_aq2mq', dbms_mgwadm.NO_FORCE); end;
The second argument specifies whether this procedure should succeed even if the gateway is not able to perform all cleanup actions pertaining to this subscriber. Valid values are DBMS_MGWADM.NO_FORCE and DBMS_MGWADM.FORCE. If DBMS_MGWADM.NO_FORCE is specified, and the Messaging Gateway agent is not running, the subscriber is placed in a DELETE_PENDING state. Cleanup actions will occur when the Messaging Gateway agent is started. If DBMS_MGWADM.FORCE is specified, the procedure will succeed, although all cleanup actions may not be done.
A selection rule specifies an optional subscriber rule for selecting which messages are dequeued from the messaging system. For Advanced Queuing, the rule corresponds to the AQ subscriber rule. Selection rules are not used for MQSeries.
Many applications of Messaging Gateway require you to provide a transformation. For Messaging Gateway to propagate messages from an AQ queue with an arbitrary ADT payload, a mapping must be provided to a Messaging Gateway canonical ADT. Likewise, for Messaging Gateway to propagate messages to an AQ queue with an arbitrary ADT payload, a mapping must be provided from a Messaging Gateway canonical ADT. This is the job of the transformation. A transformation registered with an outbound subscriber is invoked by AQ when Messaging Gateway dequeues from the AQ source queue during propagation. A transformation registered with an inbound subscriber is invoked by Advanced Queuing when Messaging Gateway enqueues to the AQ destination queue during propagation.
For example, trans_sampleadt_to_mgw_basic is a stored procedure representing a transformation function with the following signature:
FUNCTION trans_sampleadt_to_mgw_basic(in_msg IN mgwuser.sampleADT) RETURN sys.mgw_basic_msg_t;
Create a transformation using DBMS_TRANSFORM.CREATE as follows:
begin dbms_transform.create_transformation( schema => 'MGWUSER', name => 'SAMPLE_ADT_TO_MGW_BASIC', from_schema => 'MGWUSER', from_type => 'SAMPLEADT', to_schema => 'SYS', to_type => 'MGW_BASIC_MSG_T', transformation => 'mgwuser.trans_sampleadt_to_mgw_basic(user_data)'); end;
Once created, this transformation can be registered with Messaging Gateway when creating a subscriber.
begin dbms_mgwadm.add_subscriber( subscriber_id => 'sub_aq2mq', -- MGW subscriber name propagation_type => dbms_mgwadm.outbound_propagation, -- outbound propaga queue_name => 'mgwuser.srcq', -- AQ queue name (source queue) destination =>'destq@mqlink', -- MGW foreign queue with link -- (destination queue) transformation => `mgwuser.SAMPLE_ADT_TO_MGW_BASIC'); -- transformation -- invoked on dequeue end;
The exception queue stores messages for which conversion has failed. This queue must be on the same messaging system as the propagation source queue. If specified, a message for which conversion fails is moved to the exception queue instead of the destination queue. If a subscriber does not have an exception queue specified, the propagation job stops when message conversion fails.
For outbound propagation, the exception queue must refer to an already existing AQ 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.
For inbound propagation, the exception queue must be a registered non-Oracle messaging system queue, and the source and exception queues must use the same messaging system link.
You can use the MGW_SUBSCRIBERS view to check the existing configuration of subscribers and to monitor the status of propagation jobs. In addition to the configured information, columns in the view indicate the total number of messages propagated for the job (since the Messaging Gateway agent started), the number of propagation failures, the status of the propagation job, and error information.
The subscriber status value of ENABLED indicates that the subscriber is enabled. (Note that this does not mean that the propagation job is enabled. For a propagation job to be enabled, both the subscriber and an associated schedule must be enabled). DELETE_PENDING indicates that subscriber removal is pending. This can occur when DBMS_MGWADM.REMOVE_SUBSCRIBER is called, but certain cleanup tasks pertaining to this subscriber are still outstanding. In release 9.0.1, a subscriber's status is always ENABLED unless it is DELETE_PENDING.
Error information includes the number of delivery failures, last error message, the last error date, and the last error time. If the number of failures reaches 16, propagation stops. Refer to "Resetting Propagation Jobs".
SQL> select subscriber_id, queue_name, propagated_msgs, exceptionq_msgs from mgw_subscribers; SUBSCRIBER_ID QUEUE_NAME PROPAGATED_MSGS EXCEPTIONQ_MSGS -------------------------------------------------------------------- SUB_AQ2MQ MGWUSER.SRCQ 1014 10
SQL> select queue_name, failures, last_error_msg from mgw_subscribers where subscriber_id = `SUB_AQ2MQ'; QUEUE_NAME FAILURES LAST_ERROR_MSG ----------------------------------------- MGWUSER.SRCQ 0
You can use the MGW_SCHEDULES view to check which schedules are configured and which are enabled.
SQL> select schedule_id, schedule_disabled from MGW_SCHEDULES; SCHEDULE_ID SCH ------------------ SCH_AQ2MQ N (N = not disabled; that is, enabled)
Messaging Gateway agent status, history, and errors are recorded in the Messaging Gateway log file. By default, it is located in the $ORACLE_HOME/mgw/log directory. You should monitor the log file because it is where both updates and errors are reported. A different log file is created each time the Messaging Gateway agent is started.
The following sample log file shows the Messaging Gateway agent starting. Tracing information and errors are logged to this file.
Mon Sep 10 10:27:35 2001 MGW C-Bootstrap 0 process-id=4313 Bootstrap program starting Mon Sep 10 10:27:36 2001 MGW C-Bootstrap 0 process-id=4313 JVM created -- heapsize = 64 >>2001-09-10 10:27:38 MGW AdminMgr 0 LOG Connecting to database using connect string = jdbc:oracle:oci8:@ >>2001-09-10 10:27:55 MGW Engine 0 1 Agent is initializing... >>2001-09-10 10:27:56 MGW MQD 0 LOG Creating MQSeries messaging link: link : MQLINK queue manager : mars.queue.manager channel : kbchannel host : pdsun-dev10.us.oracle.com port : 1414 user : connections : 1 inbound logQ : outbound logQ : kblogqueue >>2001-09-10 10:27:56 MGW AQD 0 LOG Creating AQ messaging link: link : oracleMgwAq database : user : MGWAGENT connections : 10 inbound logQ : sys.mgw_recv_log outbound logQ : sys.mgw_send_log >>2001-09-10 10:27:56 MGW Engine 0 7 Queue DESTQ@MQLINK has been registered. >>2001-09-10 10:27:56 MGW Engine 0 9 Propagation Schedule SCH_AQ2MQ has been added. >>2001-09-10 10:27:56 MGW Engine 0 13 MGW subscriber SUB_AQ2MQ has been created. >>2001-09-10 10:27:56 MGW Engine 0 18 MGW subscriber SUB_AQ2MQ has been activated. >>2001-09-10 10:27:56 MGW Engine 0 13 MGW subscriber SUB_AQ2MQ(MGWUSER.SRCQ --> DESTQ@MQLINK) has been created. >>2001-09-10 10:27:56 MGW Engine 0 2 Agent is up and running.
When configuration information is read at startup time or when dynamic configuration occurs, the information is written to the log. In the sample log file you can see that a link, a registered foreign queue, a subscriber, and a schedule have been created. The log shows that the subscriber has been activated. Any errors also appear in the log. The last line indicates that the Messaging Gateway agent is up and running.
|
 Copyright © 2001 Oracle Corporation. All Rights Reserved. |
|