Oracle | DBMS

Oracle DBMS_UMF Version 21c

General Information

Library Note

Morgan's Library Page Header

ACE Director Alum Daniel Morgan, founder of Morgan's Library, is scheduling complimentary technical Workshops on Database Security for the first 30 Oracle Database customers located anywhere in North America, EMEA, LATAM, or APAC that send an email to asra_us@oracle.com. Request a Workshop for your organization today.

Purpose Universal Message Format, UMF, Provides an interface for deploying the Remote Management Framework (RMF) for an Oracle Database. The RMF is used for collecting Oracle Database performance statistics. It provides functions to create and manage UMF topologies. Specifically, it provides calls to create/drop topologies and to modify a topology by adding/removing nodes and links. It also provides calls to manage services (such as AWR) running on nodes and to view/validate a topology. API calls for a given topology must be executed on the target for that topology.

AUTHID DEFINER

Constants

Name	Data Type	Value
SERVICE_TYPE_AWR	NUMBER	0

Data Types

Dependencies

DBMS_ASSERT	DBMS_UMF_LIB	UMF$_REGISTRATION
DBMS_STANDARD	DBMS_WORKLOAD_REPOSITORY	UMF$_SERVICE
DBMS_SYS_ERROR	DUAL	UMF$_TOPOLOGY
DBMS_UMF_INTERNAL	UMF$_LINK

Documented Yes

Exceptions

Error Code	Reason
ORA-20501	Remote UMF is disabled

First Available 12.2

Security Model Owned by SYS with EXECUTE granted to the DBA and SYSUMF_ROLE roles.

The SYS$UMF user is the default database user that has all the privileges to access the system-level RMF views and tables. All the AWR related operations in RMF can be performed only by the SYS$UMF user. The SYS$UMF user is locked by default and it must be unlocked before deploying the RMF topology.

You need to provide password for the SYS$UMF user when creating database links in the RMF topology. If the password for the SYS$UMF user is changed, all the database links in the RMF topology must be recreated.

Source {ORACLE_HOME}/rdbms/admin/dbmsumf.sql

Subprograms

CONFIGURE_NODE	GET_NODE_ID_LOCAL	QUERY_NODE_INFO
CREATE_LINK	GET_NODE_NAME_LOCAL	REGISTER_NODE
CREATE_TOPOLOGY	GET_TARGET_ID	SWITCH_DESTINATION
DROP_LINK	GET_TOPOLOGY_NAME_LOCAL	UNCONFIGURE_NODE
DROP_TOPOLOGY	QUERY_LINK_INFO	UNREGISTER_NODE
ENABLE_SERVICE

CONFIGURE_NODE

Configure a node for UMF by setting a node name. If input is NULL it will be set to db_unique_name or db_name. Also allows pre-setting the name of the database link to the target, before registration. dbms_umf.configure_node( node_name IN VARCHAR2 DEFAULT NULL, dblink_to_target IN VARCHAR2 DEFAULT NULL);

exec dbms_umf.configure_node('UWPRODA', 'DBL_A2B');

CREATE_LINK

Create a link between two nodes implemented with dblinks: one for each direction. dbms_umf.create_link( topology_name IN VARCHAR2, node_a_name IN VARCHAR2, node_b_name IN VARCHAR2, dblink_a_to_b IN VARCHAR2, dblink_b_to_a IN VARCHAR2);

exec dbms_umf.create_link('UWTOPOL', 'UWPRODA', 'UWPRODB', 'DBL_A2B', 'DBL_B2A');

CREATE_TOPOLOGY

Creates a new topology and designates the system it runs on as the target for that topology dbms_umf.create_topology(topology_name IN VARCHAR2);

-- this is what will happen if you try to create the topology before configuring the nodes

conn sys@orabase as sysdba

      

      SQL> alter user sys$umf identified by sysumf account unlock;

      

      User altered.

      

      SQL> conn sys$umf/sysumf@orcl12c

      Connected.

      

      SQL> exec dbms_umf.create_topology('UWTOPOL');

      *

      ERROR at line 1:

      ORA-20501: Remote UMF is disabled

      ORA-06512: at "SYS.DBMS_UMF_INTERNAL", line 34

      ORA-06512: at "SYS.DBMS_UMF", line 612

      ORA-06512: at line 1

DROP_LINK

Delete the link between nodes A and B dbms_umf.drop_link( topology_name IN VARCHAR2, node_a_name IN VARCHAR2, node_b_name IN VARCHAR2);

exec dbms_umf.drop_link('UWTOPOL', 'UWPRODA', 'UWPRODB');

DROP_TOPOLOGY

Deletes a topology and all the associated registrations and links dbms_umf.drop_topology(topology_name IN VARCHAR2);

exec dbms_umf.drop_topology('UWTOPOL');

ENABLE_SERVICE

Enables a service, for example AWR, on a node dbms_umf.enable_service( topology_name IN VARCHAR2, node_name IN VARCHAR2, service_type IN NUMBER);

