modify service

Modifies the service attributes.

Syntax

To add more preferred or available databases to a global service:

modify service [-gdspool gdspool_name]
                -service service_name
               {-preferred db_name_list | -available db_name_list}

To modify the attributes of a global service:

modify service [-gdspool gdspool_name]
                -service service_name 
               [-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}]
               [-clbgoal {SHORT | LONG}] 
               [-tafpolicy {BASIC | NONE | PRECONNECT}]
               [-policy policy] 
               [-failovertype {NONE | SESSION | SELECT | TRANSACTION}]
               [-failovermethod {NONE | BASIC}] 
               [-dtp {TRUE | FALSE}] 
               [-sql_translation_profile stp_name] 
               [-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]]
               [-table_family family]

To move a global service from one database to another database:

modify service [-gdspool gdspool_name]
                -service service_name
                -old_db db_name
                -new_db db_name
               [-force]

To change an available database to a preferred database for a service:

MODIFY SERVICE [-gdspool gdspool_name]
                -service service_name
                -available db_name_list
                -preferred

To change databases between preferred and available status:

modify service [-gdspool gdspool_name]
                -service service_name
               {-preferred_all |
                {-modifyconfig -preferred db_name_list [-available db_name_list]}}

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 |
                 {-add_instances|-modify_instances} -preferred inst_list
                  -available inst_list |
                  -drop_instances inst_list
                -cardinality {UNIFORM | SINGLETON}

Options

Table 2-62 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 db_name_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 `-preferred_all,` then GDSCTL returns an error.
`-cardinality {UNIFORM \| SINGLETON}`	Specify the cardinality option for a service running on a policy-managed Oracle RAC database. Services with cardinality set to `UNIFORM` are offered on all database instances. Services with cardinality set to `SINGLETON` are offered on only one database instance.
`-clbgoal {SHORT \| LONG}`	For connection load balancing goal: set to `SHORT` if using run-time load balancing, set to `LONG` for long running connections such as batch jobs or older SQL*Forms style. The default value for this option is `SHORT`.
`-commit_outcome {TRUE \| FALSE}`	Enable Transaction Guard; when set to `TRUE`, the commit outcome for a transaction is accessible after the transaction's session fails due to a recoverable outage.
`-database db_name`	Specify the name of the database on which you want to modify the service. When `-database` is specified, you must specify exactly one of: `-server_pool` and/or `-cardinality`. Either is optional, but at least one must appear, both can be used at once. `-add_instances`, `-modify_instances`, or `-drop_instances`. Exactly one of these three options must be used.
`-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 `USE` privilege on the specified edition. If the edition does not exist or if the connect user does not have `USE` privilege on the specified edition, then an error is raised.
`-failover_primary`	If you set the `-role` option to `PHYSICAL_STANDBY`, then you can use this option to enable the service for failover to the primary database.
`-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 `failovertype` is set to either `SESSION` or `SELECT`, then choose `BASIC` for this option.
`-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 `TRANSACTION`. To enable Transparent Application Failover (TAF) for OCI, set this parameter to `SELECT` or `SESSION.`
`-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 `gdspool` with access granted to user, it is used as the default `gdspool`.
`-lag {lag_value \| ANY}`	Specify the lag for the service in seconds. You can use the keyword `ANY` to indicate that there is no upper threshold on the lag time. The default value for the `-lag` option is `ANY`.
`-locality {ANYWHERE \| LOCAL_ONLY}`	The service region locality. If you do not use this option, then the default value of `ANYWHERE` is used for the service.
`-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 `comma-delimited-list` of preferred and available instances is merged with the existing list currently stored in the catalog. If you specify an instance in the `comma-delimited-list` that is not already in the stored list, it is added to the stored list in its correct mode (preferred or available.) If you specify in `comma-delimited-list` an instance that is already in the stored list, then the mode of the instance in the stored list is modified to the provided mode (preferred or available). If the user provided mode is the same as the stored mode, then the mode of the instance will not be changed. 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. `–preferred` and `–available` are optional but at least one list must be provided.
`-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 `-preferred_all`, then GDSCTL returns an error.
`-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 `-preferred_all`, then GDSCTL returns an error.
`-policy {AUTOMATIC \| MANUAL}`	Specify the management policy for the service. If you specify `AUTOMATIC` (the default), then the service automatically starts when the database restarts, either by a planned restart or after a failure. Automatic restart is also subject to the service role. If you specify `MANUAL`, then the service is never automatically restarted upon planned restart of the database. A `MANUAL` setting does not prevent the global service manager from monitoring the service when it is running and restarting it if a failure occurs.
`-pdbname pdb_name`	Specify the pluggable database name.
`-preferred db_name_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 `-preferred` option. 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`, then GDSCTL returns an error.
`-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 `-preferred` and `-available` options.
`-region_failover`	Indicates that the service is enabled for region failover. You can only use this option when you specify `LOCAL_ONLY` for the `-locality` option.
`-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 (`commit_outcome` set to `TRUE`), this parameter determines the amount of time (in seconds) that the commit outcome is retained in the database.
`-rlbgoal {SERVICE_TIME \| THROUGHPUT}`	Run-time Load Balancing Goal. Set this parameter to `SERVICE_TIME` to balance connections by response time. Set this parameter to `THROUGHPUT` to balance connections by throughput. If you do not use this option, then the value defaults to `SERVICE_TIME` for the run-time load balancing goal.
`-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 `DYNAMIC` is recommended for most applications.
`-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 `DBMS_SERVICE` service attribute. Notes: Before using the SQL translation feature, you must migrate all server-side application objects and data to the Oracle database. Use the config service command to display the SQL translation profile. See Also: Oracle AI Database SQL Translation and Migration Guide for more information about SQL translation
`-table_familyfamily`	Specifies the table family name as a property of the service. This parameter takes one of the table family values (root table schema.name) as shown in the `CONFIG TABLE FAMILY` output. If the schema name or the table name is case-sensitive, use two-level quotes (single quotes outside, double quotes inside) around the whole string, for example, `'"TESTUSER1.Customers6"'`. No quotes are needed if neither name is case sensitive.
`-tafpolicy {BASIC \| NONE }`	TAF policy specification (for administrator-managed databases only).

Usage Notes

You must connect to the catalog database as a user with the pool administrator privileges, using the connect command before running this command.

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.

Examples

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

In a system-managed sharded database, the table family ID parameter is specified as a property of the service.

GDSCTL> modify service –GDSPOOL shdpool –table_family sales.customer -service sales