Oracle | DBMS_GSM

Oracle DBMS_GSM_CLOUDADMIN Version 21c

General Information

Library Note

Morgan's Library Page Header

ACE Director Alum Daniel Morgan, founder of Morgan's Library, is scheduling complimentary technical Workshops on Database Security for the first 30 Oracle Database customers located anywhere in North America, EMEA, LATAM, or APAC that send an email to asra_us@oracle.com. Request a Workshop for your organization today.

Purpose Defines the interfaces for dbms_gsm_cloudadmin package that is used for cloud administration performed by GSM and GSMCTL.

AUTHID DEFINER

Constants

Name	Data Type	Value
gsm_master_lock_name	VARCHAR2(19)	'ORA$GSM_MASTER_LOCK'
no_lock	NUMBER	99
rogueGSM	NUMBER	99
masterNotAllowed	NUMBER	98
MaxGSM	NUMBER	5
maxwait (wait forever)	NUMBER	32767

Data Types TYPE name_list_type IS TABLE OF VARCHAR2(dbms_gsm_common.max_ident) INDEX BY BINARY_INTEGER;

Dependencies

ALL_OBJECTS	DBMS_ISCHED	PARTITION_SET
ALL_SCHEDULER_EXTERNAL_DESTS	DBMS_LOCK	PLITBLM
AQ$_AGENT	DBMS_RLS	REGION
BROKER_CONFIGS	DBMS_SCHEDULER	REGION_SEQUENCE
CATALOG_REQUESTS	DBMS_SERVICE	SERVICE
CDB_SERVICES	DBMS_SYS_ERROR	SERVICE_PREFERRED_AVAILABLE
CHUNKDATA_TMP	DBMS_XDB_CONFIG	SHARDKEY_COLUMNS
CHUNKS	DDLID$	SHARD_GROUP
CHUNK_LOC	DDL_REQUESTS	SHARD_SPACE
CLOUD	DUAL	SHARD_TS
CREDENTIAL	FILES	TABLESPACE_SET
DATABASE	GLOBAL_TABLE	TABLE_FAMILY
DATABASE_POOL	GSM	TS_SET_TABLE
DATABASE_POOL_ADMIN	GSMLOGOFF	UTL_INADDR
DBMS_APPLICATION_INFO	GSM_LIST_T	UTL_TCP
DBMS_AQADM	GSM_REQUESTS	V$INSTANCE
DBMS_ASSERT	GSM_SEQUENCE	VERIFY_HISTORY
DBMS_GSM_ALERTS	GSM_SESSION	VERIFY_RUN_NUMBER
DBMS_GSM_COMMON	GSM_T	VNCR
DBMS_GSM_DBADMIN	GV$SESSION	VNCR_SEQUENCE
DBMS_GSM_POOLADMIN	GV_$ACTIVE_SERVICES	V_$DISPATCHER_CONFIG
DBMS_GSM_UTILITY	MESSAGE_PARAM	V_$PARAMETER2
DBMS_GSM_UTILITY_LIB	MESSAGE_PARAM_LIST

Documented No

Exceptions

Error Code	Reason
ORA-24035	AQ agent <string> is not a subscriber for queue GSMADMIN_INTERNAL.CHANGE_LOG_QUEUE
ORA-44891	GSM "<string>" was not found in the catalog

First Available 12.1

Security Model Owned by GSMADMIN_INTERNAL with EXECUTE granted to GSDADMIN_ROLE

Source {ORACLE_HOME}/rdbms/admin/dbmsgwmcl.sql

Subprograms

ADDDATABASEPOOL	DOENCRYPTGSMPWD	REMOVECATALOG
ADDDATABASEPOOLADMIN	GENDATAOBJNUMBER	REMOVECLOUD
ADDGSM	GETMASTERLOCK	REMOVEDATABASEPOOL
ADDREGION	IMPORTBEGIN	REMOVEDATABASEPOOLADMIN
ADDVNCR	IMPORTEND	REMOVEGSM
CANCELALLCHANGES	ISSYSUPDATE	REMOVEREGION
CAT_REDO_MARKER	MASKPOLICY	REMOVESUBSCRIBER
CHECKGSMDOWN	MODIFYCATALOG	REMOVEVNCR
CREATECATALOG	MODIFYGSM	SETENCRYPTEDDDL
CREATECLOUD	MODIFYREGION	SETENCRYPTEDGSMPWD
CREATESHARDCATALOG	POOLVPDPREDICATE	SYNCPARAMETERS
CREATESUBSCRIBER	RAN_CREATE_CATALOG	UNSET_CREATE_CATALOG
DISCONNECTGSM	RELEASEMASTERLOCK	VERIFYCATALOG