exec dbms_umf.enable_service('UWTOPOL', 'UWPRODB', dbms_umf.service_type_awr);

GET_NODE_ID_LOCAL

Returns the UMF node ID for the local node dbms_umf.get_node_id_local(topology_name IN VARCHAR2 DEFAULT NULL) RETURN NUMBER;

SELECT dbms_umf.get_node_id_local('UWTOPOL')

      FROM dual;

GET_NODE_NAME_LOCAL

Returns the UMF node name dbms_umf.get_node_name_local RETURN VARCHAR2;

SELECT dbms_umf.get_node_name_local

      FROM dual;

GET_TARGET_ID

Retrieves the target ID of the given topology dbms_umf.get_target_id(topology_name IN VARCHAR2) RETURN NUMBER;

SELECT dbms_umf.get_target_id('UWTOPOL')

      FROM dual;

GET_TOPOLOGY_NAME_LOCAL

Returns the name of the active UMF topology dbms_umf.get_topology_name_local RETURN VARCHAR2;

SELECT dbms_umf.get_topology_name_local

      FROM dual;

QUERY_LINK_INFO

Retrieves the name of the database link that connects two nodes dbms_umf.query_link_info( topology_name IN VARCHAR2, from_node_id IN NUMBER, to_node_id IN NUMBER, link_name OUT VARCHAR2);

DECLARE

       lname VARCHAR2(128);

      BEGIN

        dbms_umf.query_link_info('UWTOPOL',  1, 2, lname);

        dbms_output.put_line(lname);

      END;

      /

QUERY_NODE_INFO

Retrieves registration info for a node. Given the node_name, it returns the topology name and the node ID

Overload 1 dbms_umf.query_node_info( topology_name IN VARCHAR2, node_name IN VARCHAR2, node_id OUT NUMBER);

set serveroutput on

      

      DECLARE

       nid NUMBER;

      BEGIN

        dbms_umf.query_node_info('UWTOPOL, 'UWPRODB', nid);

        dbms_output.put_line(TO_CHAR(nid));

      END;

      /

Overload 2 dbms_umf.query_node_info(node_id IN NUMBER, topology_name OUT VARCHAR2, node_name OUT VARCHAR2);

set serveroutput on

      

      DECLARE

       tname VARCHAR2(128);

       nname VARCHAR2(128);

      BEGIN

        dbms_umf.query_node_info(1, tname, nname);

        dbms_output.put_line(tname);

        dbms_output.put_line(nname);

      END;

      /

REGISTER_NODE

Registers a node with a given topology. Nodes are identified by their node name, which can be any string, with the constraint that the tuple
[topology_name, node_name] must be unique
Overload 1

Also accepts as input the names of the two dblinks, to and from the target. The procedure returns the auto-generated node id for the new registration (which is also stored in umf$_registration).

dbms_umf.register_node (

      topology_name       IN VARCHAR2,

      node_name           IN VARCHAR2,

      dblink_to_node      IN VARCHAR2 DEFAULT NULL,

      dblink_from_node    IN VARCHAR2 DEFAULT NULL,

      as_source           IN VARCHAR2 DEFAULT 'TRUE',

      as_candidate_target IN VARCHAR2 DEFAULT 'FALSE')

      RETURN NUMBER;

TBD

Invokes the function without returning the node_id

Overload 2 dbms_umf.register_node ( topology_name IN VARCHAR2, node_name IN VARCHAR2, dblink_to_node IN VARCHAR2 DEFAULT NULL, dblink_from_node IN VARCHAR2 DEFAULT NULL, as_source IN VARCHAR2 DEFAULT 'TRUE', as_candidate_target IN VARCHAR2 DEFAULT 'FALSE');

TBD

Invokes the function without returning the node_id

Overload 3 dbms_umf.register_node ( topology_name IN VARCHAR2, node_name IN VARCHAR2, dblink_to_node IN VARCHAR2 DEFAULT NULL, dblink_from_node IN VARCHAR2 DEFAULT NULL, as_source IN VARCHAR2 DEFAULT 'TRUE', as_candidate_target IN VARCHAR2 DEFAULT 'FALSE', node_id OUT VARCHAR2);

TBD

SWITCH_DESTINATION

Designates the node where the command is executed as the new UMF destination of the given topology. The procedure fails if the designated node is not capable of performing the target role dbms_umf.switch_destination( topology_name IN VARCHAR2, force_switch IN BOOLEAN DEFAULT TRUE);

exec dbms_umf.switch_destination('UWTOPOL', FALSE);

UNCONFIGURE_NODE

Clear a node's internal configuration dbms_umf.unconfigure_node;

exec dbms_umf.unconfigure_node;

UNREGISTER_NODE

Removes the registration info for the node identified by the tuple [topology_name, node_name] dbms_umf. unregister_node ( topology_name IN VARCHAR2, node_name IN VARCHAR2);

exec dbms_umf.unregister_node('UWTOPOL', 'UWPRODB');