dbms_mgwadm and dbms_mgwmsg Tips

Oracle Tips by Burleson Consulting

October 14, 2013

19.2.1 Starting the Oracle Messaging Gateway Agent

After the Messaging Gateway agent is configured, you can start the agent
with DBMS_MGWADM.STARTUP, as shown in Example 19-4.
Example 19-4 Starting the Messaging Gateway Agent
SQL> exec dbms_mgwadm.startup;

You can use the MGW_GATEWAY view to check the status of the Messaging Gateway agent,
as described in Chapter 21, "Monitoring Oracle Messaging Gateway".

19.2.2 Shutting Down the Oracle Messaging Gateway

Agent
You can use DBMS_MGWADM.SHUTDOWN to shut down the Messaging Gateway agent, as
shown in Example 19-5.
Example 19-5 Shutting Down the Messaging Gateway Agent
SQL> exec dbms_mgwadm.shutdown;

You can use the MGW_GATEWAY view to check if the Messaging Gateway agent has shut
down successfully, as described in Chapter 21, "Monitoring Oracle Messaging Gateway".

Oracle Streams enable the propagation between two Oracle Stream Advanced
Queues. This is an Oracle-Oracle configuration. Oracle Messaging gateway is a

feature that makes the communication between Oracle Streams Advanced

Queue and non-Oracle applications like Websphere and other applications tools
possible.
For the purpose of configuring Messaging Gateway, two packages were
created: dbms_mgwadm and dbms_mgmsg. In the next codes, how to configure
Messaging Gateway to be used in conjunction with Websphere will be reviewed.
The Oracle Messaging gateway has two main components: the Agent and
the dbms_mgwadm administration package. The first thing to do is to create
these packages by running the catmgw.sql script which is found in
the $ORACLE_HOME/mgw/admin directory.
Next, configure the listener.ora and tnsnames.ora in order to start the
Messaging Gateway Agent. Some examples of how they should be configured
are below:

Code 11.12 ? dbms_mgw.sql

conn sys@ora11g as sysdba

