nscontrol create Command

Creates a new instance of Microsoft SQL Server Notification Services.

Syntax

nscontrol create 
    [-nologo]
    [-help]
        -in configFile
    [-sqlusername sqlUserName  -sqlpassword sqlPassword]
    [-argumentkey key]
    [param=value ...]

Arguments

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

• -help
  Displays the command syntax.

• -inconfigFile
  Specifies 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.

• -sqlusernamesqlUserName
  Specifies the SQL Server login used to connect to SQL Server.

  If you are using SQL Server Authentication to connect to SQL Server, specify a login ID with this argument. This argument must be used together with the -sqlpassword argument.

  If you are using Windows Authentication to connect to SQL Server, do not use the -sqlusername and -sqlpassword arguments.

  Note

  When possible, use Windows Authentication.

• -sqlpasswordsqlPassword
  Specifies the password that is associated with the -sqlusername login ID. This argument must be used together with the -sqlusername argument.

• -argumentkeykey
  Specifies the key used to encrypt delivery channel and event provider arguments that are stored in Notification Services databases. The key is a string of up to 2500 characters.

  This argument is required if the EncryptArguments value in the configuration file is true. You cannot change the key value used by the instance after you run the nscontrol create command. To use a different key, you must delete and then re-create the instance.

  You must also specify the same key value when you run the nscontrol register command and the nscontrol update command. The nscontrol register command encrypts the key value and stores it in the registry.

• param=value
  Is a name/value pair used to pass parameter values to the ICF from the command prompt.

  Any string that appears between percent sign (%) characters in the ICF is a replaceable parameter. If the ICF contains replaceable parameters (such as DBSystem in the following example), specify the parameter name and value on the command line (or in the ParameterDefaults section of the ICF). For example, if the configuration file contains the following XML:

  <SqlServerSystem>%DBSystem%</SqlServerSystem>
  

  Then you can specify the name and value using nscontrol create 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 directly to parameters in the application definition files (ADFs). To pass parameter values to an ADF, add a Parameters subsection to the Application section of the ICF. You can use replaceable parameters and 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 create command validates the ICF and the ADFs against their XML schemas and checks for illegal values, such as a true value for both multicast delivery and digest delivery. If the validation or checks do not pass, nscontrol create stops without creating the instance.

The nscontrol create command turns on cross-database ownership chaining in the instance and application databases. These databases require cross-database ownership chaining to allow Notification Services stored procedures to access objects in the instance and application databases.

If you are using Notification Services Standard Edition, and one or more elements are not supported by Standard Edition, nscontrol create stops without creating the instance. For more information about Notification Services Standard Edition, see Editions of Notification Services.

You can run nscontrol create from any computer that has the Notification Services client components installed and that has access to the SQL Server database engine that will store instance and application metadata.

Before you can run the instance of Notification Services, you must register the instance using nscontrol register. Registration creates a registry entry and optionally creates a Windows service you can use to run the instance.

You cannot use nscontrol create to update an instance. Instead, use nscontrol update.

Permissions

The account that you use to run nscontrol create, or the SQL Server login that you specify in the -sqlusername argument, must be a member of the sysadmin fixed server role. The account 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 show how to create an instance of Notification Services.

A. Basic example

This example shows how to create a new instance of Notification Services using the ICF InstanceConfig.xml and connect to SQL Server using Windows Authentication.

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

B. Providing values for configuration file parameters

This example shows how to pass values to the parameters BaseDirectoryPath, NSHost, and SqlServer in the ICF. The nscontrol command connects to SQL Server using Windows Authentication.

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

C. Providing an argument encryption key

This example shows how to provide an argument encryption key when creating the instance. Note that the key must match the key used when registering the instance.

The nscontrol command connects to SQL Server using Windows Authentication.

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

D. Using SQL Server Authentication

This example shows how to create a new instance of Notification Services using SQL Server Authentication to connect to SQL Server.

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

See Also

Reference

nscontrol Utility

Other Resources

EncryptArguments Element (ICF)
Deploying an Instance of Notification Services

Help and Information

Getting SQL Server 2005 Assistance

Change History

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