1 PACKAGE dbms_adr AS
2
3 -- **********************************************************************
4 -- ODL message type constants
5 -- These are for use in adr_home_t.log(msg_type => ...)
6 -- **********************************************************************
7
8 log_msg_type_unknown CONSTANT INTEGER := 1; /* Unknown */
9 log_msg_type_incident CONSTANT INTEGER := 2; /* Incident */
10 log_msg_type_error CONSTANT INTEGER := 3; /* Error */
11 log_msg_type_warning CONSTANT INTEGER := 4; /* Warning */
12 log_msg_type_notification CONSTANT INTEGER := 5; /* Notification */
13 log_msg_type_trace CONSTANT INTEGER := 6; /* Trace */
14
15 -- **********************************************************************
16 -- call_status
17 -- This variable holds the status of the last call to the DBMS_ADR
18 -- API. In case the previous call was successful, the value of this
19 -- variable will be NOERROR (0). Otherwise it will have the same value
20 -- as SQLCODE at the time of returning from the DBMS_ADR API call.
21 -- Clients can directly access this variable to get the status.
22 -- ***********************************************************************
23
24 call_status NUMBER;
25
26 -- last call did not return an error
27 NOERROR CONSTANT INTEGER := 0;
28
29 -- **********************************************************************
30 -- call_err_msg
31 -- If the last call to the DBMS_ADR APIs generated an error, this
32 -- variables contains the corresponding error message.
33 -- If the last call was successful, this variable will be NULL.
34 -- Clients can directly access this variable to get the error message.
35 -- **********************************************************************
36
37 call_err_msg VARCHAR2(1024);
38
39
40 -- **********************************************************************
41 -- create_incident
42 -- This routine creates an incident in the current ADR Home,
43 -- which is always the RDBMS ADR home. It returns the incident
44 -- handle, which can be used for further manipulation of the
45 -- incident, e.g. registering additional files in the incident.
46 -- **********************************************************************
47
48 FUNCTION create_incident
49 (
50 problem_key IN VARCHAR2, /* incident problem key */
51 error_facility IN VARCHAR2 DEFAULT NULL, /* error facility */
52 error_number IN INTEGER DEFAULT NULL, /* error number */
53 error_message IN VARCHAR2 DEFAULT NULL, /* error message */
54 error_args IN adr_incident_err_args_t DEFAULT NULL,
55 /* error arguments */
56 ecid IN VARCHAR2 DEFAULT NULL,/* execution context id */
57 signalling_component IN VARCHAR2 DEFAULT NULL,/* signalling component */
58 signalling_subcomponent IN VARCHAR2 DEFAULT NULL, /* signalling subcomp. */
59 suspect_component IN VARCHAR2 DEFAULT NULL, /* suspect component */
60 suspect_subcomponent IN VARCHAR2 DEFAULT NULL, /* suspect subcomp. */
61 correlation_keys IN adr_incident_corr_keys_t DEFAULT NULL,
62 /* correlation keys */
63 files IN adr_incident_files_t DEFAULT NULL
64 /* additional incident files */
65 )
66 RETURN adr_incident_t;
67
68
69 -- **********************************************************************
70 -- write_trace
71 -- This routine is used to write trace lines to the trace file
72 -- in the ADR home.
73 -- **********************************************************************
74
75 PROCEDURE write_trace
76 (
77 trace_data IN VARCHAR2
78 );
79
80
81 -- **********************************************************************
82 -- write_log
83 -- This routine is used to write log entries to the alert log
84 -- in the ADR home.
85 -- **********************************************************************
86
87 PROCEDURE write_log
88 (
89 -- Mandatory ODL fields without defaults
90 msg_id IN VARCHAR2, /* message id */
91 msg_type IN INTEGER, /* message type */
92 msg_level IN INTEGER, /* message level */
93 msg_text IN VARCHAR2, /* message text */
94
95 -- Optional ODL fields and mandatory ones with defaults
96 timestamp_originating IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
97 /* time originating */
98 timestamp_normalized IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
99 /* time normalized */
100 org_id IN VARCHAR2 DEFAULT NULL, /* organization id */
101 component_id IN VARCHAR2 DEFAULT NULL, /* component id */
102 instance_id IN VARCHAR2 DEFAULT NULL, /* instance id */
103 hosting_client_id IN VARCHAR2 DEFAULT NULL, /* hosting client id */
104 msg_group IN VARCHAR2 DEFAULT NULL, /* message group */
105 host_id IN VARCHAR2 DEFAULT NULL, /* host id */
106 host_nwaddr IN VARCHAR2 DEFAULT NULL, /* host address */
107 module_id IN VARCHAR2 DEFAULT NULL, /* module id */
108 process_id IN VARCHAR2 DEFAULT NULL, /* process id */
109 thread_id IN VARCHAR2 DEFAULT NULL, /* thread id */
110 user_id IN VARCHAR2 DEFAULT NULL, /* user id */
111 suppl_attrs IN adr_log_msg_suppl_attrs_t DEFAULT NULL,
112 /* supplemental attributes */
113 problem_key IN VARCHAR2 DEFAULT NULL, /* problem key */
114 upstream_comp_id IN VARCHAR2 DEFAULT NULL, /* upstream comp. id */
115 downstream_comp_id IN VARCHAR2 DEFAULT NULL, /* downstream comp. id */
116 ecid IN adr_log_msg_ecid_t DEFAULT NULL,
117 /* execution context id */
118 error_instance_id IN adr_log_msg_errid_t DEFAULT NULL,
119 /* error instance id */
120 msg_args IN adr_log_msg_args_t DEFAULT NULL,
121 /* message arguments */
122 detail_location IN VARCHAR2 DEFAULT NULL, /* detailed location */
123 suppl_detail IN VARCHAR2 DEFAULT NULL, /* supplemental detail */
124 msg_template_obj IN adr_msg_template_t DEFAULT NULL
125 /* message template object */
126 );
127
128
129 -- **********************************************************************
130 -- set_log_msg_template
131 -- This routine creates a log message template object which can
132 -- be used in the write_log API call. The purpose of the log message
133 -- template object is to avoid have to specify common parameters in
134 -- each call to write_log. When passing a template object, optional
135 -- parameters that were not set explicitly will be copied from the
136 -- template object instead.
137 -- **********************************************************************
138
139 FUNCTION set_log_msg_template
140 (
141 org_id IN VARCHAR2 DEFAULT NULL,
142 component_id IN VARCHAR2 DEFAULT NULL,
143 instance_id IN VARCHAR2 DEFAULT NULL,
144 hosting_client_id IN VARCHAR2 DEFAULT NULL,
145 msg_group IN VARCHAR2 DEFAULT NULL,
146 host_id IN VARCHAR2 DEFAULT NULL,
147 host_nwaddr IN VARCHAR2 DEFAULT NULL,
148 module_id IN VARCHAR2 DEFAULT NULL,
149 process_id IN VARCHAR2 DEFAULT NULL,
150 thread_id IN VARCHAR2 DEFAULT NULL,
151 user_id IN VARCHAR2 DEFAULT NULL,
152 upstream_comp_id IN VARCHAR2 DEFAULT NULL,
153 downstream_comp_id IN VARCHAR2 DEFAULT NULL,
154 ecid IN adr_log_msg_ecid_t DEFAULT NULL,
155 error_instance_id IN adr_log_msg_errid_t DEFAULT NULL,
156
157 msg_args IN adr_log_msg_args_t DEFAULT NULL,
158 detail_location IN VARCHAR2 DEFAULT NULL,
159 suppl_detail IN VARCHAR2 DEFAULT NULL
160 )
161 RETURN adr_msg_template_t;
162
163
164 -- **********************************************************************
165 -- get_trace_location
166 -- This routine returns the complete path of the trace directory in the
167 -- ADR home.
168 -- **********************************************************************
169
170 FUNCTION get_trace_location RETURN VARCHAR2;
171
172
173 -- **********************************************************************
174 -- get_log_location
175 -- This routine returns the complete path of the log directory in the
176 -- ADR home.
177 -- **********************************************************************
178
179 FUNCTION get_log_location RETURN VARCHAR2;
180
181
182 -- **********************************************************************
183 -- set_exception_mode
184 -- This routine sets the exception mode for the package.
185 -- If exception mode is set to true, then all the exceptions
186 -- will be raised to client. If it is set to false, then all the
187 -- exceptions will be suppressed, and the client will not see any
188 -- exception, even if underlying APIs are raising exceptions.
189 --
190 -- Since this is a diagnosability API, clients might not expect these
191 -- API calls to raise their own exceptions.
192 -- By default, exception mode will be set to false.
193 -- Clients can change it any time by calling this function.
194 -- **********************************************************************
195
196 PROCEDURE set_exception_mode
197 (
198 exc_mode IN BOOLEAN DEFAULT FALSE /* exception mode */
199 );
200
201
202 -- **********************************************************************
203 -- migrate_schema
204 -- This routine migrates the ADR home to the current version.
205 --
206 -- Input arguments:
207 -- none
208 -- **********************************************************************
209
210 PROCEDURE migrate_schema;
211
212
213 -- **********************************************************************
214 -- downgrade_schema
215 -- This routine downgrades the ADR home by restoring files.
216 --
217 -- Input arguments:
218 -- none
219 -- **********************************************************************
220
221 PROCEDURE downgrade_schema;
222
223
224 -- **********************************************************************
225 -- recover_schema
226 -- This routine tries to bring the ADR home to a consistent state
227 -- after a failed migrate or downgrade operation.
228 --
229 -- Input arguments:
230 -- none
231 -- **********************************************************************
232
233 PROCEDURE recover_schema;
234
235
236 -- **********************************************************************
237 -- cleanout_schema()
238 -- This routine recreates the ADR home, without any diagnostic contents.
239 --
240 -- Input arguments:
241 -- none
242 -- **********************************************************************
243
244 PROCEDURE cleanout_schema;
245
246
247 END dbms_adr;