Release 2 (9.2)
Part Number A96587-01
 Home |
 Book List |
 Contents |
 Index |
 Master Index |
 Feedback |
| Oracle9i Application Developer's Guide - Advanced Queuing Release 2 (9.2) Part Number A96587-01 |
|
Messaging Gateway, an Oracle9i Advanced Queuing feature, enables communication between applications based on non-Oracle messaging systems and Oracle's Advanced Queuing (AQ) feature. Advanced Queuing provides the propagation between two AQ queues to enable e-business (HTTP via IDAP). Messaging Gateway extends that propagation to legacy applications based on non-Oracle messaging systems.
Because Messaging Gateway is integrated with Advanced Queuing and Oracle9i, it offers fully transactional and secure message delivery. Messaging Gateway guarantees that messages are delivered once and only once between AQ and non-Oracle messaging systems that support persistence. The AQ-like PL/SQL interface provides an easy-to-learn administrative API, especially for developers already proficient in using AQ.
This release of Messaging Gateway supports the integration of Oracle9i Advanced Queuing with IBM MQSeries 5.1- and MQSeries 5.2-based applications.
This chapter discusses the following topics:
Messaging Gateway provides the following functionality:
Messaging Gateway propagates messages between Advanced Queuing and non-Oracle messaging systems. Messages sent by Advanced Queuing applications can be received by non-Oracle message system applications. Conversely, messages published by non-Oracle message system applications can be consumed by Advanced Queuing applications.
Messaging Gateway supports the native message formats of messaging systems. AQ messages can have RAW or any ADT payload. MQSeries messages can be TEXT or byte messages of any type. This enables integration of existing applications of messaging systems.
Messaging Gateway facilitates message conversion between AQ messages and non-Oracle message system messages. Messages are converted through either automatic message conversion routines provided by Messaging Gateway or customized message transformation functions that you provide.
Messaging Gateway is managed through an AQ-like PL/SQL interface. Configuration information is stored in Oracle database tables. Message propagation is carried out by an external process of the Oracle database server.
Messaging Gateway guarantees that persistent messages are propagated exactly once if both the message system at the propagation source and the message system at the propagation destination support transactions.
If messages are not persistent or the transaction is not supported by the messaging systems at the propagation source and propagation destination, at-most-once propagation is guaranteed.
Messaging Gateway supports client authentication of Oracle database and non-Oracle messaging systems.
For Oracle database administrators to control access to the tables, views, and procedures created by the gateway, Messaging Gateway defines two roles, MGW_ADMINISTRATOR_ROLE and MGW_AGENT_ROLE, for gateway administration and propagation processing. Refer to "Loading Database Objects into the Database", "Creating a Messaging Gateway Administration User", and "Creating a Messaging Gateway Agent User".
Messaging Gateway has the following main components: an administration package named DBMS_MGWADM for gateway configuration and management, and a gateway agent that processes propagation, as shown in Figure 18-1. The gateway agent consists of a propagation engine and a set of drivers that communicate with non-Oracle messaging systems.
The Messaging Gateway administration package, DBMS_MGWADM, provides an interface for gateway administrators to manage the gateway agent, set up propagation, and monitor propagation processing.
Through the administration package, you configure the gateway agent with the proper user name, password, and database connect string of the Oracle database in order for the agent to create connections to the database. You can also call procedures in the package to assign the maximum number of database connections and the size of the memory heap to the agent.
For the gateway agent to propagate messages to and from a non-Oracle messaging system, a messaging system link, which represents a communication channel between the agent and the non-Oracle messaging system, must be created using the administration package. Multiple messaging system links can be configured in the agent.
All non-Oracle queues that are involved in propagation must be registered using the administration package. Registering a non-Oracle queue in the gateway configuration does not create the physical queue in the non-Oracle messaging system, but only records information about the queue, such as the messaging system link to access it, its native name, and its domain (queue or topic). The physical queue must be created through the administration interfaces of the non-Oracle messaging system.
With messaging system links and non-Oracle queues configured, you can create propagation jobs to set up message propagation. A propagation job in Messaging Gateway consists of a propagation subscriber and a propagation schedule. A propagation subscriber is created to define the source queue and the destination queue of a propagation job. You manipulate the propagation schedule associated with the propagation job to control when the propagation job is processed.
Messaging Gateway provides database views for gateway administrators to query and check the current configuration information, the gateway agent running status, and the propagation job status and statistics.
Gateway configuration can be changed independent of whether the gateway agent is running or shut down. If the agent is running, the administration procedures send notifications to the agent for configuration changes. The agent will dynamically alter its configuration for most configuration changes, although some require that the agent be shut down and restarted before they take effect. All the procedures in the administration package are serialized to guarantee that the gateway agent receives notifications for the configuration changes in the same order they are made.
The gateway agent schedules and processes propagation jobs. The agent executes in an external process of the Oracle database server. The agent is started and terminated by calling the STARTUP and SHUTDOWN procedures in the administration package. Like all external processes of Oracle database server, the agent runs only when the database server that it resides in is up and running.
The agent contains a propagation engine and a set of drivers for the non-Oracle messaging systems. The multithreaded propagation engine fairly schedules propagation jobs and provides parallel interjob and intrajob propagation processing. A polling thread in the agent periodically polls the source queues of enabled propagation jobs and wakes up worker threads to process propagation jobs if messages are available. The drivers in the gateway agent are instantiated when messaging links are created. The drivers run as clients of messaging systems for all messaging operations.
The agent writes log messages into its log files, which contain information about agent configuration, agent status, actions taken by the agent upon receiving dynamic notifications, status of propagation jobs, and all error messages.
You create propagation jobs to set up message propagation. A propagation job conceptually consists of a propagation subscriber and a propagation schedule.
After a propagation subscriber is created, the gateway creates a subscription on the propagation source if the source is a topic (publish-subscribe). The gateway moves all messages that are published to the topic after the subscriber is created. If the propagation source is a point-to-point queue, the gateway moves all messages in the queue to the destination.
A propagation job is not processed until an associated propagation schedule is created. The gateway agent processes enabled propagation jobs. Disabling a propagation job stops the transfer of messages from the source queue to the destination queue, but does not stop subscription.
When a propagation job is processed, messages are dequeued in priority order from the source queue and enqueued to the destination queue. If a message fails to be converted from the source format to the destination format, the message is moved to the exception queue. Messages that have expired in a propagation source queue are not propagated to the destination queue.
Using Messaging Gateway, you can specify a propagation message selector for a propagation job if the source messaging system of the propagation job supports message selectors. Only messages satisfying the message selector are propagated.
If a propagation job runs into failures during processing, the agent retries up to 16 times in an exponential backoff scheme before disabling the job.
When a message is propagated, it is converted from its native format in the source messaging system to its native format in the destination messaging system. The gateway provides automatic message conversions between simple and commonly used message formats. You can provide your own message transformation functions for customized message conversions.
This section describes the steps for loading and setting up Messaging Gateway.
In the init<sid>.ora file, where <sid> is the Oracle system ID of the database instance used for Messaging Gateway, the following parameters must be specified:
JOB_QUEUE_PROCESSES = <num_of_processes>
AQ_TM_PROCESSES = <num_of_processes>
Install the non-Oracle messaging system before loading and setting up Messaging Gateway. Messaging Gateway uses the shared libraries and Java class files of the non-Oracle system.
You must do the following procedures before Messaging Gateway can run. These tasks apply to both Unix and Windows NT, except where "Windows NT Only" or "Unix Only" is indicated.
Using SQL*Plus, run catmgw.sql, located in the $ORACLE_HOME/mgw/admin directory. Run as user: SYS as SYSDBA.
The SQL script catmgw.sql loads the necessary database objects for Messaging Gateway, including roles, tables, views, object types, and the PL/SQL packages. It creates public synonyms for Messaging Gateway PL/SQL packages and types. It creates two roles, MGW_ADMINISTRATOR_ROLE and MGW_AGENT_ROLE, with certain privileges granted. It also creates a library alias for the agent's external procedure. All objects are owned by SYS.
Windows NT Only: You can ignore this step. Static service information for the listener is not necessary on Windows NT.
You must modify listener.ora so that the Messaging Gateway PL/SQL package can call the external procedure.
LISTENER = (ADDRESS_LIST= (ADDRESS=(PROTOCOL=IPC)(KEY=EXTPROC)) . . .
listener.ora, add static service information for the listener in step 1. This involves setting a SID_DESC for the listener. Within the SID_DESC, the following parameters are important to Messaging Gateway and must be specified according to your own situation.
SID_NAME: provide the SID that is specified in the net service name in tnsnames.ora, for example, "mgwextproc".ORACLE_HOME: provide your ORACLE_HOME directory.PROGRAM: provide the name of the external procedure agent, which is "extproc".ENVS: set up the LD_LIBRARY_PATH environment needed for the external procedure to run.
The LD_LIBRARY_PATH must contain the following paths:
[ORACLE_HOME]/jdk/jre/lib/[PLATFORM_TYPE]
[ORACLE_HOME]/lib
Replace the bracketed item with the appropriate, spelled-out value (using $ORACLE_HOME does not work, for example). PLATFORM_TYPE is your platform type, for example, sparc.
# Add a SID_DESC SID_LIST_LISTENER= (SID_LIST= (SID_DESC = (SID_NAME= mgwextproc) (ENVS="LD_LIBRARY_PATH=/private/oracle/orcl9i/jdk/jre/lib/ sparc:/private/oracle/orcl9i/lib") (ORACLE_HOME=/private/oracle/orcl9i) (PROGRAM = extproc)) . . .
Windows NT Only: You can ignore this step.
For the external procedure, configure a net service name MGW_AGENT in tnsnames.ora whose connect descriptor matches the information configured in listener.ora. The net service name must be MGW_AGENT (this value is fixed). The KEY value must match the KEY value specified for the IPC protocol in listener.ora. The SID value must match the value specified for SID_NAME of the SID_DESC entry in listener.ora.
MGW_AGENT = (DESCRIPTION= (ADDRESS_LIST= (ADDRESS= (PROTOCOL=IPC)(KEY=EXTPROC))) (CONNECT_DATA= (SID=mgwextproc) (PRESENTATION=RO)))
The Messaging Gateway initialization file $ORACLE_HOME/mgw/admin/mgw.ora is a TEXT file that the gateway external procedure uses to get initialization parameters to start the agent. Copy $ORACLE_HOME/mgw/admin/sample_mgw.ora to mgw.ora and modify it according to your situation.
The following procedure sets environment variables and other parameters:
Unix Only: Set LD_LIBRARY_PATH. Replace the brackets with appropriate, spelled-out values (using $ORACLE_HOME does not work, for example). PLATFORM_TYPE is your platform type, for example, sparc.
LD_LIBRARY_PATH must contain at least the following paths:
[ORACLE_HOME]/jdk/jre/lib/[PLATFORM_TYPE][ORACLE_HOME]/rdbms/lib[ORACLE_HOME]/oracle/lib[ORACLE_HOME]/mgw/libLD_LIBRARY_PATH.Windows NT Only: Set the MGW_PRE_PATH variable. Its value is the path to the jvm.dll library. For JDK resources, use the JDK package under %ORACLE_HOME%. For example, if %ORACLE_HOME% is D:\oracle, then add a line such as:
set MGW_PRE_PATH = D:\oracle\jdk\jre\bin\classic
This varible is prepended to the path inherited by the Messaging Gateway agent process.
CLASSPATH. (Windows NT users must set CLASSPATH using Windows NT path syntax.)
CLASSPATH must contain at least the following. Replace the brackets with appropriate, spelled-out values (using $ORACLE_HOME does not work, for example).
[ORACLE_HOME]/mgw/classes/mgw.jar
[ORACLE_HOME]/jdk/jre/lib/i18n.jar[ORACLE_HOME]/jdk/jre/lib/rt.jar[ORACLE_HOME]/jdbc/lib/classes12.zip[ORACLE_HOME]/jdbc/lib/nls_charset12.zip[ORACLE_HOME]/sqlj/lib/translator.zip[ORACLE_HOME]/sqlj/lib/runtime12.ziplog_directory and log_level parameters.
Setting these parameters is not required. They influence the logging of Messaging Gateway. If they are not set, the default values are used. For log_directory, the default value is $ORACLE_HOME/mgw/log. For log_level, the default value is 0 for basic logging.
oracle_sid parameter.
Set the oracle_sid parameter in mgw.ora to avoid providing the database connect string when configuring Messaging Gateway connection information. Refer to "Configuring Messaging Gateway Connection Information".
#an example of mgw.ora file log_directory=/private/mgwlog log_level=2 set CLASSPATH=<proper value> set LD_LIBRARY_PATH=<proper value>
To perform gateway administration work, a database user with MGW_ADMINISTRATOR_ROLE privileges must be created.
CREATE USER <admin_user> IDENTIFED BY <admin_password>; GRANT CONNECT, RESOURCE to <admin_user>; GRANT MGW_ADMINISTRATOR_ROLE to <admin_user>;
To establish the gateway agent's connection back to the database, a database user with MGW_AGENT_ROLE privileges must be created.
CREATE USER <agent_user> IDENTIFED BY <agent_password>; GRANT CONNECT, RESOURCE to <agent_user>; GRANT MGW_AGENT_ROLE to <agent_user>;
After the agent user is created, the administration user uses DBMS_MGWADM.DB_CONNECT_INFO to configure Messaging Gateway with the user name, password, and database connect string used by the gateway agent to connect back to database. Use the agent user name and password that are created in "Creating an Agent User: Example". The database connect string parameter can be set to either a new service name in tnsnames.ora (with IPC protocol for better performance) or null. If null, the oracle_sid parameter must be set in mgw.ora.
For release 9.2, always specify a nonnull value for the database connect string parameter when calling DBMS_MGW_DB_CONNECT_INFO( ).
connect <admin_user>/<admin_password> exec dbms_mgwadm.db_connect_info('<agent_user>','<agent_password>', '<agent_ database>');
The following procedure verifies the installation and includes a simple startup and shutdown of the Messaging Gateway agent.
Start the listener for the external procedure and other listeners for the regular database connection.
Run sqlplus <agent_user>/<agent_password>@<agent_database>.
If successful, the gateway agent is able to connect to the database.
To unload Messaging Gateway, do the following:
MGW_BASIC_MSG_T).SYS as SYSDBA, run catnomgw.sql, located in the $ORACLE_HOME/mgw/admin directory.
This drops the database objects used by Messaging Gateway, including the roles, tables, views, packages, object types, and synonyms.
listener.ora and tnsnames.ora.After Messaging Gateway is loaded and set up, it 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 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.
| See Also:
Oracle9i Supplied PL/SQL Packages and Types Reference, |
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 are 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_EXITThe 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 "Modifying the mgw.ora Initialization File" for information on setting the classpath of the Messaging Gateway agent.
| See Also:
Oracle9i Supplied PL/SQL Packages and Types Reference, |
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.
| See Also:
Oracle9i Supplied PL/SQL Packages and Types Reference, |
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 re-created.
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.
| See Also:
Oracle9i Supplied PL/SQL Packages and Types Reference, |
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.2, a schedule is used only for enabling and disabling propagation jobs. The scheduling parameters are not used in release 9.2.
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.2, 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.
Messaging Gateway converts the native message format of the source messaging system to the native message format of the destination messaging system during propagation. Messaging Gateway uses canonical types and an AQ-centric model for the conversion.
When a message is propagated by the gateway, the message is converted from the native format of the source queue to the native format of the destination queue.
A native message contains a message header and a message body. The header contains the fixed header fields that all messages in a messaging system have, such as message properties in Advanced Queuing and the fixed header in MQSeries. The body contains message contents, such as the AQ payload and the MQSeries message body. Messaging Gateway converts both message header and message body components.
Message conversion is done in two stages, as shown in Figure 18-2. A message is converted from the native format of the source queue to the gateway internal message format first, and then from the internal message format to the native format of the destination queue.
The gateway agent uses an internal message format consisting of a header that is the same as the AQ message properties and a body that is an object of the gateway canonical types.
Messaging Gateway defines canonical types to support message conversion between Advanced Queuing and non-Oracle messaging systems. A canonical type is a message type representation in the form of a PL/SQL abstract data type (ADT) in the Oracle9i database. In release 9.2, the canonical type MGW_BASIC_MSG_T supports conversion between Advanced Queuing and MQSeries.
MGW_BASIC_MSG_T is used to represent messages that have a message header and a TEXT or RAW (bytes) message body. The message header is represented as a set of {name,value} pairs, which are objects of the MGW_NAME_VALUE_T type.
| See Also:
Oracle9i Supplied PL/SQL Packages and Types Reference, |
Native AQ messages consist of AQ message properties and a message payload of either RAW or a user-defined ADT type.
The Messaging Gateway agent converts messages between the native AQ message format and the internal message format. Figure 18-3 illustrates the message conversion performed by the AQ driver.
For outbound propagation, after dequeuing a message from an AQ queue, the gateway agent constructs an internal message by mapping the AQ message properties of the AQ message to the AQ message properties of the internal message and converting the AQ payload to an object of the canonical type.
For inbound propagation, after receiving an internal message from a non-Oracle driver, the gateway agent converts the canonical message to the AQ payload and then enqueues a message with that payload and the internal AQ message properties.
The agent can directly enqueue and dequeue messages with a payload of RAW or SYS.MGW_BASIC_MSG_T to and from AQ queues. The agent provides automatic mapping between the two payload types and the canonical type. For a payload type other than RAW or SYS.MGW_BASIC_MSG_T type, a user-supplied transformation must be provided for conversion between the AQ payload type and the canonical type.
In general, for outbound propagation, the AQ payload type or output of a user-supplied transformation must be either RAW or SYS.MGW_BASIC_MSG_T. For inbound propagation, the AQ payload or input type of a user-supplied transformation must be either RAW or SYS.MGW_BASIC_MSG_T.
For outbound propagation, the following rules apply:
RAW is always mapped to an MGW_BASIC_MSG_T canonical message with a RAW body. MGW_BASIC_MSG_T.header is set to NULL. This never results in a message conversion failure.For inbound propagation, the following rules apply:
MGW_BASIC_MSG_T canonical message is mapped as follows:
RAW body of size <= 32k, the RAW body is mapped directly to the RAW payload. This never results in a message conversion failure.RAW body of size > 32k, message conversion fails.TEXT body, message conversion fails.TEXT and RAW body, message conversion fails.For outbound propagation, the following rules apply:
SYS.MGW_BASIC_MSG_T is always mapped to an MGW_BASIC_MSG_T canonical message.RAW body, if both small and large values are set, message conversion fails.TEXT body, if both small and large values are set, message conversion fails.For inbound propagation, the following rules apply:
MGW_BASIC_MSG_T canonical message is mapped directly. This never results in a message conversion failure.Messaging Gateway can use AQ message transformation to convert between an AQ queue payload and a gateway canonical type. After a transformation is created using the DBMS_TRANSFORM package, a Messaging Gateway administrator can use DBMS_MGWADM.ADD_SUBSCRIBER and DBMS_MGWADM.ALTER_SUBSCRIBER to configure a gateway subscriber to use the transformation.
For outbound propagation, the transformation is invoked when the gateway agent dequeues messages from the AQ queue. For inbound propagation, the transformation is invoked when the gateway agent enqueues messages to the AQ queue.
The transformation is always in the context of the gateway agent, which means that the gateway agent user must have execute privileges on the transformation function and the AQ payload type. This can be accomplished by granting the EXECUTE privilege to PUBLIC, or by granting the EXECUTE privilege directly to the gateway agent user.
The Messaging Gateway MQSeries driver converts between the internal message format and the MQSeries native message format. MQSeries native messages consist of a fixed message header and a message body. The message body is treated as either a TEXT value or RAW (bytes) value.
Figure 18-4 illustrates the message conversion performed by the MQSeries driver. For outbound propagation, the driver maps the AQ message properties and canonical message to a native message having a fixed header and message body. For inbound propagation, the driver maps a native message to a set of AQ message properties and a canonical message.
For outbound propagation, an MGW_BASIC_MSG_T canonical message is mapped to an MQSeries native message as follows:
MGW_BASIC_MSG_T.header attribute of the canonical message.
Refer to Table 18-1 for the default mapping for certain MQSeries header fields based on the AQ message properties, if a value is not specified.
The driver looks in MGW_BASIC_MSG_T.header for the {name,value} pairs described in Table 18-4 and, for each one found, uses that value for the MQSeries header field. Any {name,value} pairs with an unrecognized name or incorrect value type are ignored.
TEXT body, the MQSeries format header field is set to MQFMT_STRING and the message body is set to the TEXT value.RAW body, the MQSeries format header field is set to "MGW_Byte" and the message body is set to the RAW value.TEXT and RAW body, message conversion fails.TEXT nor RAW body, no message body is set and the MQSeries format header field is MQFMT_NONE.For inbound propagation, the MQSeries native message is mapped to an MGW_BASIC_MSG_T canonical message as follows:
MGW_BASIC_MSG_T.header attribute of the canonical message is set to {name,value} pairs based on the MQSeries header fields, as described in Table 18-4.MQFMT_STRING, the MQSeries message body is treated as TEXT and its value is mapped to MGW_BASIC_MSG_T.text_body. For any other format value, the message body is treated as RAW and its value is mapped to MGW_BASIC_MSG_T.raw_body.Messaging Gateway provides default mappings between AQ message properties and non-Oracle message header fields that have a counterpart in AQ message properties with the same semantics. Where Messaging Gateway does not provide a mapping, the message header fields are set to a default value, usually the default value defined by the messaging system.
Messaging Gateway defines {name, value} pairs for AQ message properties and the header fields of non-Oracle messaging systems to convert native message headers and allow users to override the default values. The {name, value} pairs are called header properties. Whether or not you can access the header properties for a given propagation job depends on the messaging systems involved and the AQ payload type or transformation.
Table 18-1 describes the default mapping between AQ message properties and MQSeries header fields. (Refer to "Notes on Table 18-1" for an explanation of the numbers in parentheses.)
Table 18-2 defines the Messaging Gateway {name,value} pairs used to describe the AQ message properties. The header property names for the AQ properties are prefixed with "MGW_AQ_".
When a message is dequeued from an AQ queue, the AQ driver generates {name,value} pairs based on the dequeued message header. When a message is enqueued, the AQ driver sets the AQ message properties from {name,value} pairs for these properties.
When a message is enqueued to an AQ queue, the AQ driver sets the default values for the AQ message properties that have no default mappings (refer to Table 18-1). Corresponding header properties are set as shown in Table 18-3.
| AQ Message Property Name | Default Value |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This section describes the message properties supported for the MQSeries messaging system. Table 18-4 defines the Messaging Gateway {name,value} pairs used to describe the MQSeries header properties. (Refer to "Notes on Table 18-4" for an explanation of the numbers in parentheses.) The Messaging Gateway names for the MQSeries properties are prefixed with "MGW_MQ_".
When a message is dequeued from the MQSeries messaging system, the MQSeries driver generates {name,value} pairs based on the dequeued message header and stores them in the header part of the canonical message of the MGW_BASIC_MSG_T type. When a message is enqueued to MQSeries, the MQSeries driver sets the message header and enqueue options from {name,value} pairs for these properties stored in the header part of the MGW_BASIC_MSG_T canonical message.
MGW_MQ_accountingToken is set for an outgoing message, MQSeries overrides its value unless MGW_MQ_putMessageOptions is set to the MQSeries constant MQPMD_SET_ALL_CONTEXT.MGW_MQ_putMessageOptions is used as the putMessageOptions argument to the MQSeries Base Java Queue.put() method. It is not part of the MQSeries header information and therefore is not an actual message property.
The value for the openOptions argument of the MQSeries Base Java MQQueueManager.accessQueue method is specified when the MQSeries queue is registered using the DBMS_MGWADM.REGISTER_FOREIGN_QUEUE call. Dependencies may exist between the two. For instance, for MGW_MQ_putMessageOptions to include MQPMD_SET_ALL_CONTEXT, the MQ_openMessageOptions queue option must include MQOO_SET_CONTEXT.
The gateway agent adds the value MQPMO_SYNCPOINT to any value that you can specify.
Table 18-5 describes the default values set by the gateway agent for the MQSeries message header when a message is enqueued in an MQSeries queue. For all other header fields, the gateway agent does not set a default value.
| MQSeries Property Name | Default Value |
|---|---|
|
|
|
|
|
|
The following propagation scenarios exemplify the use of header properties.
Consider an outbound propagation job from an AQ queue to an MQSeries queue. Because the MQSeries driver supports only the MGW_BASIC_MSG_T type, the propagation job must be configured so that the AQ driver converts the AQ payload to an MGW_BASIC_MSG_T canonical message. To accomplish this, either the source queue payload type must be SYS.MGW_BASIC_MSG_T, or a transformation whose output (to) type is SYS.MGW_BASIC_MSG_T must be supplied.
For outbound propagation, use the MGW_BASIC_MSG_T.header attribute to specify native message header properties that are used when the message is enqueued to the destination queue. In this example, it will contain {name,value} pairs for MQSeries header properties, as described in Table 18-4.
Although the AQ driver generates {name,value} pairs for the AQ message properties (refer to Table 18-2), the information is lost because the MQSeries message format does not allow you to specify user-defined message property information.
For an inbound propagation job from an MQSeries queue to an AQ queue, the MQSeries driver always converts its native message to an MGW_BASIC_MSG_T canonical message. Therefore, the propagation job should be configured so that the AQ driver converts the canonical message to a SYS.MGW_BASIC_MSG_T payload type. To accomplish this, either the destination queue payload type must be SYS.MGW_BASIC_MSG_T, or a transformation whose input (from) type is SYS.MGW_BASIC_MSG_T must be supplied.
When used for inbound propagation, the MGW_BASIC_MSG_T.header attribute contains {name,value} pairs for the native message header properties of the message dequeued from the source queue. In this example, it will contain {name,value} pairs for MQSeries header properties, as described in Table 18-4.
Because the MQSeries native message format does not allow you to specify user-defined message property information, you cannot specify values that the gateway MQSeries driver interprets as values to use for AQ message properties. As a result, the AQ message properties of the message enqueued to the destination queue are based on the default mappings described in Table 18-1 and the default values for the remaining (nonmapped) AQ properties.
This section provides examples of how to set up propagation between AQ queues with ADT payloads and foreign queues using XML messages.
The messages to propagate in the examples are book orders. The payload type of the AQ queue, AQ_book_orders, is book_order_typ. The foreign queue, FQ_book_orders, is capable of storing XML documents.
The following PL/SQL script creates entities in the Oracle database for the two inbound and outbound propagation examples that follow. Assume that the script is run by database user mgwuser.
-- create the type book_order_typ CREATE OR REPLACE TYPE book_order_typ AS OBJECT ( order_no number, book_name varchar2(100), book_isbn varchar2(15), book_amount number, payment varchar2(30), ship_addr varchar2(160), order_date date ); / -- grant privilege to PUBLIC GRANT EXECUTE ON book_order_typ to PUBLIC; BEGIN -- create queue table dbms_aqadm.create_queue_table( queue_table => `book_order_qtab', queue_payload_type => `book_order_typ', multiple_consumers => TRUE, compatible => `8.1'); -- create the queue dbms_aqadm.create_queue( queue_name => 'AQ_book_orders', queue_table => `book_order_qtab'); -- start the queue dbms_aqadm.start_queue(`AQ_book_orders'); END; /
The message system link called fqlink, which connects to a third-party messaging system, should be created by calling dbms_mgwadm.create_msgsystem_link( ). The foreign queue, FQ_book_orders, of the third-party messaging system should be registered by calling dbms_mgwadm.register_foreign_queue( ).
This example sets up propagation to move book order messages from the AQ queue, AQ_book_orders, to the foreign queue, FQ_book_orders, in the form of XML documents. Users can use the package DBMS_XMLSCHEMA to generate an XML schema from the ADT book_order_typ to parse and process the XML messages at the third-party messaging system side.
The following script defines a function and a transformation to convert an AQ book order message to an XML document that is stored in an object of the canonical type sys.mgw_basic_msg_t. Run the script as user mgwuser.
-- create a transformation function CREATE OR REPLACE FUNCTION fnc_order2basic (book_order IN book_order_typ) RETURN sys.mgw_basic_msg_t IS v_xml XMLType; v_text varchar(2000); -- assume book orders in XML document -- are less than 2000 char long. v_basic sys.mgw_basic_msg_t; BEGIN -- create a XMLType object from the book_order v_xml := XMLType.createXML(book_order, null, null); -- convert the XMLType object to XML document (text) v_text := v_xml.getStringVal(); -- store the XML document in a mgw_basic_msg_t obejct v_basic := sys.mgw_basic_msg_t.construct; v_basic.text_body := sys.mgw_text_value_t(v_text, null); return v_basic; END fnc_order2basic; / -- grant execute privilege to PUBLIC in order for the agent to be able to call it GRANT EXECUTE on fnc_order2basic to PUBLIC; -- create a transformation with the function BEGIN dbms_transform.create_transformation( schema => `mgwuser', name => `order2basic', from_schema => `mgwuser', from_type => `book_order_typ', to_schema => `sys', to_type =>'mgw_basic_msg_t', transformation => `mgwuser.fnc_order2basic(source.user_data)'); END; /
Run the following script as a user that has MGW_ADMINSTRATOR_ROLE privilege to create an outbound propagation job.
-- create an outbound propagation with the transformation BEGIN dbms_mgwadm.add_subscriber( subscriber_id => `sub_aq2fq', propagation_type => dbms_mgwadm.outbound_propagation, queue_name => `mgwuser.AQ_book_orders', destination => `FQ_book_orders@fqlink', transformation => `mgwuser.order2basic'); dbms_mgwadm.schedule_propagation( schedule_id => `sch_aq2fq', propagation_type => dbms_mgwadm.outbound_propagation, source => `mgwuser.AQ_book_orders', destination => `mgwuser.order2basic'); END; /
After the preceding scripts run successfully, all book order messages sent to the AQ queue are propagated to the third-party queue as XML documents conforming to the XML schema associated with the PL/SQL type book_order_typ.
This example sets up propagation to move book orders, which are XML documents conforming to the XML schema associated with the PL/SQL type book_order_typ, from the foreign queue, FQ_book_orders, to the AQ queue, AQ_book_orders. Users should use the package DBMS_XMLSCHEMA to generate XML schema from the ADT book_order_typ to generate valid XML book order messages.
The following script defines a function and a transformation to convert a book order in the form of an XML document stored in an object of the canonical type sys.mgw_basic_msg_t to an object of ADT book_order_typ. Run the script as mgwuser.
-- create a transformation function CREATE OR REPLACE FUNCTION fnc_basic2order(basic IN sys.mgw_basic_msg_t) RETURN book_order_typ IS v_xml XMLType; v_text varchar(2000); -- assume book orders in XML document -- are less than 2000 char long v_order book_order_typ; BEGIN v_text := basic.text_body.small_value; v_xml := XMLType.createXML(v_text); v_xml.toObject(v_order); return v_order; END fnc_basic2order; / -- grant execute privilege to PUBLIC in order for the agent to be able to call it GRANT EXECUTE on fnc_basic2order to PUBLIC; -- create a transformation with the function BEGIN dbms_transform.create_transformation( schema => `mgwuser', name => `basic2order', from_schema => `sys', from_type => `mgw_basic_msg_t', to_schema => `mgwuser', to_type => `book_order_typ', transformation => `mgwuser.fnc_basic2order(source.user_data)'); END; /
Run the following script as a user with MGW_ADMINSTRATOR_ROLE privilege to create an inbound propagation job.
-- create an inbound propagation with the transformation BEGIN dbms_mgwadm.add_subscriber( subscriber_id => `sub_fq2aq', propagation_type => dbms_mgwadm.inbound_propagation, queue_name => `FQ_book_orders@fqlink'', destination => `mgwuser.AQ_book_orders', transformation => `mgwuser.basic2order'); -- create a schedule for the inbound propagation dbms_mgwadm.schedule_propagation( schedule_id => `sch_fq2aq', propagation_type => dbms_mgwadm.inbound_propagation, source => `FQ_book_orders@fqlink', destination => `mgwuser.AQ_book_orders'); END; /
After the preceding scripts run successfully, all book order messages sent to the third-party queue as XML documents conforming to the XML schema associated with the PL/SQL type book_order_typ are propagated to the AQ queue.
Messaging Gateway can get additional initialization information from a text file that is read when the Messaging Gateway agent starts. This initialization file is optional, although it is recommended for setting the environment needed by the Messaging Gateway agent. For example, it may be easier to use the initialization file to set the library path and classpath since these typically need to include paths for shared libraries and Java classes needed to access the Oracle database as well as the non-Oracle messaging systems.
Name: mgw.ora
Location: <ORACLE_HOME>/mgw/admin
The Messaging Gateway initialization file contains lines for setting initialization parameters, environment variables, and Java properties. Each entity must be specified on one line; it is not possible, for example, for an initialization parameter specification to span multiple lines. Leading whitespace is trimmed in all cases.
Note: Any example that follows must consist of only one line in the initialization file, though in this document it may appear otherwise.
<name>=<value><NL>" format where <name> represents the parameter name, <value> represents its value and <NL> represents a new line. Example: log_level = 0CLASSPATH and LD_LIBRARY_PATH are set so the Messaging Gateway agent can find the required libraries, shared objects, Java classes, and so on. Environment variables are specified by lines having a "set <env var>= <value><NL>" or "setenv <env var>=<value><NL>" format where <env var> represents the name of the environment variable to set, <value> represents the value of the environment variable, and <NL> represents a new line. For example: set classpath = /myOracleHome/mgw/lib/mgw.jar:<plus_other_required_files>"setJavaProp <prop name>=<value><NL>" format where <prop name> represents the name of the Java property to set, <value> represents the value of the Java property, and <NL> represents a new line character. For example: setJavaProp java.compiler = none# character as the first character of the line.Specifies the directory where the Messaging Gateway log/trace file will be created.
log_directory = <value>
<ORACLE_HOME>/mgw/log
log_directory = /private/mgwlog
Specifies the level of logging detail recorded by the Messaging Gateway agent. The logging level can be dynamically changed by the dbms_mgwadm.set_log_level API while the agent is running. It is recommended that log level 0 be used at all times.
log_level = <value>
0 for basic logging; equivalent to dbms_mgwadm.BASIC_LOGGING
1 for lite tracing; equivalent to dbms_mgwadm.TRACE_LITE_LOGGING
2 for high tracing; equivalent to dbms_mgwadm.TRACE_HIGH_LOGGING
3 for debug tracing; equivalent to dbms_mgwadm.TRACE_DEBUG_LOGGING
basic logging (0)
log_level = 0
Since the Messaging Gateway process environment is not under the direct control of the user, certain environment variables should be set using the initialization file. They are set using the set parameter as described in "Modifying the mgw.ora Initialization File". The environment variables currently used by the Messaging Gateway agent are CLASSPATH, LD_LIBRARY_PATH, MGW_PRE_PATH, and ORACLE_SID.
Each of the following examples must consist of only one line in the initialization file, although in this document it may appear otherwise.
Used by the Java Virtual Machine to find Java classes needed by the MGW agent.
set CLASSPATH=<value>
The following example indicates classes that must be included for Messaging Gateway propagation between Oracle AQ and MQSeries.
set CLASSPATH = /myOracleHome/jdbc/lib/classes12.zip:/myOracleHome/jdk/jre/lib/i18n.jar:/myOracl eHome/jdk/jre/lib/rt.jar:/myOracleHome/sqlj/lib/runtime12.zip/myOracleHome/sqlj/ lib/translator.zip:/myOracleHome/jdbc/lib/nls_ charset12.zip:/myOracleHome/mgw/classes/mgw.jar:/opt/mqm/java/lib/com.ibm.mq.jar :/opt/mqm/java/lib
Used by the MGW process to find external libraries. Not needed for WINDOWS NT.
set LD_LIBRARY_PATH=<value>
The following example indicates paths to libraries that may be needed by the Messaging Gateway for propagation between Oracle AQ and MQSeries
set LD_LIBRARY_PATH = /myOracleHome/jdk/jre/lib/sparc:/myOracleHome/rdbms/ib:/myOracleHome/lib:/opt/mq m/java/lib
Appended to the front of the path inherited by the Messaging Gateway process. For WINDOWS NT, this variable must be set to indicate where the library jvm.dll is found. It is not currently necessary for other operating systems.
set MGW_PRE_PATH=<value>
The following example indicates where the library may be found.
set MGW_PRE_PATH=\myOracleHome\jdk\jre\bin\classic
May be used when a service name is not specified when configuring the Messaging Gateway.
set ORACLE_SID=<value>
set ORACLE_SID=my_sid
None are currently used.
|
 Copyright © 1996, 2002 Oracle Corporation. All Rights Reserved. |
|