1 PACKAGE dbms_gsm_cloudadmin AS
2
3
4 --*****************************************************************************
5 -- Package Public Types
6 --*****************************************************************************
7
8
9 --*****************************************************************************
10 -- Package Public Constants
11 --*****************************************************************************
12
13 gsm_master_lock_name constant varchar2(19) := 'ORA$GSM_MASTER_LOCK';
14 no_lock constant number := 99; -- lock not granted (GDS)
15 rogueGSM constant number := 99;
16 masterNotAllowed constant number := 98; -- GSM is not allowed to
17 -- get master lock
18 MaxGSM constant number := 5;
19
20
21 --*****************************************************************************
22 -- Package Public Exceptions
23 --*****************************************************************************
24
25
26
27 --*****************************************************************************
28 -- Package Public Procedures
29 --*****************************************************************************
30
31 maxwait constant integer := 32767; -- Wait forever
32 sessioninfo gsm_session;
33
34 -------------------------------------------------------------------------------
35 --
36 -- PROCEDURE getMasterLock
37 --
38 -- Description:
39 -- Request the GSM catalog master lock in exclusive mode.
40 --
41 -- Parameters:
42 -- timeout: the number of seconds to wait for the lock
43 -- "maxwait" means to wait forever
44 -- lock_handle: handle used to identify the lock
45 -- should be passed to releaseMasterLock to release the lock
46 -- size can be up to 128
47 --
48 -- Returns:
49 -- 0 - success
50 -- 1 - timeout
51 -- 2 - deadlock
52 -- 3 - parameter error
53 -- 4 - already own lock
54 -- 5 - illegal lock handle
55 -- 99 - Lock not granted (due to GDS checking)
56 --
57 -- Notes:
58 -- The routine uses dbms_lock.allocate_unique, so will always do a
59 -- transaction commit.
60 --
61 -- Lock is held until it is explicitly released or session terminates.
62 -------------------------------------------------------------------------------
63
64 FUNCTION getMasterLock( timeout IN integer default maxwait,
65 lock_handle OUT varchar2,
66 gsm_name IN varchar2 default NULL,
67 gsm_vers IN varchar2 default NULL )
68 RETURN integer;
69
70 -------------------------------------------------------------------------------
71 --
72 -- PROCEDURE releaseMasterLock
73 --
74 -- Description:
75 -- Release the GSM catalog master lock acquired previously by getMasterLock.
76 --
77 -- Parameters:
78 -- lock_handle: handle returned by getMasterLock
79 --
80 -- Returns:
81 -- 0 - success
82 -- 3 - parameter error
83 -- 4 - don't own lock
84 -- 5 - illegal lock handle
85 --
86 -- Notes:
87 --
88 -------------------------------------------------------------------------------
89
90 FUNCTION releaseMasterLock( lock_handle IN varchar2 )
91 RETURN integer;
92
93
94 -------------------------------------------------------------------------------
95 --
96 -- PROCEDURE createCloud
97 --
98 -- Description:
99 -- Creates a cloud entry in the cloud catalog.
100 --
101 -- Parameters:
102 -- cloud_name: name to give the cloud.
103 --
104 -- Notes:
105 -- Currently the catalog only supports one cloud.
106 -------------------------------------------------------------------------------
107 PROCEDURE createCatalog(cloud_name IN varchar2 default NULL,
108 autoVNCR IN number default dbms_gsm_common.isTrue,
109 instances IN number default NULL,
110 force IN number default dbms_gsm_common.isFalse);
111 PROCEDURE createCloud( cloud_name IN varchar2 default NULL,
112 autoVNCR IN number default dbms_gsm_common.isTrue,
113 instances IN number default NULL,
114 force IN number default dbms_gsm_common.isFalse);
115
116 -------------------------------------------------------------------------------
117 --
118 -- PROCEDURE modifyCatalog
119 --
120 -- Description:
121 -- Modifies information in the cloud catalog
122 --
123 -- Parameters:
124 -- autoVNCR: boolean - isTrue = Turn on autoVNCR
125 -- isFalse = Turn off autoVNCR
126 --
127 -- Notes:
128 -- Currently the catalog only supports one cloud.
129 -------------------------------------------------------------------------------
130 PROCEDURE modifyCatalog(autoVNCR IN number default NULL);
131 -------------------------------------------------------------------------------
132 --
133 -- PROCEDURE removeCloud
134 --
135 -- Description:
136 -- Removes the cloud entry from the cloud catalog.
137 --
138 -- Parameters:
139 -- cloud_name: name of the cloud to remove.
140 --
141 -- Notes:
142 -- Currently the catalog only supports one cloud.
143 -------------------------------------------------------------------------------
144 PROCEDURE removeCatalog( cloud_name IN varchar2 default NULL ); -- TODO: remove
145 PROCEDURE removeCloud( cloud_name IN varchar2 default NULL );
146
147
148 -------------------------------------------------------------------------------
149 --
150 -- PROCEDURE addGSM
151 --
152 -- Description:
153 -- Adds a GSM to the cloud.
154 --
155 -- Parameters:
156 -- gsm_name: GSM alias name
157 -- gsm_endpoint1: Listener endpoint
158 -- gsm_endpoint2: TODO:?
159 -- local_ons_port: Local ONS port for ONS server process
160 -- remote_ons_port: Remote ONS port of ONS server process
161 -- region_name: The GSM region, if NULL will use the default.
162 -- gsm_number: Unique number assigned to the GSM
163 --
164 -- Notes:
165 -- Updates the "_remote_gsm" parameter on the catalog database to point
166 -- to the new GSM.
167 --
168 -- region_name can be NULL if there is only one region in the cloud.
169 -- In which case the GSM will be added to that region.
170 --
171 -- No assumptions should be made about gsm_number other than it is
172 -- unique for the cloud. For example, the caller should not assume that it
173 -- is a monotonically increasing number.
174 -------------------------------------------------------------------------------
175 PROCEDURE addGSM( gsm_name IN varchar2,
176 gsm_endpoint1 IN varchar2,
177 gsm_endpoint2 IN varchar2,
178 local_ons_port IN number,
179 remote_ons_port IN number,
180 region_name IN varchar2 default NULL,
181 gsm_number OUT number,
182 gsm_oracle_home IN varchar2 default NULL,
183 gsm_hostname IN varchar2 default NULL );
184
185 -------------------------------------------------------------------------------
186 --
187 -- PROCEDURE syncParameters
188 --
189 -- Description:
190 -- Syncronize spfile parameter values using database information
191 --
192 -- Parameters:
193 -- NONE
194 --
195 -- Notes:
196 -- Currently updates the _gsm and _cloud_name parameters. These values are
197 -- required for the catalog database instance and will not be set on
198 -- data-guard standby databases (since createCatalog is never run there).
199 -- This function will be executed as part of the database open notifier
200 -- callback on any primary database that is a catalog database
201 --
202 ------------------------------------------------------------------------------
203 PROCEDURE syncParameters;
204
205 -------------------------------------------------------------------------------
206 --
207 -- PROCEDURE modifyGSM
208 --
209 -- Description:
210 -- Changes a GSM attributes.
211 --
212 -- Parameters:
213 -- gsm_name: GSM alias name
214 -- gsm_endpoint1: Listener endpoint
215 -- gsm_endpoint2: TODO:?
216 -- local_ons_port: Local ONS port for ONS server process
217 -- remote_ons_port: Remote ONS port of ONS server process
218 -- region_name: The GSM region.
219 --
220 -- Notes:
221 -- One or more of the attributes can be changed on each call.
222 --
223 -- If "gsm_endpoint1" is changed, then will update the "_remote_gsm"
224 -- parameter on the catalog database with the new endpoint.
225 -------------------------------------------------------------------------------
226 PROCEDURE modifyGSM( gsm_name IN varchar2,
227 gsm_endpoint1 IN varchar2 default NULL,
228 gsm_endpoint2 IN varchar2 default NULL,
229 local_ons_port IN number default NULL,
230 remote_ons_port IN number default NULL,
231 region_name IN varchar2 default NULL );
232
233
234 -------------------------------------------------------------------------------
235 --
236 -- PROCEDURE removeGSM
237 --
238 -- Description:
239 -- Removes a GSM from the cloud.
240 --
241 -- Parameters:
242 -- gsm_name: GSM alias name
243 --
244 -- Notes:
245 -- It is up to the caller to insure that the GSM has been stopped.
246 --
247 -- Will remove this GSM endpoint from the "_remote_gsm" parameter on the
248 -- catalog database.
249 -------------------------------------------------------------------------------
250 PROCEDURE removeGSM( gsm_name IN varchar2 );
251
252
253 -------------------------------------------------------------------------------
254 --
255 -- PROCEDURE disconnectGSM
256 --
257 -- Description:
258 -- Kills GSM session.
259 --
260 -- Parameters:
261 -- gsm_name: GSM alias name
262 -- kill_level: if 0 kill sesssion, if 1 the same immediate,
263 -- if 2 disconnect session
264 --
265 -- Notes:
266 --
267 -------------------------------------------------------------------------------
268 PROCEDURE disconnectGSM( gsm_name IN varchar2, kill_level number default 2 );
269
270 -------------------------------------------------------------------------------
271 --
272 -- PROCEDURE addVNCR
273 --
274 -- Description:
275 -- Adds VNCR to Cloud
276 --
277 -- Parameters:
278 -- name: VNCR name
279 -- group_id: VNCR group id
280 --
281 -- Notes:
282 -- Group id could be NULL. If set, it allows group removal of VNCRs
283 -------------------------------------------------------------------------------
284 PROCEDURE addVNCR( name IN varchar2,
285 group_id in varchar2 default NULL,
286 updateRequestTable IN number
287 default dbms_gsm_utility.updateTrue);
288
289 -------------------------------------------------------------------------------
290 --
291 -- PROCEDURE removeVNCR
292 --
293 -- Description:
294 -- removes VNCR from Cloud
295 --
296 -- Parameters:
297 -- name: VNCR name
298 -- group_id: VNCR group id
299 --
300 -- Notes:
301 -- One and only one of either group id or name could be NULL.
302 -------------------------------------------------------------------------------
303 PROCEDURE removeVNCR( name IN varchar2 default NULL,
304 group_id in varchar2 default NULL);
305
306 -------------------------------------------------------------------------------
307 --
308 -- PROCEDURE createSubscriber
309 --
310 -- Description:
311 -- Add an AQ subscriber to the change log queue.
312 --
313 -- Parameters:
314 -- gsm_name: Subscriber name should be a name of one of the GSMs in
315 -- the cloud.
316 --
317 -- Notes:
318 --
319 -------------------------------------------------------------------------------
320 PROCEDURE createSubscriber( gsm_name IN varchar2 );
321
322
323 -------------------------------------------------------------------------------
324 --
325 -- PROCEDURE removeSubscriber
326 --
327 -- Description:
328 -- Remove an AQ subscriber to the change log queue.
329 --
330 -- Parameters:
331 -- gsm_name: The name used originally to subscribe to the queue.
332 -- The name should have been a name of one of the GSMs in
333 -- the cloud.
334 --
335 -- Notes:
336 --
337 -------------------------------------------------------------------------------
338 PROCEDURE removeSubscriber( gsm_name IN varchar2 );
339
340
341 -------------------------------------------------------------------------------
342 --
343 -- PROCEDURE addRegion
344 --
345 -- Description:
346 -- Adds a region to the cloud.
347 --
348 -- Parameters:
349 -- region_name: The name to give to the region.
350 -- buddy_name: The name of the buddy region.
351 --
352 -- Notes:
353 --
354 -------------------------------------------------------------------------------
355 PROCEDURE addRegion( region_name IN varchar2,
356 buddy_name IN varchar2 default NULL );
357
358
359 -------------------------------------------------------------------------------
360 --
361 -- PROCEDURE modifyRegion
362 --
363 -- Description:
364 -- Modifies a region.
365 --
366 -- Parameters:
367 -- region_name: The name of the region to modify.
368 -- buddy_name: The name of a buddy region to assign to the region.
369 -- Can be NULL.
370 --
371 -- Notes:
372 --
373 -------------------------------------------------------------------------------
374 PROCEDURE modifyRegion( region_name IN varchar2,
375 buddy_name IN varchar2 default NULL,
376 region_weights IN varchar2 default NULL);
377
378
379 -------------------------------------------------------------------------------
380 --
381 -- PROCEDURE removeRegion
382 --
383 -- Description:
384 -- Removes a region from the cloud.
385 --
386 -- Parameters:
387 -- region_name: The name of the region.
388 --
389 -- Notes:
390 -- The region should be empty of GSMs and databases.
391 --
392 -- The last region in the cloud cannot be removed.
393 -------------------------------------------------------------------------------
394 PROCEDURE removeRegion( region_name IN varchar2 );
395
396
397 -------------------------------------------------------------------------------
398 --
399 -- PROCEDURE addDatabasePool
400 --
401 -- Description:
402 -- Adds a database pool to the cloud.
403 --
404 -- Parameters:
405 -- database_pool_name: The name to give to the database pool.
406 --
407 -- Notes:
408 --
409 -------------------------------------------------------------------------------
410 PROCEDURE addDatabasePool( database_pool_name IN varchar2 );
411
412
413 -------------------------------------------------------------------------------
414 --
415 -- PROCEDURE removeDatabasePool
416 --
417 -- Description:
418 -- Removes a database pool from the cloud.
419 --
420 -- Parameters:
421 -- database_pool_name: The name of the database pool.
422 --
423 -- Notes:
424 -- The pool should be empty, i.e. it should no longer have any
425 -- databases or services.
426 -------------------------------------------------------------------------------
427 PROCEDURE removeDatabasePool( database_pool_name IN varchar2 );
428
429
433 --
430 -------------------------------------------------------------------------------
431 --
432 -- PROCEDURE removeDatabasePoolAdmin
434 -- Description:
435 -- Adds an administrator for a database pool.
436 --
437 -- Parameters:
438 -- database_pool_name: The name of the database pool.
439 -- user_name: The name of user to become administrator for the
440 -- pool.
441 --
442 -- Notes:
443 -- database_pool_name can be NULL if there is only one database pool
444 -- in the cloud. In which case the command will default to that pool.
445 --
446 -- The user is revoked VPD access to the cloud information about the
447 -- database pool.
448 --
449 --
450 -------------------------------------------------------------------------------
451 PROCEDURE removeDatabasePoolAdmin( database_pool_name IN varchar2 default NULL,
452 user_name IN varchar2 );
453
454 -------------------------------------------------------------------------------
455 --
456 -- PROCEDURE addDatabasePoolAdmin
457 --
458 -- Description:
459 -- Adds an administrator for a database pool.
460 --
461 -- Parameters:
462 -- database_pool_name: The name of the database pool.
463 -- user_name: The name of user to become administrator for the
464 -- pool.
465 --
466 -- Notes:
467 -- database_pool_name can be NULL if there is only one database pool
468 -- in the cloud. In which case the command will default to that pool.
469 --
470 -- The user is granted VPD access to the cloud information about the
471 -- database pool.
472 --
473 -- TODO: the user is also given "gsm_pooladmin_role".
474 -------------------------------------------------------------------------------
475 PROCEDURE addDatabasePoolAdmin( database_pool_name IN varchar2 default NULL,
476 user_name IN varchar2 );
477
478
479 -------------------------------------------------------------------------------
480 --
481 -- PROCEDURE poolVpdPredicate
482 --
483 -- Description:
484 -- Enforces VPD read security for database pool tables.
485 --
486 -- Parameters:
487 -- Standard VPD function parameters.
488 --
489 -- Notes:
490 --
491 -------------------------------------------------------------------------------
492 FUNCTION poolVpdPredicate( obj_schema varchar2,
493 obj_name varchar2 ) RETURN varchar2;
494
495 -------------------------------------------------------------------------------
496 --
497 -- PROCEDURE MaskPolicy
498 --
499 -- Description:
500 -- Enforces VPD masking for select on database table
501 --
502 -- Parameters:
503 -- Standard VPD function parameters.
504 --
505 -- Notes:
506 --
507 -------------------------------------------------------------------------------
508 FUNCTION MaskPolicy ( obj_schema varchar2,
509 obj_name varchar2) RETURN varchar2;
510 -------------------------------------------------------------------------------
511 --
512 -- FUNCTION VerifyCatalog
513 --
514 -- Description:
515 -- Perform various cross-check verifications on the catalog data
516 --
517 -- Parameters:
518 -- NONE
519 --
520 -- Notes:
521 --
522 -------------------------------------------------------------------------------
523 FUNCTION VerifyCatalog
524 RETURN NUMBER;
525
526 -------------------------------------------------------------------------------
527 --
528 -- PROCEDURE cancelAllChanges
529 --
530 -- Description:
531 -- Cancel (and rollback) all outstanding catalog changes
532 --
533 -- Parameters:
534 -- NONE
535 --
536 -- Notes:
537 -- This procedure requires that there are no GSM servers running, and it
538 -- will get the "master lock" to prevent any from becoming master while
539 -- it is running
540 --
541 -- This is an "escape hatch" to be used only under customer support
545 -------------------------------------------------------------------------------
542 -- supervision. Usually the GSM will perform the right cleanup
543 -- automatically while it is running or as soon as it re-starts
544 -- after shutdown or crash.
546 PROCEDURE cancelAllChanges;
547
548
549 -------------------------------------------------------------------------------
550 --
551 -- FUNCTION importBegin
552 --
553 -- Description:
554 -- Clear tables and other possibly important stuff
555 --
556 -- Parameters:
557 -- NONE
558 --
559 -------------------------------------------------------------------------------
560
561 PROCEDURE importBegin;
562
563
564 -------------------------------------------------------------------------------
565 --
566 -- FUNCTION importEnd
567 --
568 -- Description:
569 -- Update sequences, and other possible stuff after successful import
570 --
571 -- Parameters:
572 -- NONE
573 --
574 -------------------------------------------------------------------------------
575
576 PROCEDURE importEnd;
577
578 -------------------------------------------------------------------------------
579 --
580 -- PROCEDURE checkGSMDown
581 --
582 -- Description:
583 -- Checks whether a GSM is disconnecting from the catalog database.
584 -- If it is a GSM then post the alert GSM down.
585 --
586 -- Parameters:
587 -- None.
588 --
589 -------------------------------------------------------------------------------
590 PROCEDURE checkGSMDown;
591 -------------------------------------------------------------------------------
592 --
593 -- PROCEDURE doEncryptGSMPwd
594 --
595 -- Description:
596 -- Encrypt database.GSM_PASSWORD and store in database.ENCRYPTED_GSM_PASSWORD
597 --
598 -- Parameters:
599 -- NULL
600 --
601 -------------------------------------------------------------------------------
602 PROCEDURE doEncryptGSMPwd;
603 -------------------------------------------------------------------------------
604 --
605 -- PROCEDURE setEncryptedGSMPwd
606 --
607 -- Description:
608 -- Sets value for gsmadmin_internal.database.ENCRYPTED_GSM_PASSWORD
609 --
610 -- Parameters:
611 -- dbname: The name of the database.
612 -- encpwd: content of encrypted password
613 --
614 -------------------------------------------------------------------------------
615 PROCEDURE setEncryptedGSMPwd( dbname varchar2,
616 encpwd RAW);
617
618 --*****************************************************************************
619 -- End of Package Public Procedures
620 --*****************************************************************************
621
622
623 END dbms_gsm_cloudadmin;
[Home] [Help]