Oracle | DBMS_GSM

Oracle DBMS_GSM_CLOUDADMIN Version 21c

General Information

Library Note

Morgan's Library Page Header

Which has the higher priority in your organization: Deploying a new database or securing the ones you already have? Looking for a website, and resources, dedicated solely to securing Oracle databases? Check out DBSecWorx.

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