Oracle | DBMS_ADR

Oracle DBMS_ADR_APP 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 Undocumented: The PL/SQL diagnosability API declared in this package is intended for use by internal non-RDBMS PL/SQL applications only.

AUTHID DEFINER

Constants

Name	Data Type	Value
ODL Message Types
log_msg_type_unknown	INTEGER	1
log_msg_type_incident	INTEGER	2
log_msg_type_error	INTEGER	3
log_msg_type_warning	INTEGER	4
log_msg_type_notification	INTEGER	5
log_msg_type_trace	INTEGER	6
Last Call No Error
NOERROR	NUMBER	0
Default PurgeThreshold
PURGE_DEFAULT_THRESHOLD	NUMBER	90

Data Types call_status NUMBER; call_err_msg VARCHAR2(1024);

Dependencies

ADR_HOME_T	ADR_INCIDENT_T	ADR_LOG_MSG_SUPPL_ATTRS_T
ADR_INCIDENT_CORR_KEYS_T	ADR_LOG_MSG_ARGS_T	ADR_MSG_TEMPLATE_T
ADR_INCIDENT_ERR_ARGS_T	ADR_LOG_MSG_ECID_T	DBMS_ADR_INTERNAL
ADR_INCIDENT_FILES_T	ADR_LOG_MSG_ERRID_T

Documented No

First Available 12.1

Security Model Owned by SYS with EXECUTE granted to the DBA role

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

Subprograms

CREATE_INCIDENT	GET_TRACE_LOCATION	SET_LOG_MSG_TEMPLATE
GET_CALL_ERROR_MSG	RUN_PURGE	SET_TRACEFILE_IDENTIFIER
GET_CALL_STATUS	SET_ADR_HOME	WRITE_LOG
GET_CURRENT_PRECEDENCE	SET_CURRENT_PRECEDENCE	WRITE_TRACE
GET_LOG_LOCATION	SET_EXCEPTION_MODE

CREATE_INCIDENT

