1 PACKAGE dbms_adr_app 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_APP
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_APP 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 -- set_adr_home()
42 -- This routine set ups a new adr home. It will create directories
43 -- if they do not exist. This adr home will be the current ADR home for
44 -- all subsequent calls to DBMS_ADR_APP.
45 --
46 -- PARAMETERS
47 -- product type - Product type or name is the first level in the ADR home
48 -- path. By default it will be set to 'plsqlapp'
49 -- product_id - product id is the second level in the ADR home path.
50 -- By default it will be set to database name
51 -- instance_id - instance id is the third level in the ADR home path.
52 -- By default it will be set to instance name.
53 -- create_dir - If true, this call will create the physical directories
54 -- for the ADR home. Otherwise, physical directory creation
55 -- will be deferred until some persistent diagnostic action
56 -- is taken, e.g. write alert log, write trace or create
57 -- incident.
58 -- precedence - Useful in multi library case when each library uses its
59 -- own ADR home. In this case the Library with the highest
60 -- precedence will win and its ADR home will be used.
61 -- **********************************************************************
62
63 PROCEDURE set_adr_home
64 (
65 product_type IN VARCHAR2 DEFAULT NULL,
66 product_id IN VARCHAR2 DEFAULT NULL,
67 instance_id IN VARCHAR2 DEFAULT NULL,
68 create_dir IN BOOLEAN DEFAULT FALSE,
69 precedence IN INTEGER DEFAULT 0
70 );
71
72
73 -- **********************************************************************
74 -- create_incident
75 -- This routine creates an incident in the current ADR Home.
76 -- It returns the incident handle, which can be used for further
77 -- manipulation of the incident e.g. registering additional files in
78 -- the incident.
79 -- **********************************************************************
80
81 FUNCTION create_incident
82 (
83 problem_key IN VARCHAR2, /* incident problem key */
84 error_facility IN VARCHAR2 DEFAULT NULL, /* error facility */
85 error_number IN INTEGER DEFAULT NULL, /* error number */
86 error_message IN VARCHAR2 DEFAULT NULL, /* error message */
87 error_args IN adr_incident_err_args_t DEFAULT NULL,
88 /* error arguments */
89 ecid IN VARCHAR2 DEFAULT NULL,/* execution context id */
90 signalling_component IN VARCHAR2 DEFAULT NULL,/* signalling component */
91 signalling_subcomponent IN VARCHAR2 DEFAULT NULL, /* signalling subcomp. */
92 suspect_component IN VARCHAR2 DEFAULT NULL, /* suspect component */
93 suspect_subcomponent IN VARCHAR2 DEFAULT NULL, /* suspect subcomp. */
94 correlation_keys IN adr_incident_corr_keys_t DEFAULT NULL,
95 /* correlation keys */
96 files IN adr_incident_files_t DEFAULT NULL
97 /* additional incident files */
98 )
99 RETURN adr_incident_t;
100
101
102 -- **********************************************************************
103 -- write_trace
104 -- This routine is used to write trace lines to the trace file in the
105 -- current ADR home.
106 -- **********************************************************************
107
108 PROCEDURE write_trace
109 (
110 trace_data IN VARCHAR2 /* trace data */
111 );
112
113
114 -- **********************************************************************
115 -- write_log
116 -- This routine is used to write log entries to the alert log in the
117 -- current ADR home. The log will be written in ODL format.
118 -- **********************************************************************
119
120 PROCEDURE write_log
121 (
122 -- Mandatory ODL fields without defaults
123 msg_id IN VARCHAR2, /* message id */
124 msg_type IN INTEGER, /* message type */
125 msg_level IN INTEGER, /* message level */
126 msg_text IN VARCHAR2, /* message text */
127
128 -- Optional ODL fields and mandatory ones with defaults
129 timestamp_originating IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
130 /* time originating */
131 timestamp_normalized IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
132 /* time normalized */
133 org_id IN VARCHAR2 DEFAULT NULL, /* organization id */
134 component_id IN VARCHAR2 DEFAULT NULL, /* component id */
135 instance_id IN VARCHAR2 DEFAULT NULL, /* instance id */
136 hosting_client_id IN VARCHAR2 DEFAULT NULL, /* hosting client id */
137 msg_group IN VARCHAR2 DEFAULT NULL, /* message group */
138 host_id IN VARCHAR2 DEFAULT NULL, /* host id */
139 host_nwaddr IN VARCHAR2 DEFAULT NULL, /* host address */
140 module_id IN VARCHAR2 DEFAULT NULL, /* module id */
141 process_id IN VARCHAR2 DEFAULT NULL, /* process id */
142 thread_id IN VARCHAR2 DEFAULT NULL, /* thread id */
143 user_id IN VARCHAR2 DEFAULT NULL, /* user id */
144 suppl_attrs IN adr_log_msg_suppl_attrs_t DEFAULT NULL,
145 /* supplemental attributes */
146 problem_key IN VARCHAR2 DEFAULT NULL, /* problem key */
147 upstream_comp_id IN VARCHAR2 DEFAULT NULL, /* upstream comp. id */
148 downstream_comp_id IN VARCHAR2 DEFAULT NULL, /* downstream comp. id */
149 ecid IN adr_log_msg_ecid_t DEFAULT NULL,
150 /* execution context id */
151 error_instance_id IN adr_log_msg_errid_t DEFAULT NULL,
152 /* error instance id */
153 msg_args IN adr_log_msg_args_t DEFAULT NULL,
154 /* message arguments */
155 detail_location IN VARCHAR2 DEFAULT NULL, /* detailed location */
156 suppl_detail IN VARCHAR2 DEFAULT NULL, /* supplemental detail */
157 msg_template_obj IN adr_msg_template_t DEFAULT NULL
158 /* message template object */
159 );
160
161 -- **********************************************************************
162 -- set_log_msg_template
163 -- This routine creates a log message template object which can
164 -- be used in the write_log API call. The purpose of the log message
165 -- template object is to avoid have to specify common parameters in
166 -- each call to write_log. When passing a template object, optional
167 -- parameters that were not set explicitly will be copied from the
168 -- template object instead.
169 -- **********************************************************************
170
171 FUNCTION set_log_msg_template
172 (
173 org_id IN VARCHAR2 DEFAULT NULL,
174 component_id IN VARCHAR2 DEFAULT NULL,
175 instance_id IN VARCHAR2 DEFAULT NULL,
176 hosting_client_id IN VARCHAR2 DEFAULT NULL,
177 msg_group IN VARCHAR2 DEFAULT NULL,
178 host_id IN VARCHAR2 DEFAULT NULL,
179 host_nwaddr IN VARCHAR2 DEFAULT NULL,
180 module_id IN VARCHAR2 DEFAULT NULL,
181 process_id IN VARCHAR2 DEFAULT NULL,
182 thread_id IN VARCHAR2 DEFAULT NULL,
183 user_id IN VARCHAR2 DEFAULT NULL,
184 upstream_comp_id IN VARCHAR2 DEFAULT NULL,
185 downstream_comp_id IN VARCHAR2 DEFAULT NULL,
186 ecid IN adr_log_msg_ecid_t DEFAULT NULL,
187 error_instance_id IN adr_log_msg_errid_t DEFAULT NULL,
188
189 msg_args IN adr_log_msg_args_t DEFAULT NULL,
190 detail_location IN VARCHAR2 DEFAULT NULL,
191 suppl_detail IN VARCHAR2 DEFAULT NULL
192 )
193 RETURN adr_msg_template_t;
194
195
196 -- **********************************************************************
197 -- get_trace_location
198 -- This routine returns the complete path of the trace directory in the
199 -- ADR home.
200 -- **********************************************************************
201
202 FUNCTION get_trace_location RETURN VARCHAR2;
203
204
205 -- **********************************************************************
206 -- get_log_location
207 -- This routine returns the complete path of the log directory in the
208 -- ADR home.
209 -- **********************************************************************
210
211 FUNCTION get_log_location RETURN VARCHAR2;
212
213
214 -- **********************************************************************
215 -- set_exception_mode
216 -- This routine sets the exception mode for the package.
217 -- If exception mode is set to true, then all the exceptions
218 -- will be raised to client. If it is set to false, then all the
219 -- exceptions will be suppressed, and the client will not see any
220 -- exception, even if underlying APIs are raising exceptions.
221 --
222 -- Since this is a diagnosability API, clients might not expect these
223 -- API calls to raise their own exceptions.
224 -- By default, exception mode will be set to false.
225 -- Clients can change it any time by calling this function.
226 -- **********************************************************************
227
228 PROCEDURE set_exception_mode
229 (
230 exc_mode IN BOOLEAN DEFAULT FALSE /* exception mode */
231 );
232
233 -- **********************************************************************
234 -- get_current_precedence
235 -- This routine returns the current precedence level set for current
236 -- ADR Home
237 -- **********************************************************************
238
239 FUNCTION get_current_precedence return INTEGER;
240
241 -- **********************************************************************
242 -- set_current_precedence
243 -- This routine sets the current precedence level for the current
244 -- ADR Home
245 -- **********************************************************************
246
247 PROCEDURE set_current_precedence
248 (
249 precedence IN INTEGER /* precedence level to set */
250 );
251
252 END dbms_adr_app;
[Home] [Help]