ADDDATABASEPOOL

Adds a database pool to the cloud dbms_gsm_cloudadmin.addDatabasePool( database_pool_name IN VARCHAR2, replication_type IN NUMBER DEFAULT NULL, pool_type IN NUMBER DEFAULT NULL);

TBD

ADDDATABASEPOOLADMIN

Adds an administrator for a database pool dbms_gsm_cloudadmin.addDatabasePoolAdmin( database_pool_name IN VARCHAR2 DEFAULT NULL, user_name IN VARCHAR2);

TBD

ADDGSM

Adds a GSM to the cloud dbms_gsm_cloudadmin.addGSM( gsm_name IN VARCHAR2, gsm_endpoint1 IN VARCHAR2, gsm_endpoint2 IN VARCHAR2, local_ons_port IN NUMBER, remote_ons_port IN NUMBER, region_name IN VARCHAR2 DEFAULT NULL, gsm_number OUT NUMBER, gsm_oracle_home IN VARCHAR2 DEFAULT NULL, gsm_hostname IN VARCHAR2 DEFAULT NULL);

TBD

ADDREGION

Adds a region to the cloud dbms_gsm_cloudadmin.addRegion( region_name IN VARCHAR2, buddy_name IN VARCHAR2 DEFAULT NULL);

TBD

ADDVNCR

Adds VNCR to Cloud

Overload 1 dbms_gsm_cloudadmin.addVNCR( name IN VARCHAR2, group_id IN VARCHAR2 DEFAULT NULL, updateRequestTable IN NUMBER DEFAULT dbms_gsm_utility.updateTrue);

TBD

Overload 2 dbms_gsm_cloudadmin.addVNCR( name IN VARCHAR2, group_id IN VARCHAR2 DEFAULT NULL, updateRequestTable IN NUMBER DEFAULT dbms_gsm_utility.updateTrue, hostname IN VARCHAR2 DEFAULT NULL, host_id OUT NUMBER, ignore_dups IN BOOLEAN DEFAULT TRUE);

TBD

CANCELALLCHANGES

Cancel (and rollback) all outstanding catalog changes dbms_gsm_cloudadmin.CancelAllChanges;

exec gsmadmin_internal.dbms_gsm_cloudadmin.CancelAllChanges;

CAT_REDO_MARKER

Undocumented dbms_gsm_cloudadmin.cat_redo_marker(mrk_type NUMBER);

exec dbms_gsm_cloudadmin.cat_redo_marker(1);

CHECKGSMDOWN

Checks whether a GSM is disconnecting from the catalog database. If it is a GSM then post the alert GSM down. dbms_gsm_cloudadmin.checkGSMDown;

exec gsmadmin_internal.dbms_gsm_cloudadmin.checkGSMDown;

CREATECATALOG

Create a GSM catalog dbms_gsm_cloudadmin.createCatalog( cloud_name IN VARCHAR2 DEFAULT NULL, autoVNCR IN NUMBER DEFAULT dbms_gsm_common.isTrue, instances IN NUMBER DEFAULT NULL, force IN NUMBER DEFAULT dbms_gsm_common.isFalse, agent_password IN VARCHAR2 DEFAULT NULL);

TBD

CREATECLOUD

Creates a cloud entry in the cloud catalog dbms_gsm_cloudadmin.createCloud( cloud_name IN VARCHAR2 DEFAULT NULL, autoVNCR IN NUMBER DEFAULT dbms_gsm_common.isTrue, instances IN NUMBER DEFAULT NULL, force IN NUMBER DEFAULT dbms_gsm_common.isFalse, agent_password IN VARCHAR2 DEFAULT NULL, repl IN NUMBER DEFAULT NULL, repfactor IN NUMBER DEFAULT NULL, chunks IN NUMBER DEFAULT NULL, protectmode IN NUMBER DEFAULT NULL, sharding IN NUMBER DEFAULT dbms_gsm_utility.not_sharded, agent_port IN NUMBER DEFAULT NULL);

TBD

CREATESHARDCATALOG