Creates an incident in the current ADR Home dbms_adr_app.create_incident( problem_key IN VARCHAR2, /* incident problem key error_facility IN VARCHAR2 DEFAULT NULL, /* error facility error_number IN INTEGER DEFAULT NULL, /* error number error_message IN VARCHAR2 DEFAULT NULL, /* error message error_args IN adr_incident_err_args_t DEFAULT NULL, /* error arguments ecid IN VARCHAR2 DEFAULT NULL, /* execution context id signalling_component IN VARCHAR2 DEFAULT NULL, /* signalling component signalling_subcomponent IN VARCHAR2 DEFAULT NULL, /* signalling subcomp. suspect_component IN VARCHAR2 DEFAULT NULL, /* suspect component suspect_subcomponent IN VARCHAR2 DEFAULT NULL, /* suspect subcomp. correlation_keys IN adr_incident_corr_keys_t DEFAULT NULL, /* correlation keys files IN adr_incident_files_t DEFAULT NULL) /* addnl incident files RETURN adr_incident_t;

TBD

GET_CALL_ERROR_MSG

Returns the error message if the last call to DBMS_ADR_APP API or NULL if no error generated dbms_adr_app.get_call_error_msg RETURN VARCHAR2;

SELECT dbms_adr_app.get_call_error_msg

      FROM dual;

      

      GET_CALL_ERROR_MSG

      -------------------

GET_CALL_STATUS

Returns the status of the last call to the DBMS_ADR_APP API. If the previous call was successful, the value of this call will be NOERROR(0) dbms_adr_app.get_call_status RETURN NUMBER;

SELECT dbms_adr_app.get_call_status

      FROM dual;

      

      GET_CALL_STATUS

      ---------------

GET_CURRENT_PRECEDENCE

Returns the current precedence level set for current ADR Home dbms_adr_app.get_current_precedence RETURN INTEGER;

See SET_CURRENT_PRECEDENCE Demo Below

GET_LOG_LOCATION

Returns the complete path of the log directory in the ADR home dbms_adr_app.get_log_location RETURN VARCHAR2;

SELECT dbms_adr_app.get_log_location

      FROM dual;

      

      GET_LOG_LOCATION

      -------------------------------------------------------------

      /u01/app/oracle/diag/plsqlapp/test21db_iad25g/test21db/alert

GET_TRACE_LOCATION

Returns the complete path of the trace directory in the ADR home dbms_adr_app.get_trace_location RETURN VARCHAR2;

SELECT dbms_adr_app.get_trace_location

      FROM dual;

      

      GET_TRACE_LOCATION

      -------------------------------------------------------------

      /u01/app/oracle/diag/plsqlapp/test21db_iad25g/test21db/trace

RUN_PURGE

Performs an ADR purge though there is no information with respect to the exact meaning of the threshold parameter dbms_adr_app.run_purge(threshold IN NUMBER);

exec dbms_adr.run_purge(1);

      

      PL/SQL procedure successfully completed.

SET_ADR_HOME

Creates a new adr home, including directory creation if they do not exist, that will be current ADR home for all subsequent calls to DBMS_ADR_APP.

Note that this does not allow you to define the location. dbms_adr_app.set_adr_home( product_type IN VARCHAR2 DEFAULT NULL, product_id IN VARCHAR2 DEFAULT NULL, instance_id IN VARCHAR2 DEFAULT NULL, create_dir IN BOOLEAN DEFAULT FALSE, precedence IN INTEGER DEFAULT 0);

exec dbms_adr_app.set_adr_home;

      

      PL/SQL procedure successfully completed.

SET_CURRENT_PRECEDENCE

Sets the current precedence level for the current ADR Home dbms_adr_app.set_current_precedence(precedence IN INTEGER);

SELECT dbms_adr_app.get_current_precedence

      FROM dual;

      

      GET_CURRENT_PRECEDENCE

      ----------------------

                           0

      

      exec dbms_adr_app.set_current_precedence(2);

      

      PL/SQL procedure successfully completed.

      

      SELECT dbms_adr_app.get_current_precedence

      FROM dual;

      

      GET_CURRENT_PRECEDENCE

      ----------------------

                           2

      

      exec  dbms_adr_app.set_current_precedence(0);

      

      PL/SQL procedure successfully completed.

      

      SELECT dbms_adr_app.get_current_precedence

      FROM dual;

      

      GET_CURRENT_PRECEDENCE

      ----------------------

                           0

SET_EXCEPTION_MODE

Sets the package exception mode. If TRUE exceptions will be raised, else suppressed if FALSE dbms_adr_app.set_exception_mode(exc_mode IN BOOLEAN DEFAULT FALSE);

exec dbms_adr_app.set_exception_mode(TRUE);

      

      PL/SQL procedure successfully completed.

SET_LOG_MSG_TEMPLATE

Creates a log message template object which can be used in the write_log API call dbms_adr_app.set_log_msg_template( org_id IN VARCHAR2 DEFAULT NULL, component_id IN VARCHAR2 DEFAULT NULL, instance_id IN VARCHAR2 DEFAULT NULL, hosting_client_id IN VARCHAR2 DEFAULT NULL, msg_group IN VARCHAR2 DEFAULT NULL, host_id IN VARCHAR2 DEFAULT NULL, host_nwaddr IN VARCHAR2 DEFAULT NULL, module_id IN VARCHAR2 DEFAULT NULL, process_id IN VARCHAR2 DEFAULT NULL, thread_id IN VARCHAR2 DEFAULT NULL, user_id IN VARCHAR2 DEFAULT NULL, upstream_comp_id IN VARCHAR2 DEFAULT NULL, downstream_comp_id IN VARCHAR2 DEFAULT NULL, ecid IN adr_log_msg_ecid_t DEFAULT NULL, error_instance_id IN adr_log_msg_errid_t DEFAULT NULL, msg_args IN adr_log_msg_args_t DEFAULT NULL, detail_location IN VARCHAR2 DEFAULT NULL, suppl_detail IN VARCHAR2 DEFAULT NULL, con_uid IN NUMBER DEFAULT NULL, con_id IN NUMBER DEFAULT NULL, con_name IN VARCHAR2 DEFAULT NULL) RETURN adr_msg_template_t;

TBD

SET_TRACEFILE_IDENTIFIER

An API for performing the action
ALTER SESSION SET TRACEFILE_IDENTIFIER = '<identifier_string>'; dbms_adr_app.set_tracefile_identifier(trc_identifier IN VARCHAR2);

exec dbms_adr_app.set_tracefile_identifier('test_plan1');

      

      PL/SQL procedure successfully completed.

WRITE_LOG

used to write log entries in the ODL format to the alert log in the current ADR home dbms_adr_app.write_log( -- Mandatory ODL fields without defaults msg_id IN VARCHAR2, /* message id msg_type IN INTEGER, /* message type msg_level IN INTEGER, /* message level msg_text IN VARCHAR2, /* message text -- Optional ODL fields and mandatory ones with defaults timestamp_originating IN TIMESTAMP WITH TIME ZONE DEFAULT NULL, /* time originating timestamp_normalized IN TIMESTAMP WITH TIME ZONE DEFAULT NULL, /* time normalized org_id IN VARCHAR2 DEFAULT NULL, /* organization id component_id IN VARCHAR2 DEFAULT NULL, /* component id instance_id IN VARCHAR2 DEFAULT NULL, /* instance id hosting_client_id IN VARCHAR2 DEFAULT NULL, /* hosting client id msg_group IN VARCHAR2 DEFAULT NULL, /* message group host_id IN VARCHAR2 DEFAULT NULL, /* host id host_nwaddr IN VARCHAR2 DEFAULT NULL, /* host address module_id IN VARCHAR2 DEFAULT NULL, /* module id process_id IN VARCHAR2 DEFAULT NULL, /* process id thread_id IN VARCHAR2 DEFAULT NULL, /* thread id user_id IN VARCHAR2 DEFAULT NULL, /* user id suppl_attrs IN adr_log_msg_suppl_attrs_t DEFAULT NULL, /* supplemental attributes problem_key IN VARCHAR2 DEFAULT NULL, /* problem key upstream_comp_id IN VARCHAR2 DEFAULT NULL, /* upstream comp. id downstream_comp_id IN VARCHAR2 DEFAULT NULL, /* downstream comp. id ecid IN adr_log_msg_ecid_t DEFAULT NULL, /* execution context id error_instance_id IN adr_log_msg_errid_t DEFAULT NULL, /* error instance id msg_args IN adr_log_msg_args_t DEFAULT NULL, /* message arguments detail_location IN VARCHAR2 DEFAULT NULL, /* detailed location suppl_detail IN VARCHAR2 DEFAULT NULL, /* supplemental detail msg_template_obj IN adr_msg_template_t DEFAULT NULL /* message template object con_uid IN NUMBER DEFAULT NULL, con_id IN NUMBER DEFAULT NULL, con_name IN VARCHAR2 DEFAULT NULL);

TBD

WRITE_TRACE

Write trace lines to the trace file in the current ADR home dbms_adr_app.write_trace(trace_data IN VARCHAR2);

exec dbms_adr_app.write_trace('Testing the new database version 21cR1');

      

      PL/SQL procedure successfully completed.

      

      -- open the most recent .trc files in the directory returned by GET_TRACE_LOCATION