nscontrol update Command

Article
12/03/2008

Updates the instance and application databases for an existing instance of SQL Server Notification Services.

Syntax

nscontrol update 
    [-nologo]
    [-help]
        -in configFile
    [-verbose] 
    [-force] 
    [-sqlusername sqlUserName -sqlpassword sqlPassword] 
    [-argumentkey key]
    [-timeout seconds]
    [param=value ...]

Arguments

-nologo
Suppresses the product and version statement that appears when you run an nscontrol command.

-help
Displays the command syntax.

-inconfigFile
Is the path and file name of the instance configuration file (ICF) that defines the instance. If the file is in the current directory, the path is not required.

-verbose
Displays all information that has changed in the ICF and the application definition file (ADF) as it is found. This is useful for debugging or for understanding exactly what actions nscontrol update will perform.

-force
Forces nscontrol update to proceed without prompting for approval after it displays the actions that will occur.

-sqlusernamesqlUserName
Is the SQL Server login that is used to connect to SQL Server.

Important

Windows Authentication is more secure than SQL Server Authentication. Whenever possible, you should use Windows Authentication.

If you are using SQL Server Authentication to connect to SQL Server, you must specify both the -sqlusername and -sqlpassword arguments.

If you are using Windows Authentication, do not specify the -sqlusername and -sqlpassword arguments.

-sqlpasswordsqlPassword
Is the password that is associated with the -sqlusername login. You should only specify a password when connecting using SQL Server Authentication.

-argumentkeykey
Is the same key value that was specified with nscontrol register and nscontrol create. This argument is required if the EncryptArguments value in the ICF is true. The nscontrol update command deciphers the argument values to verify that the key is the same key as specified with nscontrol create. If the key value is the same, the update continues. You cannot change the key after you create the instance.

-timeout seconds
Is the time-out, in seconds, for completing each update action, such as creating or removing an index. The default time-out is 30 seconds. If any single action is likely to take longer than 30 seconds, set a longer time-out value.

param=value
Is a name/value pair that is used to pass parameter values to the configuration file from the command prompt.

If the configuration file contains replaceable parameters (such as %DBSystem%), specify the parameter name and value at the command prompt. For example, if the configuration file contains the following XML:
```
<SqlServerSystem>%DBSystem%</SqlServerSystem>
```
specify the name and value using nscontrol update as follows:
```
nscontrol create -in config.xml DBSystem=MySQLServer
```
Parameter values that you supply at the command prompt apply to parameters in the ICF, but not to parameters in the ADFs. To pass parameter values to an ADF, add a Parameters subsection to the Application section in the configuration file. You can use replaceable parameters as values within that node. You can supply values for those parameters at the command prompt.

In addition to specifying parameters at the command prompt, you also can use environment variables, such as %COMPUTERNAME%, in the ICF. If you use an environment variable in the ICF, note that a command prompt name/value pair of the same name takes precedence over the environment variable.

Remarks

The nscontrol update command compares the XML in the ICF and ADFs with the databases. For each valid change, nscontrol update updates the database as specified in the XML file.

Not all of the elements in the ICF and the ADFs can be updated. Some elements in those files specify options that cannot be changed without deleting and creating the instance again. For more information, review the Instance Configuration File Reference and the Application Definition File Reference sections. Each topic contains an Updates row that indicates whether the field can be updated.

Important

We strongly recommend that you back up the instance and application databases before you update the instance. The update operation can fail before completion. If this occurs, the instance and application databases can be left in an inconsistent state, which means that the instances and the applications may not be operable and data could be lost.

Note

Check all ADFs and the ICF before you run nscontrol update, to reduce the risk of errors. If an error does occur, fix the file and then run nscontrol update again.

If you are using Notification Services Standard Edition, and you specify options in your ADFs that are not supported by Standard Edition, nscontrol update stops without updating the instance.

If you change subscription class metadata in the ADF, nscontrol update renames the existing subscription class table, NS<*subscription_class>*Subscriptions, to NS<*subscription_class>*SubscriptionsOld to save the subscription data. If you later update the same subscription class, when nscontrol update attempts to rename the table, the rename fails if NS<*subscription_class>*SubscriptionsOld still exists. For more information, see Updating an Application.

If an event class or notification class changes in the ADF, nscontrol update deletes the existing tables for these classes.

The nscontrol update command typically displays all changes made to the ICF and the ADFs while performing the update. However, if the instance uses argument encryption, nscontrol update does not display the encrypted arguments.

Before you update an instance, make sure that any code that creates a table, a view, an index, or other SQL Server object checks for and deletes or renames any existing object with the same name. This is essential because nscontrol update does not automatically delete or rename any existing user-defined SQL Server objects that have the same name. By explicitly deleting or renaming the SQL Server object, you avoid a duplicate object error. For more information, see Defining Event Chronicle Tables.

Permissions

The account used to run nscontrol update, or the SQL Server login that you specified in the -sqlusername argument, must be a member of the db_owner database role in all instance and application databases that are affected by the nscontrol update command, or must be a member of the sysadmin fixed server role.

The account also must also have permission to execute the Notification Services binary files; this permission is granted to members of the Administrators and SQLServerNotificationServicesUser Windows groups.

Examples

The following examples illustrate how to update an instance.

A. Update an instance, viewing all differences

This example shows how to update an instance using a ICF named InstanceConfig.xml. The nscontrol update command displays all differences found in the updated configuration file and the ADFs. You are prompted to answer yes or no before the update proceeds.

The nscontrol command uses Windows Authentication to connect to SQL Server.

nscontrol update -in "C:\NS\Stock\InstanceConfig.xml" 
    -verbose

B. Updating an instance when the ICF contains parameters

This example shows how to provide values for the BaseDirectoryPath, NSHost, and SqlServer parameters when you update an instance. The nscontrol command uses Windows Authentication to connect to SQL Server.

nscontrol update -in "C:\NS\Stock\InstanceConfig.xml" 
    BaseDirectoryPath=C:\NS\Samples\Stock NSHost=nsuetest 
    SqlServer=nsuetest

C. Updating an instance when using argument encryption

This example shows how update an instance when you use argument encryption. The nscontrol command uses Windows Authentication to connect to SQL Server.

nscontrol update -in "C:\NS\Stock\InstanceConfig.xml" 
    -argumentkey "MyArgumentKey"

D. Forcing an update without prompt

This example shows how update an instance without being prompted to approve the update. The nscontrol command uses Windows Authentication to connect to SQL Server.

nscontrol update -in "C:\NS\Stock\InstanceConfig.xml" -force

E. Updating an instance using SQL Server Authentication

Important

When possible, use Windows Authentication.

This example shows how to update an instance using SQL Server Authentication to connect to SQL Server. The nscontrol update command displays all differences found in the updated configuration file and the ADFs. You are prompted to answer yes or no before the update proceeds.

nscontrol update -in "C:\NS\Stock\InstanceConfig.xml" 
    -sqlusername SqlUser -sqlpassword sQl-P@sWd

Change History

Release	History
5 December 2005	New content: Added information about the SQLServerNotificationServicesUser Windows group.

Share via