Undocumented dbms_gsm_cloudadmin.createShardCatalog( cloud_name IN VARCHAR2 DEFAULT NULL, autoVNCR IN NUMBER DEFAULT dbms_gsm_common.isTrue, force IN NUMBER DEFAULT dbms_gsm_common.isFalse, sdb IN VARCHAR2 DEFAULT 'orasdb', repl IN NUMBER DEFAULT dbms_gsm_common.reptype_dg, agent_password IN VARCHAR2 DEFAULT NULL, repfactor IN NUMBER DEFAULT NULL, chunks IN NUMBER DEFAULT NULL, protectmode IN NUMBER DEFAULT NULL, sharding IN NUMBER DEFAULT dbms_gsm_utility.sh_system, shardspace IN name_list_type DEFAULT CAST(NULL AS name_list_type), regions IN name_list_type DEFAULT CAST(NULL AS name_list_type), instances IN NUMBER DEFAULT NULL, agent_port IN NUMBER DEFAULT NULL);

TBD

CREATESUBSCRIBER

Add an AQ subscriber to the change log queue dbms_gsm_cloudadmin.createSubscriber(gsm_name IN VARCHAR2);

SQL> exec gsmadmin_internal.dbms_gsm_cloudadmin.createSubscriber('GSMSUBX');

      BEGIN gsmadmin_internal.dbms_gsm_cloudadmin.createSubscriber('GSMSUBX'); END;

      *

      ERROR at line 1:

      ORA-44891: GSM "GSMSUBX" was not found in the catalog

      ORA-06512: at "SYS.DBMS_SYS_ERROR", line 86

      ORA-06512: at "GSMADMIN_INTERNAL.DBMS_GSM_CLOUDADMIN", line 2308

      ORA-06512: at line 1

DISCONNECTGSM

Kills GSM session dbms_gsm_cloudadmin.disconnectGSM( gsm_name IN VARCHAR2, kill_level IN NUMBER DEFAULT 2);

exec gsmadmin_internal.dbms_gsm_cloudadmin.disconnectGSM('UWGSM');

DOENCRYPTGSMPWD

Encrypt database.GSM_PASSWORD and store in database.ENCRYPTED_GSM_PASSWORD dbms_gsm_cloudadmin.doencryptGSMPwd;

exec gsmadmin_internal.dbms_gsm_cloudadmin.doEncryptGSMPwd;

GENDATAOBJNUMBER

Generates a range of data object numbers

Overload 1 dbms_gsm_cloudadmin.genDataObjNumber( db_id IN NUMBER, curr_max IN NUMBER);

SQL> SELECT dbid FROM v$database;

      

            DBID

      ----------

       549318987

      

      exec gsmadmin_internal.dbms_gsm_cloudadmin.genDataObjNumber(549318987, 100);

      BEGIN gsmadmin_internal.dbms_gsm_cloudadmin.genDataObjNumber(549318987, 100); END;

      *

      ERROR at line 1:

      ORA-01403: no data found

      ORA-06512: at "GSMADMIN_INTERNAL.DBMS_GSM_CLOUDADMIN", line 3753

      ORA-06512: at "GSMADMIN_INTERNAL.DBMS_GSM_CLOUDADMIN", line 3736

      ORA-06512: at line 1

Overload 2 dbms_gsm_cloudadmin.genDataObjNumber( db_id IN NUMBER, curr_max IN NUMBER, min_num OUT NUMBER, max_num OUT NUMBER, no_commit IN NUMBER DEFAULT dbms_gsm_common.isFalse);

SQL> DECLARE

        2   maxN NUMBER;

        3   minN NUMBER;

        4  BEGIN

        5    gsmadmin_internal.dbms_gsm_cloudadmin.genDataObjNumber(549318987, 100, minN, maxN);

        6    dbms_output.put_line(TO_CHAR(minN));

        7    dbms_output.put_line(TO_CHAR(maxN));

        8  END;

        9  /

      DECLARE

      *

      ERROR at line 1:

      ORA-01403: no data found

      ORA-06512: at "GSMADMIN_INTERNAL.DBMS_GSM_CLOUDADMIN", line 3753

      ORA-06512: at line 5

GETMASTERLOCK

Request the GSM catalog master lock in exclusive mode dbms_gsm_cloudadmin.getMasterLock( timeout IN INTEGER DEFAULT MAXWAIT, lock_handle OUT VARCHAR2, gsm_name IN VARCHAR2 DEFAULT NULL, gsm_vers IN VARCHAR2 DEFAULT NULL ) RETURN INTEGER; -- Returns: -- 0 - success -- 1 - timeout -- 2 - deadlock -- 3 - parameter error -- 4 - already own lock -- 5 - illegal lock handle -- 99 - Lock not granted (due to GDS checking)