Connected to:
Oracle 11g Enterprise Edition Release 11.2.0.1.0 - Production
With the Partitioning, Oracle Label Security, OLAP, Data Mining,
Oracle Database Vault and Real Application Testing options
--Check your listener.ora and tnsnames.ora and validate if they have the proper values
necessary to start the agent
--tnsnames.ora
mgw_agent=
(description =
(address_list =
(address = (protocol=ipc)(key=extproc)))
(connect_data = (sid=mgwextproc) (presentation=RO)))
agent_service =
(description =
(address_list =
(address=
(protocol=ipc)( key=extproc)))
(connect_data =
(sid=sourcedb)(presentation=RO)))
--listener.ora
listener =
(description =
(address = (protocol = tcp)(host = 10.10.10.113)(port = 1521))
(address = (protocol = ipc)(key =extproc))
)
sid_list_listener =
(sid_list =
(sid_desc =
(global_dbname = dbms)
(ORACLE_HOME = /u01/app/oracle/product/11.2.0/db11g)
(sid_name = dbms)
)
(sid_desc=
(sid_name= mgwextproc)
(envs="ld_library_path=/u01/app/oracle/product/11.2.0/db11g/jdk/jre/lib/i386
:/u01/app/oracle/product/11.2.0/db11g/jdk/jre/lib/i386/server:/u01/app/oracl

e/product/11.2.0/db11g/lib")
(ORACLE_HOME=/u01/app/oracle/product/11.2.0/db11g)
(program = extproc))
)

Check the mgw.ora file that is used by the agent. This file is located in
the$ORACLE_HOME/mgw/admin directory and will look something like the lines
below:
set ld_library_path=/u01/app/oracle/product/11.2.0/db11g/jdk/jre/lib/i386:/u01/a
pp/oracle/product/11.2.0/db11g/jdk/jre/lib/i386/server:/u01/app/oracle/produ
ct/11.2.0/db11g/rdbms/lib:/u01/app/oracle/product/11.2.0/db11g/lib
log_directory=/u01/app/oracle/product/11.2.0/db11g/mgw/log
log_level = 0
set classpath=/u01/app/oracle/product/11.2.0/db11g/jdbc/lib/ojdbc5.jar://u01/app
/oracle/product/11.2.0/db11g/jdk/jre/lib/i18n.jar://u01/app/oracle/product/1
1.2.0/db11g/jdk/jre/lib/rt.jar://u01/app/oracle/product/11.2.0/db11g/sqlj/li
b/runtime12.jar://u01/app/oracle/product/11.2.0/db11g/jlib/orai18n.jar://u01
/app/oracle/product/11.2.0/db11g/jlib/jta.jar://u01/app/oracle/product/11.2.
0/db11g/rdbms/jlib/jmscommon.jar://u01/app/oracle/product/11.2.0/db11g/rdbms
/jlib/aqapi.jar:/opt/mqm/java/lib/com.ibm.mqjms.jar:/opt/mqm/java/lib/com.ib
m.mq.jar:/opt/mqm/java/lib:/opt/mqm/java/lib/connector.jar

Create a user that will have Messaging Gateway permissions and configure
connection information used by the agent to connect to the database.
create user mgw identified by mgw;
grant connect,mgw_agent_role to mgw;
begin
dbms_mgwadm.db_connect_info(
username => 'mgw',
password => 'mgw',
database => 'sourcedb');
end;
/

To check agent information, query the mgw_gateway view.

col agent_database for a10
col agent_status for a10
col agent_user for a10
col max_connections for 99
select
max_memory,
max_connections,
agent_user,
agent_database,
agent_status
from
mgw_gateway;

Now start the agent by using the start_agent procedure. Note that after starting
theagent_status, the column on table mgw$_gateway will change in value from 0
to 1.
begin
dbms_mgwadm.startup;
end;
/
--Shutdown the agent

begin
dbms_mgwadm.shutdown(
sdmode => dbms_mgwadm.shutdown_immediate);
end;
/

Now it is time to create a particular queue table and a queue for this process.
After this has been created, start the queue.
begin
dbms_aqadm.create_queue_table(
queue_table => 'mgw_q_table',
multiple_consumers=>TRUE,
queue_payload_type =>'sys.anydata' ,
compatible => '8.1');
dbms_aqadm.create_queue(
queue_name => 'mgw_q',
queue_table => 'mgw_q_table');
end;
/
--Start the queue
begin
dbms_aqadm.start_queue (queue_name => 'mgw_q');
end;
/

Now that the queue has been created and started, the next step will be creating
the link that is responsible for connecting the database to the Websphere
application. This link is created using the create_msgsystem_link procedure:
declare
v_mgw_properties sys.mgw_properties;
v_mgw_mq_properties sys.mgw_mqseries_properties;
begin
v_mgw_mq_properties := sys.mgw_mqseries_properties.construct();
v_mgw_mq_properties.max_connections := 5;
v_mgw_mq_properties.interface_type := dbms_mgwadm.mqseries_base_java_interface;
v_mgw_mq_properties.username := 'webuser';
v_mgw_mq_properties.password := 'web123';
v_mgw_mq_properties.hostname := '10.10.10.114';
v_mgw_mq_properties.port
:= 5522;
v_mgw_mq_properties.channel := 'system.def.svrconn';
v_mgw_mq_properties.queue_manager := 'mgw_q_manager';
v_mgw_mq_properties.outbound_log_queue := 'mgw_out_log_q';
v_mgw_mq_properties.inbound_log_queue := 'mgw_in_log_q';
dbms_mgwadm.create_msgsystem_link(
linkname => 'mgw_link',
properties => v_mgw_mq_properties,
options => v_mgw_properties,
comment => 'This is the link to connect to Websphere.' );
end;
/

The link just created can be checked by querying the mgw$_links table
or mgw_links view as follows:
col link_name for a10
select
link_name,
agent_name
from
mgw$_links;

select
link_name,
link_type,
agent_name
from
mgw_links;
After creating the link, we register the non-Oracle queue in the Messaging Gateway.
begin
dbms_mgwadm.register_foreign_queue(
name => 'mgw_fk_queue',
linkname => 'mgw_link',
provider_queue => 'mgw_fk_queue',
domain => dbms_mgwadm.domain_queue,
comment => 'Foreign Link Test.');
end;
/

Check the foreign queue by querying the mgw_foreign_queues view:

col name for a14
col provider_queue for a15
select
name,
link_name,
provider_queue,
domain
from
mgw_foreign_queues;
NAME
LINK_NAME PROVIDER_QUEUE DOMAIN
-------------- ---------- --------------- -----mgw_fk_queue
mgw_link
mgw_fk_queue
queue

Finally , after creating the link that will guide messages to Websphere, a job is
created
using
the create_job procedure
which
replaced
the
old add_subscriber and schedule_propagation. This job is created using the
following scripts.
begin
dbms_mgwadm.create_job(
job_name => 'mgw_job',
propagation_type => dbms_mgwadm.outbound_propagation,
source => 'sys.mgw_q',
destination => 'mgw_fk_queue@mgw_link',
enabled => TRUE,
poll_interval => 10,comments => 'My test mgw Job.');
end;
/
--Check the subscriber using the mgw_subscribers view.
col subscriber_id for a10
col queue_name for a10
col destination for a22
select
subscriber_id,
propagation_type,
queue_name,
destination,
status
from
mgw_subscribers;
--Check job created
col job_name for a10
col source for a10
col status for a10
select

job_name,
propagation_type,
source,
destination,
enabled,
link_name,
status
from
mgw_jobs;

While dbms_mgwadm is used to create and manage Messaging Gateway

configurations,dbms_mgwmsg is a package used to convert message
bodies; for example, converting asys.anydata object, encapsulating a lcr to
a sys.xmltype or functions like nvarray_find_nameused to find a name-value
array for an element.