This appendix includes a complete reference for the Global Data Services utility (GDSCTL) for Oracle Database.
This appendix includes the following topics:
This section contains topics that about using the GDSCTL utility.
The GDSCTL utility is a command-line interface for configuring and managing the Global Data Services framework. To run some commands, GDSCTL must establish a connection to a global service manager, a Global Data Services catalog database, or a database in the Global Data Services configuration.
Note:
Unless specified, GDSCTL resolves connect strings with the current name resolution methods (such as TNSNAMES). The exception is the global service manager name. GDSCTL queries thegsm.ora file to resolve the global service manager name.To start GDSCTL, enter the following command at the operating system prompt:
$ gdsctl
The preceding command starts GDSCTL and displays the GDSCTL command prompt. You can enter GDSCTL commands at either the operating system prompt or the GDSCTL command prompt, as shown in the following examples:
$ gdsctl add gsm -gsm gsm1 -catalog 127.0.0.1:1521:db1 GDSCTL> add gsm -gsm gsm1 -catalog 127.0.0.1:1521:db1
Both of the preceding commands achieve the same result. The first command is run at the operating system command prompt while the second command is run at the GDSCTL command prompt. The command syntax examples in this document use the GDSCTL command prompt.
Notes:
Many GDSCTL commands require you to first connect to the Global Data Services catalog before running the command.
If you run commands from the GDSCTL prompt, then you must execute the connect command before the first GDSCTL command that requires connection to the Global Data Services catalog. The connect command needs only to be run once in a GDSCTL session.
A net service name may be specified instead of a connect descriptor when adding a database or broker configuration to a GDS configuration. If a net service name is specified, it must be resolvable at each global service manager in the GDS configuration to a connect descriptor that allows connectivity to the entity that is being added.
Alternatively, you can gather all the GDSCTL commands in one file and run them as a batch with GDSCTL, as follows:
$ gdsctl @script_file_name
The preceding command starts GDSCTL and runs the commands contained in the specified script file.
You can display help for GDSCTL, as follows:
GDSCTL> help: The help command displays a summary of all GDSCTL commands. If you specify a command name after help, then the help text for that command displays.
GDSCTL> command -h: This syntax displays help text for the specified command, where command is the command name.
The following examples display identical help text for the start command:
GDSCTL> help start GDSCTL> start -h
Only users with the proper privileges can run GDSCTL commands.
See Also:
"Overview of Global Data Services Administration" for more information about GDSCTL privileges and securityFor certain operations GDSCTL must connect to a global service manager. To connect to a global service manager, GDSCTL must be running on the same host as the global service manager. When connecting to a global service manager, GDSCTL looks for the gsm.ora file associated with the local global service manager. Table A-1 lists the GDSCTL operations that require a connection to a global service manager.
Table A-1 Operations That Require a Connection to a Global Service Manager
| GSM Operation | Description |
|---|---|
|
Add a global service manager. |
|
|
Start the global service manager. |
|
|
Stop the global service manager. |
|
|
Modify the configuration parameters of the global service manager. |
|
|
Obtain the status of a global service manager. |
|
|
Set the |
|
|
Set the trace level for the listener associated with the specified global service manager. |
|
|
Set the timeout value for the outbound connections for the listener associated with a specific global service manager. |
|
|
Set the log level for the listener associated with a specific global service manager. |
For all other operations, GDSCTL uses Oracle Net Services to connect to the Global Data Services catalog database or another database in the Global Data Services configuration. For these connections you can run GDSCTL from any client or host that has the necessary network configuration.
GDSCTL Command Syntax and Options
GDSCTL commands, objects, and options; database names, instance names, Global Data Services region names, Global Data Services pool names, and service names are all case insensitive. Passwords and server pool names are also case sensitive. GDSCTL uses the following command syntax:
$ gdsctl command [object] [options] [argument] or GDSCTL> command [object] [options] [argument]
In GDSCTL syntax:
command: A verb such as add, start, stop, or remove
object (also known as a noun): The target or object on which GDSCTL performs the command, such as service or database. You can find a list of objects in Table A-3.
options: Optional flags that extend the use of a preceding command combination to include additional parameters for the command. For example, the -gdspool option indicates that the name of a specific Global Data Services pool follows. If a comma-delimited list follows an option, then do not use spaces between the items in the list.
argument: Additional variables for the GDSCTL command to specify actions for an object, or to specify actions for GDSCTL without an object.
Table A-2 Summary of GDSCTL Commands
| Command | Description |
|---|---|
|
Add a global service manager, region, database, database pool, invitednode, Oracle Data Guard broker configuration, or service to the Global Data Service management framework. |
|
|
Display the static configuration for databases, database pools, global service managers, services, and valid node checking for registration (VNCR). |
|
|
Set the GDSCTL parameters. |
|
|
Specify the credentials to use for the current GDSCTL session. |
|
|
Create a Global Data Services catalog in a specified database. |
|
|
Delete a Global Data Services catalog. |
|
|
Disable a global service. |
|
|
Enable a global service. |
|
|
Modify catalog, databases, database pools, regions, or services. |
|
|
Move a global service from one database to another. |
|
|
Remove global service managers, regions, databases, database pools, invitednode, services, or Oracle Data Guard broker configurations. |
|
|
Display information about the services registered with a specific global service manager. |
|
|
Set the current global service manager for the current session and sets various run-time parameters of the local global service manager. |
|
|
Start a global service manager or global services. |
|
|
Show status of global service managers, regions, databases, database pools, or services. |
|
|
Stop a global service manager or global services. |
|
|
Synchronize the Oracle Data Guard broker configuration in the global service manager with the configuration in the database pool. |
|
|
|
Bring attributes of global services and GDS related parameters of a pool database in synchronization with the contents of the GDS catalog. |
|
Cross check the Global Data Services catalog, global service manager run-time status, and pool databases, and reports any inconsistencies and errors. |
Table A-3 lists the keywords that you can use for the object portion of GDSCTL commands. You can use either the full name or the abbreviation for each object keyword. The Purpose column describes the object and the actions that can be performed on that object.
Table A-3 Object Keywords and Abbreviations for GDSCTL
| Object | Keyword (Abbreviations) | Purpose |
|---|---|---|
|
|
Enables or disables valid node checking for registration (VNCR) list for database registration |
|
|
|
To add, modify, and manage the Oracle Data Guard broker configuration. The Oracle Data Guard broker logically groups primary and standby databases into a broker configuration that enables the broker to manage and monitor them together as an integrated unit. |
|
|
|
To manage the Global Data Services catalog stored in an Oracle database. |
|
|
|
To add, modify, and remove database configuration information about databases. |
|
|
|
To add, modify, and manage a Global Data Services pool. A Global Data Services pool is a set of databases within a GDS configuration that provides a unique set of global services and belongs to a certain administrative domain. |
|
|
|
To add, modify, and manage a global service manager. A global service manager is a software component that provides service-level load balancing and centralized management of services within the Global Data Services configuration. |
|
|
Global Data Services catalog |
invitednode |
Adds host address information to the valid node checking for registration (VNCR) list in the Global Data Services catalog. |
|
Global Data Services catalog |
invitedsubnet |
Adds subnet information to the valid node checking for registration (VNCR) list in the Global Data Services catalog |
|
|
To add, modify, and manage a Global Data Services Region, which is a logical boundary that contains database clients and servers that are considered to be geographically close to each other. |
|
|
|
To add, modify, list the configuration of, enable, disable, start, stop, obtain the status of, relocate, and remove global services. |
The gdsctl add command adds elements to the global service manager configuration. Table A-4 describes the add command variations.
Table A-4 gdsctl add command Summary
| Command | Description |
|---|---|
|
Adds an Oracle Data Guard configuration to a Global Data Services pool |
|
|
Adds a database to a Global Data Services region or Global Data Services pool |
|
|
Adds a Global Data Services pool to the configuration and optionally configures pool administrator users |
|
|
Adds a global service manager to the configuration |
|
|
Adds a host or IP address to a VNCR list in the Global Data Services catalog |
|
|
Adds a Global Data Services region to the configuration |
|
|
Adds a global service to the configuration |
Adds an Oracle Data Guard broker configuration to a Global Data Services pool.
Use the gdsctl add brokerconfig command with the following syntax:
add brokerconfig [-gdspool gdspool_name] -connect connect_identifier [-region region_name] [-pwd password] [-savename]
Table A-5 gdsctl add brokerconfig Options
| Option | Description |
|---|---|
-connect connect_identifier
|
Specify an Oracle Net connect descriptor or net service name that resolves to a connect descriptor for a database in the broker configuration. |
-gdspool gdspool_name
|
The pool to which the databases of the Oracle Data Guard broker configuration are to be added. If the specified Global Data Services pool already contains databases or another configuration, GDSCTL returns an error. |
-pwd password
|
The password for the GSMUSER. If |
-region region_name
|
The Global Data Services region to which the databases belong. If you specify a region, then all the databases are added to that region. If you do not specify a region, then all databases are added with a region of UNASSIGNED. If the region is UNASSIGNED, then you must use the |
-savename |
Specify this option to store a net service name specified with the |
You must connect to the Global Data Services catalog database as a user with the pool administrator privileges, using the connect command before running this command
Add the Oracle Data Guard broker configuration for the DB1 database to the Global Data Services pool MYREADERFARM and the WEST region.
GDSCTL> add brokerconfig -connect 192.168.1.1:1521:sid -region west -gdspool myreaderfarm
GDSCTL returns the errors listed in Table A-6 if you use this command incorrectly.
Table A-6 gdsctl add brokerconfig Exceptions or Error Codes
| Exception | Description |
|---|---|
|
|
A pool can only contain one Data Guard broker configuration. If a Global Data Services pool already contains an Oracle Data Guard broker configuration, then GDSCTL returns error 44866 because a database must be added using Oracle Data Guard in this case. |
Adds databases to a Global Data Services region and Global Data Services pool.
Use the gdsctl add database command with the following syntax:
add database -connect connect_identifier -[region region_name] [-gdspool gdspool_name] [-pwd password] [-savename] [-cpu_threshold cpu] [-disk_threshold disk]
Table A-7 gdsctl add database Options
| Option | Description |
|---|---|
-connect connect_identifier
|
Specify an Oracle Net connect descriptor or net service name that resolves to a connect descriptor for the database being added. |
-cpu_threshold cpu
|
Specifies CPU Utilization percentage threshold. |
-disk_threshold disk
|
Specifies the average latency in milliseconds of a synchronous single-block read. |
-gdspool gdspool_name
|
The Global Data Services pool to which the database belongs. |
-pwd password
|
The password for the GSMUSER. If |
-region region_name
|
The Global Data Services region to which the database belongs. |
-savename |
Specify this option to store a net service name specified with the |
You must connect to the Global Data Services catalog database as a user with the pool administrator privileges, using the connect command before running this command.
If -savename is not specified, then GDSCTL replaces what you specify for the net service name with the full connection string before saving the configuration to the catalog.
The default for GDSCTL is for autovncr to be enabled for the catalog. If autovncr has been disabled for the catalog, before configuring Global Data Services pools and adding databases to the Global Data Services configuration, the nodes where those databases run must be part of the valid node checking for registration (VNCR) list for database registration. Use the add invitednode (add invitedsubnet) command to define the valid nodes.
Adds database DB1 to the WEST region and Global Data Services pool MYREADERFARM.
GDSCTL> add database -connect 127.0.0.1:1521:db1 -region west -gdspool myreaderfarm
Adds a database using myalias instead of the IP address connection string.
GDSCTL> add database -connect myalias -gdspool myreaderfarm
GDSCTL returns the errors listed in Table A-8 if you use this command incorrectly.
Table A-8 gdsctl add database Exceptions or Error Codes
| Exception | Description |
|---|---|
|
|
If a pool already contains an Oracle Data Guard broker configuration, then GDSCTL returns an error; you must add databases using Oracle Data Guard in this case. That is, if a pool contains an Oracle Data Guard broker configuration, then additional databases can only be added to the pool by adding them to that DG broker configuration. |
|
|
If the database being added is part of a Oracle Data Guard broker configuration, then GDSCTL returns an error; you must use the |
Adds a Global Data Services pool to the Global Data Services framework. When the Global Data Services catalog is created, a default pool named DBPOOLORA is created, automatically.
Use the gdsctl add gdspool command with the following syntax:
add gdspool -gdspool database_pool_list [-users user_list]
Table A-9 gdsctl add gdspool Options
| Option | Description |
|---|---|
-gdspool database_pool_list
|
A comma-delimited list of Global Data Services pool names. A Global Data Services pool must have a unique name within its GDS configuration. If you do not specify a name for the pool when you create it, then the name defaults to |
-users user_list
|
A comma-delimited list of users that are granted the pool administrator role. |
You must connect to the Global Data Services catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command.
The default for GDSCTL is for autovncr to be enabled for the catalog. If autovncr has been disabled for the catalog, then before configuring Global Data Services pools and adding databases to the Global Data Services configuration, the nodes where those databases run must be part of the valid node checking for registration (VNCR) list for database registration. Use the add invitednode (add invitedsubnet) command to define the valid nodes.
Add a Global Data Services pool named MYREADERFARM to the configuration:
GDSCTL> add gdspool -gdspool myreaderfarm
Adds a global service manager to the Global Data Services framework. You must specify the Global Data Services catalog database when using this command.
Use the gdsctl add gsm command with the following syntax:
add gsm -gsm gsm_name -catalog connect_id [-pwd password] [-wpwd password] [-region region_name] [-localons ons_port] [-remoteons ons_port] [-listener listener_port] [-endpoint gmsendpoint] [-remote_endpoint remote_endpoint] [-trace_level level]
Table A-10 gdsctl add gsm Options
| Option | Description |
|---|---|
-catalog connect_id
|
Specify the connect identifier for the Global Data Services catalog database. If a network service name is specified, it must be resolvable by the local naming method to a connect descriptor that allows the global service manager being added to connect to the catalog database. |
-endpoint gsmendpoint
|
Specifies the protocol address that the global services manager listens on for client connection requests. If you use this option, the value that you specify overrides the default endpoint. |
-gsm gsm_name
|
Specify the name of the global service manager that you want to add. If you do not specify a name, then GDSCTL uses the current global service manager name for the session (specified with the |
-listener listener_port
|
Specify the listener port. The default port is 1522. |
-localons ons_port
|
Specify the local ONS port. If you do not specify this option, then GDSCTL uses the default ONS port (which is 6123 on most platforms). |
-pwd password
|
Specify the password for the |
-region region_name
|
Specify the region to which the global service manager belongs. The value for |
-remote_endpoint remote_endpoint
|
Specifies the protocol address that is used by the global service manager to receive database registration requests and communicate with other global service managers in the configuration. If you use this option, the value that you specify overrides the default endpoint. |
-remoteons ons_port
|
Specify the remote ONS port. If you do not specify this option, then GDSCTL uses the default ONS port (which is 6234 on most platforms). |
-trace_level level
|
Specify the global service manager trace level (to be used as directed by Oracle Support Services). |
|
|
Specify a password to protect the global service manager wallet. If a wallet password is not specified, a system-generated password is used instead. Note that if a password is specified with this option, the wallet cannot be modified without supplying that password. |
You must run this command, locally, on the computer where you want to add the global service manager.
You must have operating system privileges on the computer where you want to add the global service manager to run this command.
When you run this command, GDSCTL connects to the Global Data Services catalog as the GSMCATUSER user and prompts you for the GSMCATUSER password.
Add a global service manager named gsm1, specifying the location of the Global Data Services catalog database, DB1.
GDSCTL> add gsm -gsm gsm1 -catalog 127.0.0.1:1521:db1
Adds host address or subnet information to the valid node checking for registration (VNCR) list in the catalog. This command enables you to add a host or a subnet to the VNCR list before starting the first global service manager (by establishing a direct connection to the Global Data Services catalog database).
VNCR enables or denies access from specified IP addresses to Oracle services. See Oracle Database Net Services Administrator's Guide for more information about VNCR.
Use the gdsctl add invitednode command with the following syntax:
add {invitednode | invitedsubnet} [-group group_name]
[-catalog catalog_dbname [-user user_name/password]] vncr_id
Table A-11 gdsctl add invitednode Options
| Option | Description |
|---|---|
-catalog catalog_dbname
|
Specify the Global Data Services catalog database net alias or connect string. If you enter an invalid address or connect string, then GDSCTL uses the pre-established connection created with the |
-group group_name
|
Specify an alias which defines a group of invited nodes. This alias can be referenced in other commands related to invited nodes. |
-user user_name[/password] |
Specify the user credentials for the Global Data Services administrator in the catalog database. If you do not specify a user or a password, then GDSCTL prompts you this information. |
vncr_id
|
Specify the list of nodes that can register with the global service manager. The list can include host names or CIDR notation for IPv4 and IPv6 addresses. The wildcard format (*) is supported for IPv4 addresses. The presence of a host name in the list results in the inclusion of all IP addresses mapped to the host name. The host name should be consistent with the public network interface. |
You must connect to the Global Data Services catalog database as a user with the pool administrator privileges, using the connect command before running this command.
The default for GDSCTL is that autovncr is enabled for the catalog. If autovncr has been disabled for the catalog, before configuring Global Data Services pools and adding databases to the Global Data Services configuration, then the nodes where those databases run must be part of the valid node checking for registration (VNCR) list for database registration. Use the add invitednode (add invitedsubnet) command to define the valid nodes.
Add the netmask 255.255.255.248 to the catalog.
GDSCTL> add invitednode 255.255.255.248
Add the server east1.example.com to the catalog in the alias group EAST_SRV.
GDSCTL> add invitednode east1.example.com
Add the server east2.example.com to the catalog in the alias group EAST_SRV.
GDSCTL> add invitednode east2.example.com
Adds a Global Data Services region to the Global Data Services framework. When the Global Data Services catalog is created, the REGIONORA region is created automatically.
Use the gdsctl add region command with the following syntax:
add region -region region_list [-buddy region_name]
Table A-12 gdsctl add region Options
| Option | Description |
|---|---|
-buddy region_name
|
Specify the name of the buddy region. |
-region region_list
|
Specify a comma-delimited list of Global Data Services region names. A Global Data Services region should have a name that is unique within the corresponding Global Data Services configuration. If no name is specified at the first region creation time, the default name, oraregion, is given to the region. The region name can be up to 30 characters long and can be any valid identifier - an alphabetical character followed by zero or more alphanumeric ASCII characters or '_'. |
You must connect to the Global Data Services catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command
Add two Global Data Services regions, EAST and WEST to the current configuration:
GDSCTL> add region -region east,west
Add a global service to a Global Data Services pool.
Use the gdsctl add service command with the following syntax:
add service [-gdspool gdspool_name] -service service_name {-preferred_all | -preferred dbname_list [-available dbname_list] } [-locality {ANYWHERE | LOCAL_ONLY [-region_failover]}] [-role {PRIMARY | PHYSICAL_STANDBY [-failover_primary] | LOGICAL_STANDBY | SNAPSHOT_STANDBY}] [-lag {lag_value | ANY}] [-notification {TRUE | FALSE}] [-rlbgoal {SERVICE_TIME | THROUGHPUT}] [-dtp {TRUE | FALSE}] [-sql_translation_profile stp_name] [-clbgoal {SHORT | LONG}] [-tafpolicy {BASIC | NONE | PRECONNECT}] [-policy policy] [-failovertype {NONE | SESSION | SELECT | TRANSACTION}] [-failovermethod {NONE | BASIC}] [-failoverretry failover_retries] [-failoverdelay failover_delay] [-edition edition_name] [-commit_outcome {TRUE | FALSE}] [-retention retention_seconds] [-session_state {DYNAMIC | STATIC}] [-replay_init_time replay_init_time] [-pdbname pdbname]
Table A-13 gdsctl add service Options
| Option | Description |
|---|---|
-available dbname_list
|
Specify a comma-delimited list of available databases on which the service runs if the preferred databases are not available. You cannot specify a list of available instances, only databases. You can use the The list of available databases must be mutually exclusive with the list of preferred databases. You cannot use this option with the |
-clbgoal {SHORT | LONG}
|
Connection Load Balancing Goal. Use a value of The default value for this option is |
-commit_outcome {TRUE | FALSE}
|
Enable Transaction Guard; when set to |
-dtp {TRUE | FALSE}
|
Indicates whether Distributed Transaction Processing should be enabled for this service. This service can either be a service in a policy-managed database or a preferred service on a single node in an administrator-managed database. |
-edition edition_name
|
Specify the initial session edition of the service. When an edition is specified for a service, all subsequent connections that specify the service use this edition as the initial session edition. However, if a session connection specifies a different edition, then the edition specified in the session connection is used for the initial session edition. GDSCTL does not validate the specified edition name. During connection, the connect user must have |
-failover_primary |
If you set the |
-failoverdelay failover_delay
|
For Application Continuity and TAF, this parameter specifies the time delay (in seconds) between reconnect attempts for each incident at failover. |
-failovermethod {NONE | BASIC}
|
TAF failover method (for backward compatibility only). If the failover type ( |
-failoverretry failover_retries
|
For Application Continuity and TAF, this parameter determines the number of attempts to connect after an incident. |
-failovertype {NONE | SESSION | SELECT | TRANSACTION}
|
Specify the failover type. To enable Application Continuity for Java, set this parameter to |
-gdspool gdspool_name
|
Specify the name of the Global Data Services pool to which you want to add a service. If the pool name is not specified and there is only one |
-lag {lag_value | ANY}
|
Specify the lag for the service in seconds. You can use the keyword The default value for |
-locality {ANYWHERE | LOCAL_ONLY}
|
Specify the service region locality. If you do not specify this option, then GDSCTL uses the default value of |
-notification {TRUE | FALSE}
|
Enable Fast Application Notification (FAN) for OCI connections. |
-pdbname pdb_name
|
Specify the pluggable database name. |
-policy {AUTOMATIC | MANUAL}
|
Specify the management policy for the service. If you specify If you specify |
-preferred dbname_list
|
Specify a comma-delimited list of preferred databases on which the service runs. You cannot specify preferred instances, only databases. You can use the The list of preferred databases must be mutually exclusive with the list of available databases. You cannot use this option with the |
-preferred_all |
Specifies that all the databases in the Global Data Services pool are preferred databases. Any databases you later add to the pool are configured as preferred databases for this service. You cannot use this option with the |
-region_failover |
Indicates that the service is enabled for region failover. You can only use this option when you specify |
-replay_init_time replay_init_time
|
For Application Continuity, this parameter specifies the time (in seconds) after which replay cannot be initiated. The default value is 300 seconds. |
-retention retention_seconds
|
If commit_outcome is set to |
-rlbgoal {SERVICE_TIME | THROUGHPUT}
|
Run-time Load Balancing Goal (for the Load Balancing Advisory). Set this parameter to If you do not use this option, then the value defaults to |
-role {[PRIMARY] | [PHYSICAL_STANDBY] [-failover_primary] |[LOGICAL_STANDBY] |[SNAPSHOT_STANDBY]}
|
Specify the database role that the database must be for this service to start on that database. This applies only to Global Data Services pools that contain an Oracle Data Guard broker configuration. See Also: Oracle Data Guard Concepts and Administration for more information about database roles |
-service service_name
|
Specify the name of the global service. The service name specified in the A global service name must be unique within a GDS pool and when qualified by domain, must also be unique within a GDS configuration. A global service cannot be created at a database if a local or global service with the same name already exists at that database. A global service name can contain alphanumeric characters, underscore (_), and period (.). The first character must be alphanumeric. The maximum length of a global service name is 64 characters. The maximum length of a domain qualified global service name is 250 characters. An Oracle Net connect descriptor used to connect to a global service must contain a domain qualified service name. |
-session_state
{DYNAMIC | STATIC}
|
For Application Continuity, this parameter specifies whether the session state that is not transactional is changed by the application. A setting of |
-sql_translation_profile stp_name
|
Use this option to specify a SQL translation profile for a service that you are adding after you have migrated applications from a non-Oracle database to an Oracle database. This option corresponds to the SQL translation profile parameter in the Notes:
See Also: Oracle Database Migration Guide for more information about SQL translation |
-tafpolicy {BASIC | NONE }
|
TAF policy specification (for administrator-managed databases only). |
Add a service named sales_report to the Global Data Services pool MYREADERFARM with a value of ANYWHERE for the locality.
GDSCTL> add service -gdspool myreaderfarm -service sales_report -locality ANYWHERE
Add a service named daily_sales_rept to the Global Data Services pool MYDGPOOL with preferred instance set to DB1 and the available instances set to DB3 and DB4. The service should use the basic transaction failover policy.
GDSCTL> add service -gdspool mydgpool -s daily_sales_rept -preferred db1 -available db3,db4 -tafpolicy BASIC
See Also:
"Creating a Global Service"The gdsctl config command displays the static configuration of the specified component or set of components. This configuration data is retrieved from the catalog database. You can also use this command with no options to display the configuration data for all components defined for the configuration. When using the config command, it does not matter if the components (except for the catalog database) are started.
Table A-14 gdsctl config Summary
| Command | Description |
|---|---|
|
Displays the static configuration data for the specified database. |
|
|
Displays the static configuration data for the specified database pool. |
|
|
Displays the static configuration data for the specified global service manager. |
|
|
Displays the static configuration data for the specified region. |
|
|
Displays the static configuration data for the specified region. |
|
|
Displays the VNCR configuration data for the specified global service manager. |
Displays the static configuration data stored in the catalog for the specified database.
Use the gdsctl config database command with the following syntax:
config database [-database db_name]
Table A-15 gdsctl config database Options
| Syntax | Description |
|---|---|
-database db_name
|
Specify the name of a database. If you do not specify a database name, then GDSCTL displays the configuration data for all databases in the Global Data Services configuration. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command
Display the static configuration data stored in the catalog for all the databases in the Global Data Services configuration.
GDSCTL>config database
The gdsctl config database command returns information similar to the following:
Name Pool Status Region ---- ---- ------ ------ dbcat sales Ok east dbcat1 sales Ok west dbcat3 sales Ok west
Displays the static configuration data that is stored in the catalog for the specified database pool.
Use the gdsctl config gdspool command with the following syntax:
config gdspool [-gdspool gdspool_name]
Table A-16 gdsctl config gdspool Options
| Syntax | Description |
|---|---|
-gdspool gdspool_name
|
Specify the name of a database pool. If you do not specify a database pool name, then GDSCTL displays the configuration data for all database pools. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command
Display the static configuration data stored in the catalog for all Global Data Services pools.
GDSCTL>config gdspool
The gdsctl config gdspool command returns output similar to the following:
Name Broker ---- ------ dbpoolora No mkt No sales No marketing No
The following command shows the configuration detail of Global Data Services pool marketing.
GDSCTL>config gdspool -gdspool marketing
The above example returns output similar to the following:
GDS Pool administrators ------------------------ Databases ------------------------ dbcat2 dbcat1 dbcat3 Services ------------------------ sales_report sales_analysis sales_estimation sales_peragent sales_global
Displays the static configuration data stored in the catalog for the specified global service manager.
Use the gdsctl config gsm command with the following syntax:
config gsm [-gsm gsm_name]
Table A-17 gdsctl config gsm Options
| Syntax | Description |
|---|---|
-gsm gsm_name
|
Specify the name of a global service manager. If you do not specify a global service manager name, then GDSCTL displays the static configuration data for all global service managers in the cloud. |
You must connect to the catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command
Display the static configuration data stored in the catalog for the global service manager mygsm:
GDSCTL>config gsm -gsm mygsm
The gdsctl config gsm command returns information similar to the following:
Name: mygsm Endpoint 1: (ADDRESS=(HOST=stcal.us.hq.com)(PORT=1523)(PROTOCOL=tcp)) Endpoint 2: (ADDRESS=(HOST=stcal.us.hq.com)(PORT=1523)(PROTOCOL=tcp)) Local ONS port: 6123 Remote ONS port: 6234 Region: east Buddy ------------------------
Displays the static configuration data for the specified region.
Use the gdsctl config region command with the following syntax:
config region [-region gsm_name]
Table A-18 gdsctl config region Options
| Syntax | Description |
|---|---|
-region gsm_name
|
Specify the name of a global service manager. |
Displays the static configuration data for the specified region.
GDSCTL>config region -region eastcoast
Displays the following output:
Databases ------------------------ debug msvc4 GSM ------------------------ mygsm
Displays the static configuration data stored in the Global Data Services catalog for the specified services that are located in a database pool.
Use the gdsctl config service command with the following syntax:
config service [-gdspool gdspool_name] [-service service_name]
Table A-19 gdsctl config service Options
| Syntax | Description |
|---|---|
-gdspool gdspool_name
|
Specify the name of the database pool that contains the services. If the name is not specified, and there is only one |
-service service_name
|
Specify a comma-delimited list of service names. If you do not use this option, then GDSCTL displays the configuration data for all services in the specified database pool. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command
Show all the services in the user's Global Data Services pool:
GDSCTL>config service
The gdsctl config service command returns information similar to the following:
Name Network name Pool Started Preferred all ---- ------- ---- ---- ------- --------- --- sales_svc1 sales_svc1.sales.oradbcloud sales Yes Yes sales_svc2 sales_svc2.sales.oradbcloud sales NO Yes sales_svc3 sales_svc3.sales.oradbcloud sales Yes Yes mkt_svc1 mkt_svc1.mkt.oradbcloud mkt NO Yes
Display the static configuration data stored in the Global Data Services catalog for sales_svc1:
GDSCTL>config service -service sales_svc1
returns:
Name: sales_svc1 Network name: sales_svc1.sales.oradbcloud Pool: sales Started: Yes Preferred all: Yes Locality: ANYWHERE Region Failover: No Role: NONE Primary Failover: No Lag: ANY Runtime Balance: SERVICE_TIME Connection Balance: SHORT Notification: Yes TAF Policy: NONE Policy: AUTOMATIC DTP: No Failover Method: NONE Failover Type: NONE Failover Retries: Failover Delay: Edition: PDB: Commit Outcome: Retention Timeout: Replay Initiation Timeout: Session State Consistency: SQL Translation Profile: Supported services ------------------------ Database Preferred Status -------- --------- ------ dbcat2 Yes Enabled dbcat1 Yes Enabled dbcat3 Yes Enabled
Displays the static configuration data stored in the catalog for valid node checking for registration (VNCR).
Use the gdsctl config vncr command with the following syntax:
config vncr [-group gsm_name]
Table A-20 gdsctl config invitednode Options
| Syntax | Description |
|---|---|
-group gsm_name
|
Specify the name of a global service manager. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command
Displays the list of hosts in the VNCR list:
GDSCTL>config vncr
The gdsctl config vncr command returns information similar to the following:
Name Group ID ---- ----- -- example 22.231.113.64 example.com
The gdsctl configure command sets the GDSCTL parameters.
Use the gdsctl configure command with the following syntax:
configure [-gsmport port] [-timeout seconds] [-show] [-driver {THIN | OCI}] [-resolve {IP | HOSTNAME | QUAL_HOSTNAME}] [-log {ALL|OFF|INFO|FINE|FINER|FINEST|SEVERE|WARNING}] [-log_file log_file] [-gsm gsm_name]
Table A-21 gdsctl configure Options
| Syntax | Description |
|---|---|
-driver THIN | OCI |
Oracle JDBC driver. |
-gsm gsm_name
|
Set current global service manager. |
-gsmport port
|
Default global service manager port. |
-log {ALL | OFF | INFO | FINE |
FINER | FINEST | SEVERE |
WARNING}
|
Set the logging level. The default is |
-log_file log_file
|
Set the location of the log file. The default is |
-resolve IP | HOSTNAME| QUAL_HOSTNAME |
Default host resolution for global service manager endpoint. |
-show |
Show the configuration. |
-timeout seconds
|
Global service manager requests timeout in seconds. |
Set the mygsm driver to OCI:
configure -driver OCI mygsm
The gdsctl connect command specifies the credentials to administer a global service management environment. Credentials must be specified to perform certain operations using GDSCTL.
Use the gdsctl connect command with the following syntax:
connect [user_name[/password]]@connect_identifier
Table A-22 gdsctl connect Options
| Syntax | Description |
|---|---|
connect_identifier
|
Specify an Oracle Net connect descriptor or a net service name that maps to a connect descriptor (for example, a list of global service managers). |
password
|
Specify the password for the specified user. If you do not specify a password, then you are prompted to enter a password. The password is obscured when entered. |
user_name
|
Specify the name of the user to connect as. The user that you specify must have either the Global Data Services administrator or the pool administrator role. If you specify no user name, then you are prompted for a user name. |
You must connect to the catalog database as a user with either the Global Data Services administrator or the pool administrator privileges, depending on which command you want to run after you connect
WARNING:
Specifying a password as a connect command option is a security risk. You can avoid this risk by omitting the password, and entering it only when the system prompts for it.
Connect as the gsmadmin user to the private cloud:
GDSCTL> connect gsmadmin@mycloud Enter password:
Connect using a connect descriptor, without specifying a user name and password:
GDSCTL> connect (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=myhost)(PORT=1521))) Enter username:
The gdsctl create catalog command creates a Global Data Services catalog for global service management in a specific database. It also generates a pair of PKI public and private keys and stores them in the catalog, along with a fixed string "GSM" that is encrypted with a private key. It uses the GSMCATUSER password.
Use the gdsctl create catalog command with the following syntax:
create catalog -database connect_id [-user user_name[/password] [-region region_list] [-gdspool gdspool_list] [-configname config_name] [-autovncr {ON | OFF}] [-force]
Table A-23 gdsctl create catalog Options
| Syntax | Description |
|---|---|
-autovncr {ON | OFF}
|
This option enables ( |
-configname config_name
|
Specify the name of the GDS configuration. The default configuration name is The configuration name can be up to 32 bytes long and can contain an alphabetical character followed by zero or more alphanumeric ASCII characters, ’_', or ’#' and possibly separated by periods if there are multiple identifiers. |
-database connect_id
|
Specify the connect identifier for the database in which you want to create catalog. |
-force |
Rewrites existing global service manager configuration on catalog database. |
-gdspool gdspool_list
|
Specify a comma-delimited list of database pool names. When you use this option, the specified database pools are created as part of the catalog creation. If you do not specify this option, then GDSCTL creates a default database pool named DBPOOLORA. |
-region region_list
|
Specify a comma-delimited list of region names. This command creates each region and adds the regions to the catalog. If you do not specify a region, then a default region named REGIONORA is created. |
-user user_name[/password] |
Specify a user (and optionally, the password) that has the Global Data Services administrator privileges on the catalog database. If you do not use this option, then GDSCTL prompts you for the name and the password of a user with Global Data Services administrator privileges. If you specify a user name but not the password for the user, then GDSCTL prompts you for the password. |
You must have the Global Data Services administrator privileges on the computer where you want to create the Global Data Services catalog.
Auto VNCR is best used in environments with simple private networks where ease of configuration is the most important consideration. To have the highest level of control over which hosts may participate in a GDS configuration, disable Auto VNCR and explicitly add the IP address(es) of each database host to the VNCR configuration.
Create a Global Data Services catalog for global service management in the database named DB1. Also create the regions EAST and WEST, and the database pool READERFARM.
GDSCTL> create catalog -database db1 -region west,east -gdspool readerfarm
The gdsctl delete catalog command deletes the Global Data Services catalog.
Use the gdsctl delete catalog command with the following syntax:
delete catalog [-connect connect_identifier]
Table A-24 gdsctl delete catalog Options
| Syntax | Description |
|---|---|
-connect connect_identifier
|
Specify an Oracle Net connect descriptor or a net service name that maps to a connect descriptor. If you do not use this option, then GDSCTL deletes the Global Data Services catalog that is used by the global service manager associated with the current session. |
You must have the Global Data Services administrator privileges on the computer where the database resides from which you want to delete the Global Data Services catalog
Delete the Global Data Services catalog located in the database named DB1.
GDSCTL> delete catalog -connect db1.example.com
The gdsctl disable service command disables specified services. The specified services are also stopped.
Use the gdsctl disable service command with the following syntax:
disable service [-gdspool gdspool_name] [ -service service_name_list] -database db_name
Table A-25 gdsctl disable service Options
| Syntax | Description |
|---|---|
-database db_name
|
Specify the name of the database on which to the service is located. If you do not specify this option, then the service is disabled, globally. |
-gdspool gdspool_name
|
Specify the database pool in which the services are located. If not specified and there is only one |
-service service_name_list
|
Specify a comma-delimited list of global service names. If you do not use |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command
Disable and stop the service G_SALES_REPORT on all databases in the database pool READERFARM.
GDSCTL> disable service -gdspool readerfarm -service g_sales_report
See Also:
"Disabling a Global Service"The gdsctl enable service command enables the specified services. If the cardinality for a service has not been reached, then this command also starts that service.
Use the gdsctl enable service command with the following syntax:
enable service [-gdspool gdspool_name] [-service service_name] -database db_name
Table A-26 gdsctl enable service Options
| Syntax | Description |
|---|---|
-database db_name
|
Specify the name of the database on which the service is located. If you do not specify this option, then the service is enabled globally. |
-gdspool gdspool_name
|
Specify the database pool in which the services are located. If not specified and there is only one |
-service service_name
|
Specify a comma-delimited list of global service names. If you do not use |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command
Enable the service G_SALES_REPORT on the database DB1 in the database pool READERFARM.
GDSCTL> enable service -gdspool readerfarm -service g_sales_report -database db1
See Also:
"Enabling a Global Service"The gdsctl export catalog command saves the current catalog configuration to a local file.
Use gdsctl export catalog command with the following syntax:
export catalog file_name
Table A-27 gdsctl export catalog Options
| Syntax | Description |
|---|---|
file_name
|
Name of a file on the same computer where the command is being executed. The configuration will be saved to this file. If the file already exists, it will be overwritten without a prompt. If the file is not writable (for example the path does not exist), you will get an error. |
You must connect to the catalog database as a user with GDS Administrator privileges before running this command.
It is recommended that you validate the catalog, using the validate catalog command before exporting it.
Save the catalog backup to your home directory.
GDSCTL> export catalog /home/user/cat-201307.backup
The gdsctl import catalog command is used to restore catalog configuration from the file, created using export catalog command. When restoring to a new catalog database, catalog must be created first, using create catalog command.
Use gdsctl import catalog command with the following syntax:
import catalog file_name
Table A-28 gdsctl export catalog Options
| Syntax | Description |
|---|---|
file_name
|
Name of a file on the same computer where the command is being executed. The configuration will be restored from this file. If the file is not readable, you will get an error. |
You must connect to the catalog database as a user with GDS Administrator privileges before running this command.
The import procedure can be considered finished only when there are no pending requests after import. Use the config command to get the list of pending requests.
Load the catalog backup from your home directory.
GDSCTL> import catalog /home/user/cat-201307.backup
The gdsctl modify command changes the configuration parameters for components in the global service manager configuration.
Table A-29 gdsctl modify Summary
| Command | Description |
|---|---|
|
Modifies the catalog attributes. |
|
|
Modifies the configuration parameters of the databases |
|
|
Add or remove a user from the list of database pool administrators |
|
|
Modifies the configuration options for a global service manager |
|
|
Modifies the regions currently defined for the global service management framework |
|
|
Modifies the preferred or available databases for a service, or other service attributes |
The gdsctl modify catalog command modifies the properties of the global service manager catalog. To use this command, there must be a least one global service manager running and a connection with the catalog database must have already been established (see the connect command).
Use the gdsctl modify catalog command with the following syntax:
modify catalog [-autovncr {ON | OFF}] [-oldpwd oldpassword -newpwd newpassword] [-pwd password -newkeys]
To update the GSMCATUSER password after changing it on the catalog database use
modify catalog -oldpwd ** -newpwd ***
If you decide to replace the PKI keys, or just after the patchset upgrade from Oracle Database 12c Release 1 (12.1) on the catalog database, run this command:
modify catalog -pwd ** -newkeys
Table A-30 gdsctl modify catalog Options
| Syntax | Description |
|---|---|
-autovncr {ON | OFF}
|
This option enables ( |
-newkeys |
Generates a new PKI key pair. |
-newpwd newpassword
|
Used along with |
-oldpwd oldpassword
|
Used along with |
-pwd password
|
Provides the |
You must connect to the catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command.
Auto VNCR is best used in environments with simple private networks where ease of configuration is the most important consideration. To have the highest level of control over which hosts may participate in a GDS configuration, disable Auto VNCR and explicitly add the IP address(es) of each database host to the VNCR configuration.
The GSMCATUSER password should be updated regularly for security reasons. Use modify catalog -oldpwd oldpassword -newpwd newpassword to perform this operation. This command fetches the encrypted private key and enc string, decrypts them using the old password, re-encrypts them with the new password and stores them again.
The PKI keys must be updated regularly, which is done using modify catalog -oldpwd oldpassword -newkeys. This command generates a new PKI key pair and replaces the corresponding fields in the database.
Turn off autovncr mode for the catalog database.
connect gsmadmin@mycloud GDSCTL> modify catalog -autovcnr off
Modifies the configuration parameters of the databases in a GDS pool, such as region, connect identifier, global service manager password, SCAN address, and ONS port. For all parameters except for the GDS region, first the appropriate changes must be done by the database administrator and then the modify database command must be run to update the modified parameters in the GDS catalog. Alternatively, you can use the sync database command for this purpose.
Use the gdsctl modify database command with the following syntax:
modify database -database dbname_list [-region region_name] [-gdspool gdspool_name] [-connect connect_identifier] [-pwd password] [-scan scan_address [-ons port]] [-savename] [-cpu_threshold cpu] [-disk_threshold disk]
Table A-31 gdsctl modify database Options
| Option | Description |
|---|---|
-connect connect_identifier
|
Specify an Oracle Net connect descriptor or a net service name that maps to a connect descriptor for the database that is being modified. |
-cpu_threshold cpu
|
Specifies CPU Utilization percentage threshold. |
-database dbname_list
|
Specify a comma-delimited list of database names. |
-disk_threshold disk
|
Specifies the average latency in milliseconds of a synchronous single-block read. |
-gdspool gdspool_name
|
Specify the database pool to which the databases belong. |
-ons port
|
Specify the ONS port. |
-pwd password
|
Specify the password for the GSMUSER. |
-region region_name
|
Specify the region to which the databases belong. |
-savename |
Specify this option to store a net service name specified with the |
-scan scan_address
|
Specify the SCAN address for a cluster. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command
Change the region of databases DB1 and DB3 to EAST.
GDSCTL> modify database -database db1,db3 -region east
Adds and removes users from the list of pool administrators for one or more database pools.
Use the gdsctl modify gdspool command with the following syntax:
modify gdspool -gdspool database_pool_list {-removeuser user_name | -adduser user_name}
Table A-32 gdsctl modify gdspool Options
| Option | Description |
|---|---|
-adduser user_name
|
Specify the user to add to the list of database pool administrators. This option grants the pool administrator role to the specified user. |
-gdspool database_pool_list
|
Specify a comma-delimited list of database pool names. |
-removeuser user_name
|
Specify the user to remove from the list of database pool administrators. This option revokes the pool administrator role from the specified user. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command
Add PETER to the list of database pool administrators for the pool MYREADERFARM:
GDSCTL> modify gdspool -gdspool myreaderfarm -adduser peter
Modifies the configuration parameters of the global service manager. The changes take effect after the global service manager is restarted.
Use the gdsctl modify gsm command with the following syntax:
modify gsm -gsm gsm_name [-catalog connect_id [-pwd password]] [-region region_name] [-localons ons_port] [-remoteons ons_port] [-endpoint gmsendpoint [-remote_endpoint remote_endpoint]] [-listener listener_port] [-wpwd wallet_password]
Table A-33 gdsctl modify gsm Options
| Option | Description |
|---|---|
-catalog connect_id
|
Specify the connect identifier for the Global Data Services catalog database. If a network service name is specified, it must be resolvable by the local naming method to a connect descriptor that allows the global service manager being modified to connect to the catalog database. |
-endpoint gsmendpoint
|
Specify the protocol address that the global services manager listens on for client connection requests. If you use this option, the value you specify overrides the default endpoint. |
-gsm gsm_name
|
Enter the name of the global service manager that you want to modify. If you do not specify a name, then the current global service manager name for the session (specified with the |
-listener listener_port
|
Specify the new listener port. |
-localons ons_port
|
Specify the new local ONS port. |
-pwd password
|
Specify the password for the |
-region region_name
|
Specify the region to which the global service manager belongs. |
-remote_endpoint remote_endpoint
|
Specify the protocol address that is used by the global service manager to receive database registration requests and communicate with other global service managers in the configuration. If you use this option, the value you specify overrides the default endpoint. |
-remoteons ons_port
|
Specify the new remote ONS port. |
-wpwd |
Specify the password for the global service manager wallet. |
You must run this command locally on the computer where you want to modify the global service manager.
This command can be run only by the operating system user who started the global service manager.
When you run this command, GDSCTL connects to the Global Data Services catalog as the GSMCATUSER user and prompts you for the GSMCATUSER password.
Modify the global service manager named gsm1 so that it is in the EAST region.
GDSCTL> modify gsm -gsm gsm1 -region east
This command modifies the configuration for a region.
Use the gdsctl modify region command with the following syntax:
modify region -region region_list -buddy region_name [-weights weight]
Table A-34 gdsctl modify region Options
| Option | Description |
|---|---|
-buddy region_name
|
Specify the name of the buddy region |
-region region_list
|
Specify a comma-delimited list of region names |
-weights weight
|
Used for static RLB distribution. format: name = value,..,name = value |
You must connect to the catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command.
Modify two regions, EAST and WEST, as follows:
GDSCTL> modify region -region west -buddy east
Modifies the service attributes. Use this command to:
Add databases to the preferred or available lists for the service
Move a service from one database to another database
Change an available database to a preferred database or a preferred database to an available database
Modify the high availability attributes of the service
If you want to temporarily move a service from one database to a different database, then use the relocate service command.
Use the gdsctl modify service command to manage services.
To add more preferred or available databases to a service:
modify service [-gdspool gdspool_name] -service service_name {-preferred dbname_list | -available dbname_list}
To modify the high availability attributes of a service:
modify service [-gdspool gdspool_name] -service service_name [-database db_name] [-server_pool server_pool_name] [-cardinality {UNIFORM | }] [-locality {ANYWHERE | LOCAL_ONLY [-region_failover]}] [-role {PRIMARY | PHYSICAL_STANDBY [-failover_primary] | LOGICAL_STANDBY | SNAPSHOT_STANDBY}] [-lag {lag_value | ANY}] [-notification {TRUE | FALSE}] [-rlbgoal {SERVICE_TIME | THROUGHPUT}] [-dtp {TRUE | FALSE}] [-sql_translation_profile stp_name] [-clbgoal {SHORT | LONG}] [-tafpolicy {BASIC | NONE | PRECONNECT}] [-policy policy] [-failovertype {NONE | SESSION | SELECT}] [-failovermethod {NONE | BASIC}] [-failoverretry failover_retries] [-failoverdelay failover_delay] [-edition edition_name] [-commit_outcome {TRUE | FALSE}] [-retention retention_seconds] [-session_state {DYNAMIC | STATIC}] [-replay_init_time replay_init_time]]
To change an available database to a preferred databases for a service:
modify service [-gdspool gdspool_name] -service service_name -available dbname_list -preferred
To change preferred and available status of a database for a service:
modify service [-gdspool gdspool_name] -service service_name {-preferred_all | -modifyconfig -preferred dbname_list [-available dbname_list]} [-force]
To modify properties for a global service that are specific to an Oracle RAC database:
modify service [-gdspool gdspool_name] -service service_name -database db_name {[-server_pool server_pool_name] [-cardinality {UNIFORM | }] | { -add_instances [-preferred comma-delimited-list] [-available comma-delimited-list] | -drop_instances instlist | -modify_instances [-preferred comma-delimited-list] [-available comma-delimited-list] } }
Table A-35 gdsctl modify service Options
| Option | Description |
|---|---|
-add_instances [-preferred comma-delimited-list] [-available comma-delimited-list] |
Provides a list of preferred and available instances for the given service on the given database. The provided list over-rides existing assigned instances, if any. Using the –preferred and –available options is optional, but at least one of these must be provided. |
-available dbname_list
|
Specify a comma-delimited list of available databases on which the service runs, if the preferred databases are not available. The list of available instances must be mutually exclusive with the list of preferred instances. If you attempt to add a preferred or available database to a service that was configured with |
-cardinality {UNIFORM | }
|
Specify the cardinality option for a service running on a policy-managed Oracle RAC database. Services with cardinality set to |
-clbgoal {SHORT | LONG}
|
For connection load balancing goal: set to The default value for this option is |
-commit_outcome {TRUE | FALSE}
|
Enable Transaction Guard; when set to |
-database db_name
|
Specify the name of the database on which you want to modify the service. When
|
-dtp {TRUE | FALSE}
|
Indicates whether Distributed Transaction Processing should be enabled for this service. This ensures that the service is offered at exactly one instance at a time for XA affinity. |
-drop_instances inst_list
|
Provide a list of instances to be removed from the existing assigned instances for a given service on a given database. The provided list of instances will be removed from the existing assigned list. |
-edition edition_name
|
Specify the initial session edition of the service. When an edition is specified for a service, all subsequent connections that specify the service use this edition as the initial session edition. However, if a session connection specifies a different edition, then the edition specified in the session connection is used for the initial session edition. GDSCTL does not validate the specified edition name. During connection, the connect user must have |
-failover_primary |
If you set the |
-failoverdelay failover_delay
|
For Application Continuity and TAF, the time delay (in seconds) between reconnect attempts for each incident at failover. |
-failovermethod {NONE | BASIC}
|
TAF failover method (for backward compatibility only). If |
-failoverretry failover_retries
|
For Application Continuity and TAF, the number of attempts to connect after an incident. |
-failovertype {NONE | SESSION | SELECT | TRANSACTION}
|
Specify the failover type. To enable Application Continuity for Java, set this parameter to |
-force |
If you use this option, then all sessions are disconnected when the service is moved, requiring the sessions using the service to reconnect (potentially to a different instance). If you do not use this option, then the sessions that are connected to a database using this service stay connected, but all new sessions cannot be established to the service. |
-gdspool gdspool_name
|
Specify the name of the database pool to which the service belongs. If not specified and there is only one |
-lag {lag_value | ANY}
|
Specify the lag for the service in seconds. You can use the keyword The default value for the |
-locality {ANYWHERE | LOCAL_ONLY}
|
The service region locality. If you do not use this option, then the default value of |
-modifyconfig |
Use this option to indicate that you are changing the current list of preferred and available databases for the service. If you use this option, then any databases that are not specified in either the preferred or available list, but were previously assigned, are removed from the list of databases on which the service can run. |
-modify_instances [-preferred comma-delimited-list] [-available comma-delimited-list] |
The provided If you specify an instance in the If you specify in Any instances already in the stored list that are not in the provided list remain unchanged in the stored list. Note that an instance cannot be both preferred and available, it can be in one mode only.
|
-new_db database_name
|
Specify the name of the new database on which the service runs. If you attempt to move a service that was configured with |
-notification {TRUE | FALSE}
|
Enable Fast Application Notification (FAN) for OCI connections. |
-old_db database_name
|
Specify the name of the old database on which the service runs. If you attempt to move a service that was configured with |
-policy {AUTOMATIC | MANUAL}
|
Specify the management policy for the service. If you specify If you specify |
-pdbname pdb_name
|
Specify the pluggable database name. |
-preferred dbname_list
|
Specify a comma-delimited list of preferred databases on which the service runs. When changing a database from available to preferred, you do not specify a value for the The list of preferred instances must be mutually exclusive with the list of available instances. If you attempt to add a preferred or available database to a service that was configured with |
-preferred_all |
Specifies that all the databases in the database pool are preferred databases. Any new databases added to the pool are configured as preferred databases for this service. This option cannot be used with the |
-region_failover |
Indicates that the service is enabled for region failover. You can only use this option when you specify |
-replay_init_time replay_init_time
|
For Application Continuity, this parameter specifies the time (in seconds) after which replay is not initiated. Default value is 300 seconds. |
-retention retention_seconds
|
For Transaction Guard ( |
-rlbgoal {SERVICE_TIME | THROUGHPUT}
|
Run-time Load Balancing Goal. Set this parameter to If you do not use this option, then the value defaults to |
-role {[PRIMARY] | [PHYSICAL_STANDBY]
[-failover_primary] |
[LOGICAL_STANDBY] |
[SNAPSHOT_STANDBY]}
|
Specify the database role that the database must be for this service to start on that database. This applies only to database pools that contain an Oracle Data Guard broker configuration. See Also: Oracle Data Guard Concepts and Administration for more information about database roles |
-server_pool server_pool_name
|
Specify the name of the Oracle RAC server pool in the GDS pool database to which the service belongs (for a policy-managed Oracle RAC database). |
-service service_name
|
Specify the name of the global service. |
-session_state
{DYNAMIC | STATIC}
|
For Application Continuity, this parameter specifies whether the session state that is not transactional is changed by the application. A value of |
-sql_translation_profile stp_name
|
Use this option to specify a SQL translation profile for a service that you are adding after you have migrated applications from a non-Oracle database to an Oracle database. This option corresponds to the SQL translation profile parameter in the Notes:
See Also: Oracle Database Migration Guide for more information about SQL translation |
-tafpolicy {BASIC | NONE }
|
TAF policy specification (for administrator-managed databases only). |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command.
Add the database DB3 as a preferred database for the service G_SALES_REPORT in the database pool MYREADERFARM.
GDSCTL> modify service -gdspool myreaderfarm -service g_sales_report -preferred db3
Modify the service G_DAILY_SALES_REPT in the database pool MYREADERFARM to change the run-time load balancing goal to THROUGHPUT.
GDSCTL> modify service -gdspool myreaderfarm -service g_daily_sales_rept -rlbgoal THROUGHPUT
Move the service G_SALES_REPORT in the database pool MYREADERFARM from the database DB1 to DB4.
GDSCTL> modify service -gdspool myreaderfarm -service g_sales_report -old_db db1 -new_db db4
Upgrade the DB3 database from an available database to a preferred database for the service G_SALES_REPORT in the database pool READFARM.
GDSCTL> modify service -gdspool readfarm -service g_sales_report -available db3 -preferred
Assume the service G_SALES_REPORT currently has the databases DB1 and DB2 assigned as preferred databases, and the database DB3 assigned as an available database. Exchange the preferred and available databases DB1 and DB3, and remove the DB2 database for the service SALES_REPORT in the database pool READFARM.
GDSCTL> modify service -gdspool readfarm -service g_sales_report -modifyconfig -available db3 -preferred db1
Modify the properties of the service G_SALES_REPORT in the database pool READFARM to specify that it should run only in the server pool named SALESPOOL for the policy-managed Oracle RAC database DB1.
GDSCTL> modify service -gdspool readfarm -service g_sales_report -database db1 -server_pool salespool
Supply the preferred and available instances for the given service on the given database.
GDSCTL> modify service –gdspool mypool –service mysvc –database mydb –add_instances –preferred inst1,inst2 –available inst3,inst4
See Also:
"Modifying Global Service Attributes"The gdsctl relocate service command stops a service on one database and starts the service on a different database. Unlike using the modify service command to change the location of a service, this command does not change the underlying configuration. This command temporarily relocates a service to run on another database.
Note:
If you attempt to use this command on a service that was previously configured with the-preferred_all option, then GDSCTL returns an error.Use the gdsctl relocate service command with the following syntax:
relocate service [-gdspool gdspool_name] -service service_name -old_db db_name -new_db db_name [-force] [-override [-sourcepwd password] [-targetpdw password]]
Table A-36 gdsctl relocate service Options
| Option | Description |
|---|---|
-force |
If you use this option, then all sessions are disconnected when the service is moved, requiring the sessions using the service to reconnect (potentially to a different instance). If you do not use this option, then the sessions that are connected to a database using this service stay connected, but new sessions cannot be established to the service. |
-gdspool gdspool_name
|
Specify the name of the database pool where the service is located. If not specified and there is only one |
-new_db db_name
|
Specify the name of the database to which you want to move the service. |
-old_db db_name
|
Specify the name of the database where the service is currently located. |
-override |
This option causes the command to execute without updating the global service manager catalog. You can use this option when the catalog database is unavailable. During normal operation, you should not use this option. |
-service service_name
|
Specify the name of the service you are relocating. |
-sourcepwd password
|
Specify the password for the GSMUSER in the source database, or the database where the service is currently located. |
-targetpwd password
|
Specify the password for the GSMUSER in the database to which the service is being relocated (the target database). |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command
Relocate the service SALES_REPORT in the READFARM database pool from the DB2 database to the DB3 database.
GDSCTL> relocate service -gdspool readfarm -service sales_report -old_db db1 -new_db db3
The gdsctl remove command removes components from the global service management configuration.
Table A-37 gdsctl remove Summary
| Command | Description |
|---|---|
|
Removes the Oracle Data Guard broker configuration from a database pool |
|
|
Removes a database from a Global Data Services pool |
|
|
Removes a database pool |
|
|
Removes a global service manager from the configuration |
|
|
Removes VNCR information from the catalog database |
|
|
Removes a region from the current configuration |
|
|
Removes a service from a database pool |
Removes an Oracle Data Guard broker configuration from a GDS pool.
Use the gdsctl remove brokerconfig command with the following syntax:
remove brokerconfig [-gdspool gdspool_name]
Table A-38 gdsctl remove brokerconfig Options
| Syntax | Description |
|---|---|
-gdspool gdspool_name
|
Specify the GDS pool from which you want to remove the Oracle Data Guard broker configuration (not required--if not specified and there is only one GDS pool with access granted to the user, it is used by default). |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command.
If a GDS pool does not contain a Data Guard Broker configuration, an error is returned.
Remove the Oracle Data Guard broker configuration from the database pool MYDGPOOL.
GDSCTL> remove brokerconfig -gdspool myreaderfarm
Removes databases from a database pool.
Use the gdsctl remove database command with the following syntax:
remove database {-gdspool gdspool_name -all | [-gdspool gdspool_name]
-database db_name_list } [-force]
Table A-39 gdsctl remove database Options
| Option | Description |
|---|---|
-all |
Removes all databases in the database pool. |
-database dbname_list
|
Specify a comma-delimited list of database names that you want to remove from the database pool. You cannot specify a database that was added through an Oracle Data Guard broker configuration; you must use Oracle Data Guard to remove these databases. |
-force |
Removes the database from the catalog even if the database is not available. Using this option can result in global services not being removed from the database. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command.
Remove the database DB1 from the global service management configuration.
GDSCTL> remove database -database db1
Removes a database pool from the current configuration.
Use the gdsctl remove gdspool command with the following syntax:
remove gdspool -gdspool database_pool_list
Table A-40 gdsctl remove gdspool Options
| Option | Description |
|---|---|
-gdspool database_pool_list
|
Specify a comma-delimited list of database pool names. |
You must connect to the catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command.
Remove the database pools tempreaders and myfarm from the Global Data Services framework.
GDSCTL> remove gdspool -gdspool tempreaders,myfarm
Removes a global service manager from the configuration.
Note:
The removal of a global service manager requires at least one global service manager to be running to perform cleanup of Global Data Services databases. If there is only one global service manager in the Global Data Services configuration, then it has to be running to be removed.Use the gdsctl remove gsm command with the following syntax:
remove gsm [-gsm gsm_name]
Table A-41 gdsctl remove gsm Options
| Syntax | Description |
|---|---|
-gsm gsm_name
|
Specify the name of the global service manager that you want to remove. If the name is not specified, then the current global service manager is removed. |
You must connect to the catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command.
Remove the global service manager named gsm5 from the configuration.
GDSCTL> remove gsm -gsm gsm5
Remove host address information from the valid node checking for registration (VNCR) list in the Global Data Services catalog. This command removes either the specified invitednode or all invitednodes that correspond to an alias.
Use the gdsctl remove invitednode command with the following syntax:
remove invitednode {[-group group_name]|vncr_id}
Table A-42 gdsctl remove invitednode Options
| Option | Description |
|---|---|
-group group_name
|
Specify an alias which defines a group of VNCRs. This alias can be referenced in other commands related to invited nodes. |
vncr_id
|
The host address information, which can be an IPv4 or IPv6 address, a host name, a netmask, or other identifier for a server. The host address information cannot contain any spaces. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command
Remove the invitednode 194.66.82.32 from the catalog.
GDSCTL> remove invitednode 194.66.82.32
Remove the VNCR alias group EAST_SRV from the catalog.
GDSCTL> remove invitednode -group east_srv
Removes the specified regions from the global service management framework.
Use the gdsctl remove region command with the following syntax:
remove region -region region_list
Table A-43 gdsctl remove region Options
| Option | Description |
|---|---|
-region region_list
|
Specify a comma-delimited list of region names |
You must connect to the catalog database as a user with the Global Data Services administrator privileges, using the connect command before running this command.
Remove the region named SOUTH from the configuration.
GDSCTL> remove region -region south
Removes a service from a database pool.
Use the gdsctl remove service command with the following syntax:
remove service [-gdspool gdspool_name] -service service_name [-force]
Table A-44 gdsctl remove service Options
| Option | Description |
|---|---|
-force |
Indicates this action should be performed even if one or more databases in the database pool are not available. |
-gdspool gdspool_name
|
Specify the name of the database pool from which you want to remove the service. If not specified and there is only one |
-service service_name
|
Specify the name of the service that you want to remove. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command
Remove the service sales_report from the database pool MYREADERFARM.
GDSCTL> remove service -gdspool myreaderfarm -service sales_report
See Also:
"Deleting a Global Service"The gdsctl services command retrieves the information about the services that are registered with the specified global service manager.
Use the gdsctl services command with the following syntax:
services [-gsm gsm_name] [-service service_name]
| Option | Description |
|---|---|
-gsm gsm_name
|
Specify the name of a global service manager. If the name is not specified, then GDSCTL uses the current global service manager name for the session (specified with the GDSCTL |
|
|
Specify a fully qualified service name. If the service name is not specified, then the information about all the services registered with the global service manager is retrieved. |
You must run this command on the host where the global service manager for which you want to retrieve service information resides
You must have the privileges of the user who started the global service manager to run this command
Display information about the services registered with global service manager mygsm:
GDSCTL> services -gsm mygsm
The gdsctl services command returns output similar to the following:
GDSCTL>services -gsm mygsm Service "localsvc.dbpoolora.oradbcloud" has 2 instance(s). Affinity: LOCALPREF Instance "dbpoolora%1", name: "gdscat", db: "gdscat", region: "regionora", status: ready. Instance "dbpoolora%11", name: "gdscat2", db: "gdscat2", region: "regionora", status: ready. Service "sales_report1.dbpoolora.oradbcloud" has 2 instance(s). Affinity: LOCALONLY Instance "dbpoolora%1", name: "gdscat", db: "gdscat", region: "regionora", status: ready. Instance "dbpoolora%11", name: "gdscat2", db: "gdscat2", region: "regionora", status: ready. Service "sales_report2.dbpoolora.oradbcloud" has 2 instance(s). Affinity: ANYWHERE Instance "dbpoolora%1", name: "gdscat", db: "gdscat", region: "regionora", status: ready. Instance "dbpoolora%11", name: "gdscat2", db: "gdscat2", region: "regionora", status: ready.
Note:
Affinity values can beLOCALONLY when the service locality is defined as local_only, LOCALPREF when the service locality is defined as local_only with the region_failover option enabled, and ANYWHERE when the service locality is defined as anywhere.Display the status of mthly_report service:
GDSCTL>services -service mthly_report.sales.oradbcloud
Returns output similar to the following:
Service "mthly_report.sales.oradbcloud" has 1 instance(s). Affinity:
ANYWHERE
Instance "sales%1", name: "debug", db: "debug", region: "eastcoast",
status: ready.
The gdsctl set command is used to configure the context of the current GDSCTL session.
| Command | Description |
|---|---|
|
Sets the name of the global service manager for the current session. |
|
|
Sets the |
|
|
Sets the |
|
|
Sets the |
|
|
Sets the |
Sets the global service manager for the current session. This command establishes to which global service manager the successive commands apply. The specified global service manager name is resolved in the gsm.ora configuration file.
Use the gdsctl set gsm command with the following syntax:
set gsm -gsm gsm_name
Table A-47 gdsctl set gsm Options
| Syntax | Description |
|---|---|
-gsm gsm_name
|
Specify the name of the global service manager to work with in the current session. If you do not specify a specific global service manager, then GDSCTL uses the default global service manager name of |
You must run this command on the host where the global service manager that you want to set for the current session resides.
You must have the privileges of the user who started the global service manager to run this command.
Set the global service manager for the current session to gsm1.
GDSCTL> set gsm -gsm gsm1
Sets the INBOUND_CONNECT_LEVEL listener parameter.
Use the gdsctl set inbound_connect_level command with the following syntax:
set inbound_connect_level [-gsm gsm_name] timeout_value
Table A-48 gdsctl set inbound_connect_level Options
| Option | Description |
|---|---|
-gsm gsm_name
|
Specify the name of the global service manager that you want to start. If you do not specify a specific global service manager, then GDSCTL uses the current global service manager name for the session (specified with the |
timeout_value
|
Specify in seconds the connection timeout value. |
You must run this command on the host where the global service manager for which you want to set the INBOUND_CONNECT_LEVEL listener parameter resides
You must have the privileges of the user who started the global service manager to run this command
Set the INBOUND_CONNECT_LEVEL listener parameter for mygsm to time out in 60 seconds:
GDSCLTL> set inbound_connect_level -gsm mygsm 60
Sets the log level for the listener associated with a specific global service manager.
Use the gdsctl set log_level command with the following syntax:
set log_level [-gsm gsm_name] log_level
Table A-49 gdsctl set log_level Options
| Option | Description |
|---|---|
-gsm gsm_name
|
Specify the name of the global service manager. |
log_level
|
Specify the level of detail to write to the log. Valid values are ON or OFF. |
You must run this command on the host where the global service manager for which you want to set the listener log level resides
You must have the privileges of the user who started the global service manager to run this command
Set logging on for global service manager mygsm:
GDSCTL> set log_level -gsm mygsm ON
Sets the timeout value for the outbound connections for the listener associated with a specific global service manager.
Use the gdsctl set outbound_connect_level command with the following syntax:
set outbound_connect_level [-gsm gsm_name] timeout_value
Table A-50 gdsctl set outbound_connect_level Options
| Option | Description |
|---|---|
-gsm gsm_name
|
Specify the name of the global service manager |
timeout_value
|
Specify the connection timeout value |
You must run this command on the host where the global service manager for which you want to set the timeout value of outbound connections for the listener resides.
You must have the privileges of the user who started the global service manager to run this command.
Set timeout value for all outbound connections:
GDSCTL> set outbound_connect_level 60
Sets the trace level for the listener associated with the specified global service manager.
Use the gdsctl set trace_level command with the following syntax:
set trace_level [-gsm gsm_name] trace_level
Table A-51 gdsctl set trace_level Options
| Option | Description |
|---|---|
-gsm gsm_name
|
Specify the name of the global service manager. If the name is not specified, then GDSCTL uses the current global service manager name for the session (specified with the GDSCTL |
trace_level
|
Specify the trace level for the global service manager listener. Valid values are USER - provides traces to identify user-induced error conditions ADMIN - provides traces to identify installation-specific problems SUPPORT - provides trace with troubleshooting information for Oracle Support Services OFF - provides no tracing |
You must run this command on the host where the global service manager for which you want to set the listener trace level resides.
You must have the privileges of the user who started the global service manager to run this command.
Set the trace level for all listeners associated with mygsm to ADMIN
GDSCTL> set trace_level -gsm mygsm ADMIN
The gdsctl start command starts components that are part of the global service management framework.
Table A-52 gdsctl start Summary
| Command | Description |
|---|---|
|
Starts the global service manager |
|
|
Starts the specified services |
Starts a specific global service manager.
Use the gdsctl start gsm command with the following syntax:
start gsm [-gsm gsm_name]
Table A-53 gdsctl start gsm Options
| Option | Description |
|---|---|
-gsm gsm_name
|
Specify the name of the global service manager that you want to start. If you do not specify a specific global service manager, then GDSCTL uses the current global service manager name for the session (specified with the |
You must run GDSCTL on the same host where the global service manager you want to start is located.
You must have operating system privileges on the computer where you want to start the global service manager to run this command.
Start the global service manager gsm1 on the local host.
GDSCTL> start gsm -gsm gsm1
Starts specific services.
Use the gdsctl start service command with the following syntax:
start service [-gdspool gdspool_name] -service service_name [{-database db_name | -override [-pwd password] -connect connect_identifier}]
Table A-54 gdsctl start service Options
| Option | Description |
|---|---|
-database db_name
|
Specify the name of the database on which you want to start the service. If you do not specify this option, then GDSCTL starts the services on all preferred databases. |
-connect connect_identifier
|
Specify an Oracle Net connect descriptor or net service name that resolves to a connect descriptor. |
-gdspool gdspool_name
|
Specify the name of the database pool in which the services that you want to start are located. If not specified and there is only one |
-override |
This option causes the command to run without updating the global service manager catalog. You can use this option when the catalog database is unavailable. During normal operation, you should not use this option. |
-pwd password
|
Specify the password of the GSMUSER in the specified database. |
-service service_name
|
Specify a comma-delimited list of global service names. If you do not use this option, then GDSCTL starts all the services in the database pool. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command.
Start the service SALES_REPORT, located in the READERFARM database pool.
GDSCTL> start service -gdspool readerfarm -service sales_report
See Also:
"Starting a Global Service"The gdsctl status command displays the running status of a specific component or set of components. For example, you can use the gdsctl status command to check whether a component is started.
Table A-55 gdsctl status Summary
| Command | Description |
|---|---|
|
Displays the status of a specific database |
|
|
Displays the status of a specific global service manager |
|
|
Displays the status of one or more services in a specific database pool |
Displays the status of all databases.
Use the gdsctl status database command with the following syntax:
{status database | databases} [-gsm gsm_name][-database db_name]
[-gdspool gdspool_name]
Table A-56 gdsctl status database Options
| Option | Description |
|---|---|
-database db_name
|
Specify the name of the database on which you want to start the service. If you do not specify this option, then GDSCTL starts the services on all preferred databases. |
-gdspool gdspool_name
|
Specify the name of the database pool in which the services you want to start are located. If not specified and there is only one |
-gsm gsm_name
|
Specify the name of a global service manager to check. If the name is not specified, then GDSCTL uses the current global service manager name for the session (specified with the GDSCTL |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command.
Display the status of all databases:
GDSCTL>status database
The gdsctl status database command returns output similar to the following:
Database: "dbcat1" Registered: Y State: Ok ONS: N. Role: PRIMARY Instances: 1
Region: east
Service: "sales_svc2" Globally started: N Started: N
Scan: Y Enabled: Y Preferred: Y
Service: "sales_svc1" Globally started: Y Started: Y
Scan: N Enabled: Y Preferred: Y
Registered instances:
sales%11
Database: "dbcat2" Registered: Y State: Ok ONS: N. Role: PRIMARY Instances: 1
Region: east
Service: "sales_svc2" Globally started: N Started: N
Scan: Y Enabled: Y Preferred: Y
Service: "sales_svc1" Globally started: Y Started: Y
Scan: N Enabled: Y Preferred: Y
Registered instances:
sales%1
Displays the status of a specific global service manager.
Use the gdsctl status gsm command with the following syntax:
status gsm [-gsm gsm_name]
Table A-57 gdsctl status gsm Options
| Option | Description |
|---|---|
-gsm gsm_name
|
Specify the name of a global service manager to check. If the name is not specified, then GDSCTL uses the current global service manager name for the session (specified with the GDSCTL |
You must run GDSCTL on the same host where the global service manager for which you want to display the status is located.
You must have operating system privileges on the computer where you want to display the global service manager status to run this command.
Display status of mygsm:
GDSCTL> status gsm -gsm mygsm
The gdsctl status gsm command returns output similar to the following:
Alias MYGSM Version 12.1.0.0.2 Start Date 03-JUL-2012 16:48:54 Trace Level support Listener Log File /u01/ORACLE/mygsm/alert/log.xml Listener Trace File /u01/ORACLE/mygsm/trace/ora_14816_47568108067776.trc Endpoint summary (ADDRESS=(HOST=mymv.us.hq.com)(PORT=1523)(PROTOCOL=tcp)) GSMOCI Version 0.1.8 Mastership Y Connected to GDS catalog Y Process Id 14818 Number of reconnections 0 Pending tasks. Total 0 Tasks in process. Total 0 Regional Mastership TRUE Total messages published 28599 Time Zone -07:00 Orphaned Buddy Regions: None GDS region regionora
Displays the status of a specific service. This command is similar to services.
Use the gdsctl status service command with the following syntax:
{status service | services} [-gsm gsm_name] [-service service_name] [{-raw|-verbose|-support}]
Table A-58 gdsctl status service Options
| Option | Description |
|---|---|
-gsm gsm_name
|
Specify the name of a global service manager. If the name is not specified, then GDSCTL uses the current global service manager name for the session (specified with the GDSCTL |
-raw |
Used by oracle internal components. |
-service service_name
|
Specify a comma-delimited list of global service names. If you do not specify any services, then GDSCTL displays the status of all services in the database pool. |
-support |
Display more detailed information concerning load balancing. |
-verbose |
Display extra information related to load balancing. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command.
Display the status of service sales_report1.sales.oradbcloud:
GDSCTL>status service -service sales_report1.sales.oradbcloud
The gdsctl status service command returns output similar to the following:
Service "sales_report1.sales.oradbcloud" has 3 instance(s). Affinity: ANYWHERE Instance "sales%1", name: "dbcat2", db: "dbcat2", region: "east", status: ready. Instance "sales%11", name: "dbcat1", db: "dbcat1", region: "west", status: ready. Instance "sales%31", name: "dbcat3", db: "dbcat3", region: "east", status: ready.
The gdsctl stop command stops components that are part of the Global Service Management framework.
Table A-59 gdsctl stop Summary
| Command | Description |
|---|---|
|
Stops a specific global service manager on the local host |
|
|
Stops a specific service |
Stops a specific global service manager. You must run GDSCTL on the same host where the global service manager that you want to stop is located.
Use the gdsctl stop gsm command with the following syntax:
stop gsm [-gsm gsm_name]
Table A-60 gdsctl stop gsm Options
| Option | Description |
|---|---|
-gsm gsm_name
|
Specify the name of a global service manager you want to stop. If you do not specify a specific global service manager, then GDSCTL uses the current global service manager name for the session (specified with the |
You must run GDSCTL on the same host where the global service manager that you want to stop is located.
You must have operating system privileges on the computer where you want to start the global service manager to run this command.
Stop the global service manager gsm1 on the local host.
GDSCTL> stop gsm -gsm gsm1
Stops a specific service.
Use the gdsctl stop service command with the following syntax:
stop service [-gdspool gdspool_name] [-service service_name] [{-database db_name | -override [-pwd password] -connect connect_identifier}] [-force]
Table A-61 gdsctl stop service Options
| Option | Description |
|---|---|
-connect connect_identifier
|
Specify an Oracle Net connect descriptor or net service name that resolves to a connect descriptor. |
-database db_name
|
Specify the name of the database on which you want to stop the service. If you do not specify this option, then GDSCTL stops the services on all databases on which the service is currently running. |
-force |
If you use this option, then GDSCTL disconnects all sessions when the service is stopped, requiring the sessions using the service to reconnect (potentially to a different instance). If you do not use this option, then the sessions that are connected to a database using this service remain connected, but new sessions cannot be established to the service. |
-gdspool gdspool_name
|
Specify the name of the database pool in which the service that you want to stop is located. If not specified and there is only one |
-override |
This option causes the command to execute without updating the global service manager catalog. You can use this option when the catalog database is unavailable. During normal operation, you should not use this option. |
-pwd password
|
Specify the password of the GSMUSER in the specified database. |
-service service_name
|
Specify a comma-delimited list of global service names you want to stop. If you do not use this option, then GDSCTL stops all the services in the database pool. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command.
Stop the service SALES_REPORT, on all databases in the database pool READERFARM.
GDSCTL> stop service -gdspool readerfarm -service sales_report
See Also:
"Stopping a Global Service"The gdsctl sync brokerconfig command synchronizes the Oracle Data Guard broker configuration in the global service manager with the configuration in the database pool.
Use the gdsctl sync brokerconfig command with the following syntax:
sync brokerconfig [-gdspool gdspool_name] [-database db_name]
Table A-62 gdsctl sync brokerconfig Options
| Option | Description |
|---|---|
-database db_name
|
Specify the name of a database in the database pool to use as a referential database, from which the configuration is queried. If you do not use this option, then GDSCTL uses the primary database as the referential database. If a primary database does not exist in the Oracle Data Guard broker configuration, then GDSCTL uses a random database from the pool as the referential database. |
-gdspool gdspool_name
|
Specify the database pool to which the Oracle Data Guard broker configuration belongs. If not specified and there is only one If the specified database pool does not contain an Oracle Data Guard broker configuration, then GDSCTL returns an error. |
You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command.
Synchronize the Oracle Data Guard broker configuration in the database pool MYREADERFARM with the configuration stored in the Global Data Services catalog.
GDSCTL> sync brokerconfig -gdspool myreaderfarm
The gdsctl sync database command brings attributes of global services and GDS related parameters of a pool database in synchronization with the contents of the GDS catalog.
Use the gdsctl sync database command with the following syntax:
sync database [-gdspool gdspool_name] [-database database_name]
Table A-63 gdsctl sync database Options
| Option | Description |
|---|---|
-database database_name
|
Specify the name of a database in the database pool to use as a referential database, from which the configuration is queried. |
-gdspool gdspool_name
|
Specify the GDS pool to which the database belongs. If not specified and there is only one GDS pool with access granted to user, it is used as the default GDS pool. |
If database has no GDS region assigned, an error is returned.
If a GDS pool is specified and the database option is not specified, then each database in the pool is synchronized.
Synchronize a database in the default database pool with the database mydb.
GDSCTL> sync database -database mydb
The gdsctl validate catalog command cross checks the Global Data Services catalog, global service manager run-time status, and pool databases, and reports inconsistencies and errors.
Because the execution of this command involves accessing all databases in a Global Data Services configuration, the GSMCATUSER password is required run it. The password is stored in the wallet of any global service manager that is part of the Global Data Services configuration. Therefore, if you run the command from the ORACLE_HOME of any of the global service managers, the password is automatically extracted from the wallet and does not have to be provided. Otherwise, you must provide the GSMCATUSER password using the -catpwd command option. Alternatively, if all databases in the Global Data Services configuration have the same GSMUSER password, you can specify the password instead of the GSMCATUSER password by using the -dbpwd option.
Use the gdsctl validate catalog command with the following syntax:
validate [catalog] [-gsm gsm_name] [ {-config | -database db_name} ] [-catpwd cpwd] [-dbpwd dpwd]
Table A-64 gdsctl validate catalog Options
| Option | Description |
|---|---|
-catpwd cpwd
|
Provides the GDSCATUSER password, otherwise it is read from the local wallet file by default. |
|
|
Indicates that the validation should be performed on the Global Data Services catalog configuration only. |
|
|
Indicates the name of the database for which the cross-check validation should be performed. |
-dbpwd dpwd
|
Provides the pool database password directly if there is only one database in the pool, or if multiple databases in the pool share the same password. |
|
|
Specify the global service manager name. If the name is not specified, then GDSCTL uses the current global service manager name for the session (specified with the |
Validate the catalog:
GDSCTL> validate
The output should be similar to the following:
Validation results: VLD2: Region "regionora" does not have buddy region VLD11: GDS pool "marketing" does not contain any databases VLD12: GDS pool "marketing" does not contain any global services VLD11: GDS pool "sales" does not contain any databases VLD12: GDS pool "sales" does not contain any global services VLD11: GDS pool "mkt" does not contain any databases VLD12: GDS pool "mkt" does not contain any global services