TBD

IMPORTBEGIN

Clear tables and other possibly important stuff dbms_gsm_cloudadmin.importBegin;

exec gsmadmin_internal.dbms_gsm_cloudadmin.importBegin;

IMPORTEND

Update sequences, and other possible stuff after successful import dbms_gsm_cloudadmin.importEnd;

exec gsmadmin_internal.dbms_gsm_cloudadmin.importEnd;

ISSYSUPDATE

Enforces VPD update restrictions for DDL requests

In the demo, at right, returns a predicate that will evaluate to FALSE dbms_gsm_cloudadmin.isSYSUpdate( obj_schema IN VARCHAR2, obj_name IN VARCHAR2) RETURN VARCHAR2;

SELECT gsmadmin_internal.dbms_gsm_cloudadmin.isSYSUpdate(USER, 'TAB$')

      FROM dual;

      

      GSMADMIN_INTERNAL.DBMS_GSM_CLOUDADMIN.ISSYSUPDATE(USER,'TAB$')

      --------------------------------------------------------------

                                                                 1=0

MASKPOLICY

Enforces VPD masking for select on database table dbms_gsm_cloudadmin.maskPolicy( obj_schema IN VARCHAR2, obj_name IN VARCHAR2) RETURN VARCHAR2;

SELECT gsmadmin_internal.dbms_gsm_cloudadmin.maskPolicy(USER, 'TAB$')

      FROM dual;

      

      GSMADMIN_INTERNAL.DBMS_GSM_CLOUDADMIN.MASKPOLICY(USER,'TAB$')

      --------------------------------------------------------------

      'GSMADMIN_ROLE' in (select granted_role from dba_role_privs where grantee = SYS_CONTEXT('USERENV', 'SESSION_USER') )

MODIFYCATALOG

Modifies information in the cloud catalog dbms_gsm_cloudadmin.modifyCatalog( autoVNCR IN NUMBER DEFAULT NULL, cat_region IN VARCHAR2 DEFAULT NULL, agent_password IN VARCHAR2 DEFAULT NULL, agent_port IN NUMBER DEFAULT NULL);

TBD

MODIFYGSM

Changes a GSM attributes dbms_gsm_cloudadmin.modifyGSM( gsm_name IN VARCHAR2, gsm_endpoint1 IN VARCHAR2 DEFAULT NULL, gsm_endpoint2 IN VARCHAR2 DEFAULT NULL, local_ons_port IN NUMBER DEFAULT NULL, remote_ons_port IN NUMBER DEFAULT NULL, region_name IN VARCHAR2 DEFAULT NULL);

TBD

MODIFYREGION

Modifies a region dbms_gsm_cloudadmin.modifyRegion( region_name IN VARCHAR2, buddy_name IN VARCHAR2 DEFAULT NULL, region_weights IN VARCHAR2 DEFAULT NULL);

TBD

POOLVPDPREDICATE

Enforces VPD read security for database pool tables dbms_gsm_cloudadmin.poolVPDPredicate( obj_schema IN VARCHAR2, obj_name IN VARCHAR2) RETURN VARCHAR2;

SELECT gsmadmin_internal.dbms_gsm_cloudadmin.poolVPDPredicate(USER, 'TAB$')

      FROM dual;

RAN_CREATE_CATALOG

Undocumented dbms_gsm_cloudadmin.ran_create_catalog RETURN BOOLEAN;

SQL> BEGIN

        2    IF gsmadmin_internal.dbms_gsm_cloudadmin.ran_create_catalog THEN

        3      dbms_output.put_line('T');

        4    ELSE

        5      dbms_output.put_line('F');

        6    END IF;

        7  END;

        8  /

      F

      

      PL/SQL procedure successfully completed.

RELEASEMASTERLOCK

Release the GSM catalog master lock acquired previously by getMasterLock dbms_gsm_cloudadmin.releaseMasterLock(lock_handle IN VARCHAR2) RETURN INTEGER;

Returns:
-- 0 - success
-- 3 - parameter error
-- 4 - don't own lock
-- 5 - illegal lock handle

TBD

REMOVECATALOG

