1 PACKAGE dbms_ha_alerts_prvt AS
2
3 /****************************************************************************
4 * NAME
5 * post_ha_alert - Kernel High availability Notifications POST HA ALERT
6 *
7 * DESCRIPTION
8 * This routine is the PL/SQL public interface for posting HA alerts.
9 *
10 * It calls keltpost() or keltpost_bg() in kelt.c after packaging the alert
11 * attributes appropriately.
12 *
13 * It can call keltpost[_bg] up to three times:
14 * 1. to clear old versions of same alert [optional]
15 * 2. to post the alert (level = requested severity)
16 * 3. to immediately clear the alert [optional]
17 *
18 * The clearing calls can help ensure that this alert (or a following one)
19 * isn't rejected as duplicate of an earlier one.
20 *
21 * PARAMETERS
22 *
23 * reason_id - taken from dbmsslrt.sql (e.g.
24 * dbms_server_alert.RSN_FAN_DATABASE_DOWN)
25 *
26 * same_transaction - the post should occur in the caller's
27 * transaction (which must already have been
28 * started) [passes KELT_SAME_TRAN to keltpost].
29 * Otherwise, a recursive transaction is
30 * used [passes KELT_SEP_TRAN to keltpost].
31 * Ignored KJHN_BACKGROUND_PROCESS is turned on.
32 *
33 * clear_old_alert - kjhn_post_ha_alert should clear any existing
34 * version of the same alert before posting. This
35 * helps ensure that the new alert won't be
36 * rejected as duplicate. Most users will
37 * want to specify clear_old_alert => TRUE.
38 * Note: calls keltpos[_bg] first w/ LEVEL_CLEAR,
39 * then calls again with requested severity.
40 *
41 * severity - an integer severity level (such as critical), one of
42 * dbms_server_alert.LEVEL_* (see dbmsslrt.sql).
43 * Defaults to LEVEL_WARNING.
44 *
45 * host_name - the host that failed, or the host on which the
46 * resource affected was run
47 *
48 * event_reason - a string indicating the reason the event occurred;
49 * e.g. 'user' or 'unplanned'
50 *
51 * event_time - best approximation of time at which the event
52 * occurred
53 *
54 * database_domain - FAN attributes representing the resource affacted.
55 * database_unique_name Which attributes are needed depends on the
56 * instance_name value of reason_id; see 'HA ALERT ATTRIBUTES' above.
57 * service_name
58 * incarnation
59 * cardinality
60 *
61 * event_id - a numeric id used for avoiding duplicate events.
62 * Most posters should use the default, unless they
63 * wish to control the duplication of events;
64 * e.g. if multiple nodes may post the same event.
65 *
66 * metric_value - value for metric associated with the event
67 * (see kjhn2.h for list of alerts and their metrics).
68 * Currently, no values are defined, so use default.
69 *
70 * timeout_seconds - minimum time to hold the event before timeout
71 * allows duplicates to be submitted. Should be
72 * left to the default for most posters.
73 *
74 * immediate_timeout - TRUE means clear alert immediately after posting,
75 * thus avoiding conflict with later postings.
76 * Recommended to be TRUE for most posters.
77 * Choose FALSE if multiple nodes may post the same
78 * event with the same event_id, to avoid duplication.
79 *
80 *
81 * background_process - the actual queue posting should happen
82 * asynchronously in MMON. Uses keltpost_bg()
83 * rather than keltpost().
84 *
85 * signal_internal - if TRUE, signal some errors as internal errors;
86 * if FALSE, use only normal errors
87 *
88 * duplicates_ok - silently ignore and discard events that duplicate
89 * existing ones. Use to avoid duplicate if
90 * multiple nodes will attempt to post the same event.
91 * Most users will not want to set this.
92 *
93 * NOTES
94 * An event is considered a duplicate if it shares the following
95 * attributes with an event that has not yet timed out:
96 * reason_id
97 * event_id
98 * object_id (generally, the name hash of the service or database service)
99 *
100 * This means that two events with different event time, incarnation, etc.
101 * will still be treated as equivalent.
102 *
103 ****************************************************************************/
104 PROCEDURE post_ha_alert(reason_id IN dbms_server_alert.
105 reason_id_t,
106 same_transaction IN BOOLEAN,
107 clear_old_alert IN BOOLEAN,
108 severity IN dbms_server_alert.
109 SEVERITY_LEVEL_T
110 DEFAULT
111 dbms_server_alert.
112 LEVEL_WARNING,
113 database_domain IN VARCHAR2 DEFAULT
114 SYS_CONTEXT('USERENV',
115 'DB_DOMAIN'),
116 database_unique_name IN VARCHAR2 DEFAULT NULL,
117 instance_name IN VARCHAR2 DEFAULT NULL,
118 service_name IN VARCHAR2 DEFAULT NULL,
119 host_name IN VARCHAR2 DEFAULT NULL,
120 incarnation IN VARCHAR2 DEFAULT NULL,
121 event_reason IN VARCHAR2,
122 event_time IN TIMESTAMP WITH TIME ZONE,
123 cardinality IN BINARY_INTEGER DEFAULT NULL,
124 event_id IN NUMBER DEFAULT NULL,
125 metric_value IN NUMBER DEFAULT NULL,
126 timeout_seconds IN BINARY_INTEGER DEFAULT NULL,
127 immediate_timeout IN BOOLEAN DEFAULT TRUE,
128 background_process IN BOOLEAN DEFAULT FALSE,
129 signal_internal IN BOOLEAN DEFAULT TRUE,
130 duplicates_ok IN BOOLEAN DEFAULT FALSE);
131
132
133
134 -- THE FOLLOWING FOR KJHN INTERNAL USE ONLY [see body for details] --
135
136 FUNCTION post_instance_up RETURN VARCHAR2;
137
138 FUNCTION check_ha_resources RETURN VARCHAR2;
139
140 PROCEDURE clear_instance_resources(database_domain IN VARCHAR2,
141 database_unique_name IN VARCHAR2,
142 instance_name IN VARCHAR2,
143 event_time IN TIMESTAMP
144 WITH TIME ZONE);
145
146 /****************************************************************************
147 *
148 * Convert a startup time from v$instance/gv$instance to a timestamp
149 * with time zone, so it can pe stored persistently and compared
150 * safely with other timestamps.
151 *
152 ****************************************************************************/
153 FUNCTION instance_startup_timestamp_tz(startup_time DATE)
154 RETURN TIMESTAMP WITH TIME zone;
155
156
157 END dbms_ha_alerts_prvt;
[Home] [Help]