1 PACKAGE dbms_drs IS
2 -- ------------
3 -- OVERVIEW
4 -- ------------
5 --
6 -- This package contains procedures used in the DR Server (Hot Standby).
7 -- There are two forms of each major function; one is a blocking procedure,
8 -- which does not return until the command is completed. The other is a
9 -- non-blocking function which returns with a request identifier which may
10 -- be used to return the result of the command.
11 --
12 --------------------------
13 -- NON-BLOCKING FUNCTIONS
14 --------------------------
15 --
16 -- There is 1 non-blocking function:
17 -- do_control
18 --
19 -- These functions take an incoming document type described in the
20 -- Design Specification for DR Server API. Before the document is parsed
21 -- and processed, it is added to a request queue with a request id returned.
22 -- Therefore, the only reason why the non-blocking functions would raise
23 -- an exception is when the request cannot be added to the request queue.
24 --
25 -- Once all pieces of the outgoing document have been retrieved, the
26 -- user should delete the request using the 'delete_request' procedure.
27 --
28 --------------------------
29 -- BLOCKING PROCEDURES
30 --------------------------
31 --
32 -- There are several blocking procedures:
33 -- do_control
34 -- delete_request
35 -- cancel_request
36 -- get_property
37 --
38 -- With the exception of delete_request, cancel_request and get_property*,
39 -- all the blocking procedures work the same way: as with the
40 -- non-blocking functions, each command takes an incoming document type
41 -- described in the Design Specification for the DR Server API.
42 -- Unlike the non-blocking functions, the blocking functions wait until
43 -- the command completes before returning the first piece of the document.
44 -- All initial requests should request the first piece (piece=1).
45 --
46 -- If there is only one piece of the outgoing document, then the procedure
47 -- returns the first and only piece with a NULL request id. The request id
48 -- is automatically deleted prior to returning from the procedure.
49 --
50 -- If there is more than one piece of the outgoing document, then the
51 -- procedure returns the request id along with the first piece of the
52 -- outgoing document. The user should continue to call the blocking function
53 -- with increasing piece numbers until the last piece is retrieved. Prior
54 -- to returning the last piece, the function autmatically deletes the request
55 -- id and a NULL request id is returned to the user.
56 --
57 -- As with the non-blocking functions, the blocking procedures will not
58 -- raise an exception unless they cannot make the request. The user should
59 -- check the outgoing document for the results of the command issued.
60 --
61 -- The remaining blocking functions (delete_request, cancel_request,
62 -- get_property*) may
63 -- be used to delete, cancel a request, or get a named non-XML property
64 -- respectively. delete_request may be used with a valid request id that
65 -- was retrieved using either the blocking or non-blocking functions.
66 -- Deleting a request that hasn't completed is not permitted and will
67 -- raise an exception. To cancel a request that is in progress, use the
68 -- cancel_request function. The cancel request function will automatically
69 -- delete the request information after cancelling the request.
70 --
71 -- Note: Do not mix blocking and non-blocking functions using the request_id.
72 --
73 -- get_property* returns the first piece of a named property value that is
74 -- identified by name rather than by object id.
75 --
76 --
77 -- ------------------------
78 -- EXAMPLES
79 -- ------------------------
80 --
81 -- ------------------------
82 -- Non-blocking example
83 -- ------------------------
84 --
85 -- declare
86 -- rid integer;
87 -- indoc varchar2(4000);
88 -- outdoc varchar2(4000);
89 -- p integer;
90 -- begin
91 -- indoc:='<dummy>foo</dummy>';
92 --
93 -- rid :=dbms_drs.do_control(indoc);
94 -- dbms_output.put_line('Request_id = '|| rid);
95 --
96 -- outdoc :=NULL;
97 -- p:=1;
98 -- while (outdoc is null)
99 -- loop
100 -- -- should really sleep a couple of ms
101 --
102 -- outdoc:=dbms_drs.get_response(rid,p);
103 -- end loop;
104 --
105 -- dbms_output.put_line(outdoc);
106 -- begin
107 -- while (outdoc is not NULL)
108 -- loop
109 -- p:=p+1;
110 --
111 -- outdoc:=dbms_drs.get_response(rid,p);
112 --
113 -- dbms_output.put_line(outdoc);
114 -- end loop;
115 -- exception
116 -- when no_data_found then
117 -- -- we got past last piece
118 -- NULL;
119 -- end;
120 -- dbms_drs.delete_request(rid);
121 -- end;
122 --
123 -- ------------------------
124 -- Blocking example
125 -- ------------------------
126 --
127 -- declare
128 -- rid integer;
129 -- indoc varchar2(4000);
130 -- outdoc varchar2(4000);
131 -- p integer;
132 -- begin
133 -- p:=1;
134 -- indoc:='<dummy>foo</dummy>';
135 -- dbms_drs.do_control(indoc,outdoc,rid,p);
136 -- dbms_output.put_line(outdoc);
137 --
138 -- p:=2;
139 -- while(rid is NOT NULL)
140 -- loop
141 -- dbms_drs.do_control(indoc,outdoc,rid,p);
142 -- dbms_output.put_line(outdoc);
143 -- p:=p+1;
144 -- end loop;
145 -- end;
146 --
147 --
148 -- ------------------------
149 -- PROCEDURES AND FUNCTIONS
150 -- ------------------------
151
152 procedure do_control(
153 indoc IN VARCHAR2,
154 outdoc OUT VARCHAR2,
155 request_id IN OUT INTEGER,
156 piece IN INTEGER,
157 context IN VARCHAR2 default NULL );
158 -- Control blocking API - OBSELETE, for test use only
159 -- - See do_control_raw below
160 -- Perform a control operation. This is the blocking form of the procedure.
161 -- Input parameters:
162 -- indoc - the document containing the control commands. The
163 -- document type (DDT) is DO_CONTROL.
164 -- request_id - the request id for returning multiple output pieces
165 -- must be NULL for the first piece.
166 -- piece - the piece of the output document to return. For new
167 -- requests, the piece must be 1. For values greater than
168 -- 1, a valid request_id must be supplied.
169 -- context - the context of command, usually NULL.
170 -- Output parameters:
171 -- outdoc - the result of the command. DDT may be either RESULT or VALUE.
172 -- request_id - the request id for returning the next output piece
173 -- will be NULL if the current piece does not exist
174 -- or is the last piece.
175 -- Exceptions:
176 -- bad_request (ORA-16508)
177 --
178
179 procedure do_control_raw(
180 indoc IN RAW,
181 outdoc OUT RAW,
182 request_id IN OUT INTEGER,
183 piece IN INTEGER,
184 context IN VARCHAR2 default NULL,
185 client_id IN INTEGER default 0 );
186 -- Control blocking API - designed for solving NLS problem
187 -- Send DG Broker control request. It is blocking call.
188 -- Input parameters:
189 -- indoc - the document containing the control commands. The
190 -- document type (DDT) is DO_CONTROL.
191 -- request_id - the request id for returning multiple output pieces
192 -- must be NULL for the first piece.
193 -- piece - the piece of the output document to return. For new
194 -- requests, the piece must be 1. For values greater than
195 -- 1, a valid request_id must be supplied.
196 -- context - the context of command, usually NULL.
197 -- client_id - For clients to identify itself - GUI or CLI.
198 -- Default value is 0, which means not GUI nor CLI.
199 --
200 -- Output parameters:
201 -- outdoc - the result of the command. DDT may be either RESULT or VALUE.
202 -- request_id - the request id for returning the next output piece
203 -- will be NULL if the current piece does not exist
204 -- or is the last piece.
205 -- Exceptions:
206 -- bad_request (ORA-16508)
207 --
208
209 function do_control(indoc in varchar2) return integer;
210 -- Control non-blocking API - OBSELETE, for test use only
211 -- - See do_control_raw below
212 -- Perform a control operation. This is the non-blocking form of the
213 -- procedure.
214 -- Input parameters:
215 -- indoc - the document containing the control commands. The
216 -- document type (DDT) is DO_CONTROL.
217 -- Return Value: The request id for the request.
218 --
219 -- Exceptions:
220 -- bad_request (ORA-16508)
221 --
222
223 function do_control_raw( indoc IN RAW ) return integer;
224 -- Control non-blocking API - designed for solving NLS problem
225 -- Perform a control operation. This is the non-blocking form of the
226 -- procedure.
227 -- Input parameters:
228 -- indoc - the document containing the control commands. The
229 -- document type (DDT) is DO_CONTROL.
230 -- Return Value: The request id for the request.
231 --
232 -- Exceptions:
233 -- bad_request (ORA-16508)
234 --
235
236 function get_response(rid in integer, piece in integer) return varchar2;
237 -- Get Result (non-blocking) - OBSELETE, for test use only
238 -- - See get_repsonse_raw below
239 -- Get the result of a non-blocking command. If the command hasn't finished,
240 -- the answer will be NULL. If the piece is beyond the end of the document
241 -- the answer will be NULL.
242 -- Input parameters:
243 -- rid - the request to delete.
244 -- piece - the piece to get, starting from 1.
245 -- Returns:
246 -- outdoc - the answer to the request, if any, or NULL otherwise.
247 --
248 -- Exceptions:
249 -- bad_request (ORA-16508)
250 --
251
252 function get_response_raw(rid in integer, piece in integer) return RAW;
253 -- Get Result (non-blocking) - designed for solving NLS problem
254 -- Get the result of a non-blocking command. If the command hasn't finished,
255 -- the answer will be NULL. If the piece is beyond the end of the document
256 -- the answer will be NULL.
257 -- Input parameters:
258 -- rid - the request to delete.
259 -- piece - the piece to get, starting from 1.
260 -- Returns:
261 -- outdoc - the answer to the request, if any, or NULL otherwise.
262 --
263 -- Exceptions:
264 -- bad_request (ORA-16508)
265 --
266
267 procedure delete_request(rid in integer);
268 -- Delete Request (blocking).
269 -- Input parameters:
270 -- rid - the request to delete.
271 --
272 -- Exceptions:
273 -- bad_request (ORA-16508)
274 --
275
276 procedure cancel_request(rid in integer);
277 -- Cancel Request (blocking).
278 -- Input parameters:
279 -- rid - The request to cancel.
280 --
281 -- Exceptions:
282 -- bad_request (ORA-16508)
283 --
284
285 function get_property( site_name in varchar2,
286 resource_name in varchar2,
287 property_name in varchar2) return varchar2;
288 -- get_property
289 -- get a named property. This function is equivalent to using
290 -- getid to return the object id, followed by a <do_monitor><property>
291 -- request.
292 --
293 -- Input parameters:
294 -- site_name - The name of the site (optional). If omitted,
295 -- resource_name must be NULL and DRC properties are
296 -- retrieved.
297 -- resource_name - The name of the resource (optional). If omitted,
298 -- then site DRC properties are retrieved. Otherwise,
299 -- resource properties are retrieved.
300 --
301 -- property_name - the name of the property to return.
302 --
303 -- Output parameters:
304 -- none
305 -- Returns:
306 -- The property value converted to a string. If the value_type is XML
307 -- then the first 4000 bytes of the XML document are returned.
308 -- Exceptions:
309 --
310
311 function get_property_obj(object_id in integer,
312 property_name in varchar2) return varchar2;
313 -- get_property
314 -- get a named property. This function is equivalent to
315 -- calling a <DO_MONITOR><PROPERTY>...
316 -- request and parsing the resulting string.
317 --
318 -- Input parameters:
319 -- object_id - The object_handle.
320 -- property_name - the name of the property to return.
321 --
322 -- Output parameters:
323 -- none
324 -- Returns:
325 -- The property value converted to a string. If the value_type is XML
326 -- then the first 4000 bytes of the XML document are returned.
327 -- Exceptions:
328 --
329
330 function dg_broker_info( info_name in varchar2 ) return varchar2;
331 -- get Data Guard Broker Information
332 -- It now recognizes the following information names:
333 -- 'VERSION' - the version of Data Guard Broker;
334 -- 'DMONREADY' - whether Data Guard Broker is ready to receive requests.
335 -- Returns:
336 -- The requested information specified by info_name, or
337 -- 'UNSUPPORTED' if info_name is not supported
338 -- Exceptions:
339 -- none
340 --
341
342 procedure sleep(seconds in integer);
343 -- Sleep (blocking).
344 -- Input parameters:
345 -- seconds - Number of seconds to sleep.
346 --
347 -- Output parameters:
348 -- none
349 --
350 -- Exceptions:
351 -- none
352 --
353
354 procedure dump_meta( options IN integer,
355 metafile IN varchar2,
356 dumpfile IN varchar2 );
357 -- DUMP data guard broker METAdata file content into a readable text file.
358 -- Input parameters:
359 -- options - Indicates which metafile(s) to be dumped
360 -- - the file indicated by fnam/fnamlen
361 -- - the "current" metadata file
362 -- - the "alternate" metadata file
363 -- - first the "current", then the "alternate"
364 -- metafile - Metadata filespec to be dumped. Ignored unless selected by
365 -- the options argument.
366 -- dumpfile - The readable output filespec.
367
368
369 --
370 -- The old ping procedure that was used in 12.1.0.1 and prior to 11.2.0.4.
371 --
372 PROCEDURE Ping(iObid IN BINARY_INTEGER,
373 iVersion IN BINARY_INTEGER,
374 iFlags IN BINARY_INTEGER,
375 iMiv IN BINARY_INTEGER,
376 oVersion OUT BINARY_INTEGER,
377 oFlags OUT BINARY_INTEGER,
378 oFoCond OUT VARCHAR2,
379 oStatus OUT BINARY_INTEGER);
380
381 --
382 -- Ping procedure since 12.1.0.2 ( and 11.2.0.4 )
383 --
384 PROCEDURE Ping(iObid IN BINARY_INTEGER,
385 iVersion IN BINARY_INTEGER,
386 iFlags IN BINARY_INTEGER,
387 iMiv IN BINARY_INTEGER,
388 iWaitStat IN BINARY_INTEGER,
389 oVersion OUT BINARY_INTEGER,
390 oFlags OUT BINARY_INTEGER,
391 oFoCond OUT VARCHAR2,
392 oStatus OUT BINARY_INTEGER);
393
394
395 PROCEDURE ReadyToFailover(iObid IN BINARY_INTEGER,
396 iVersion IN BINARY_INTEGER,
397 iFlags IN BINARY_INTEGER,
398 iMiv IN BINARY_INTEGER,
399 iFoCond IN VARCHAR2,
400 oStatus OUT BINARY_INTEGER);
401
402 PROCEDURE StateChangeRecorded(iObid IN BINARY_INTEGER,
403 iVersion IN BINARY_INTEGER);
404
405 PROCEDURE fs_failover_for_hc_cond(hc_cond IN BINARY_INTEGER,
406 status OUT BINARY_INTEGER);
407
408 FUNCTION fs_failover_for_hc_cond(hc_cond IN BINARY_INTEGER) RETURN BOOLEAN;
409
410 PROCEDURE initiate_fs_failover(condstr IN varchar2,
411 status OUT binary_integer);
412
413 pragma TIMESTAMP('2006-05-17:20:20:00');
414
415 end;
[Home] [Help]