Removes the Catalog dbms_gsm_cloudadmin.removeCatalog(removeCatalog(cloud_name IN VARCHAR2 DEFAULT NULL);

TBD

REMOVECLOUD

Removes the cloud entry from the cloud catalog dbms_gsm_cloudadmin.removeCloud(removeCloud(cloud_name IN VARCHAR2 DEFAULT NULL);

TBD

REMOVEDATABASEPOOL

Removes a database pool from the cloud dbms_gsm_cloudadmin.removeDatabasePool(database_pool_name IN VARCHAR2);

TBD

REMOVEDATABASEPOOLADMIN

Adds an administrator for a database pool dbms_gsm_cloudadmin.removeDatabasePoolAdmin( database_pool_name IN VARCHAR2 DEFAULT NULL, user_name IN VARCHAR2);

TBD

REMOVEGSM

Removes a GSM from the cloud dbms_gsm_cloudadmin.removeGSM(gsm_name IN VARCHAR2);

SQL> exec gsmadmin_internal.dbms_gsm_cloudadmin.removeGSM('UWGSM');

      BEGIN gsmadmin_internal.dbms_gsm_cloudadmin.removeGSM('UWGSM'); END;

      *

      ERROR at line 1:

      ORA-44891: GSM "UWGSM" was not found in the catalog

      ORA-06512: at "GSMADMIN_INTERNAL.DBMS_GSM_CLOUDADMIN", line 2233

      ORA-06512: at "SYS.DBMS_SYS_ERROR", line 86

      ORA-06512: at "GSMADMIN_INTERNAL.DBMS_GSM_CLOUDADMIN", line 2209

      ORA-06512: at line 1

REMOVEREGION

Removes a region from the cloud dbms_gsm_cloudadmin.removeRegion(region_name IN VARCHAR2);

TBD

REMOVESUBSCRIBER

Remove an AQ subscriber to the change log queue dbms_gsm_cloudadmin.removeSubscriber(gsm_name IN VARCHAR2);

SQL> exec gsmadmin_internal.dbms_gsm_cloudadmin.removeSubscriber('GSMSUBX');

      BEGIN gsmadmin_internal.dbms_gsm_cloudadmin.removeSubscriber('GSMSUBX'); END;

      *

      ERROR at line 1:

      ORA-24035: AQ agent GSMSUBX is not a subscriber for queue GSMADMIN_INTERNAL.CHANGE_LOG_QUEUE

      ORA-06512: at "SYS.DBMS_AQADM_SYS", line 10722

      ORA-06512: at "SYS.DBMS_AQADM_SYS", line 11090

      ORA-06512: at "SYS.DBMS_SYS_ERROR", line 95

      ORA-06512: at "SYS.DBMS_AQADM_SYS", line 10897

      ORA-06512: at "SYS.DBMS_AQADM_SYS", line 10710

      ORA-06512: at "SYS.DBMS_AQADM_SYS", line 10625

      ORA-06512: at "SYS.DBMS_AQADM", line 974

      ORA-06512: at "GSMADMIN_INTERNAL.DBMS_GSM_CLOUDADMIN", line 2344

      ORA-06512: at line 1

REMOVEVNCR

Removes VNCR from Cloud dbms_gsm_cloudadmin.removeVNCR( name IN VARCHAR2 DEFAULT NULL, group_id IN VARCHAR2 DEFAULT NULL);

TBD

SETENCRYPTEDDDL

Sets value for gsmadmin_internal.ddl_requests.DDL_TEXT dbms_gsm_cloudadmin.setEncryptedDDL( ddl_id IN NUMBER, enctxt IN RAW);

TBD

SETENCRYPTEDGSMPWD

Sets value for gsmadmin_internal.ddl_requests.DDL_TEXT dbms_gsm_cloudadmin.setencryptdGSMPwd( ddl_id IN NUMBER, enctxt IN RAW);

TBD

SYNCPARAMETERS

Syncronize spfile parameter values using database information dbms_gsm_cloudadmin.syncParameters;

exec gsmadmin_internal.syncParameters;

UNSET_CREATE_CATALOG

Undocumented dbms_gsm_cloudadmin.unset_create_catalog;

exec gsmadmin_internal.dbms_gsm_cloudadmin.unset_create_catalog;

VERIFYCATALOG

Perform cross-check verifications on the catalog data dbms_gsm_cloudadmin.verifyCatalog RETURN NUMBER;

SELECT gsmadmin_internal.dbms_gsm_cloudadmin.verifyCatalog

      FROM dual;

      

      VERIFYCATALOG

      -------------

                  1