nscontrol disable Command

Disables the specified Microsoft SQL Server Notification Services instance, application, or component.

Syntax

nscontrol disable 
    [-nologo]
    [-help]
    [<component> [...n ]]
        -name instanceName
    [-server databaseServer]
    [-application applicationName]
    [-sqlusername sqlUserName -sqlpassword sqlPassword]

< component > ::=
    -events [systemName]
    | -generator
    | -distributor [systemName]
    | -subscriptions
    | -subscribers 

Arguments

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

• -help
  Displays the command syntax.

• <component>
  Represents a component to disable. You can specify zero or more components when you run nscontrol disable.

  If you do not specify a component, all components of the instance or application are disabled. If you specify a component but do not specify an application name using the -application argument, all matching components in all applications hosted by the instance are disabled.

  <component> can be any of the following arguments:

  Argument	Description
  -distributor [systemName]	Disables distribution for the instance or application. If you specify a distributor system name, the distributors on only that system are disabled. Otherwise, all the distributors for the instance or application are disabled.
  -events [systemName]	Disables the hosted event providers for the instance or application. If you specify a system name, the hosted event providers on only that system are disabled. Otherwise, all hosted event providers for the instance or application are disabled.
  -generator	Disables the generator.
  -subscriptions	Disables subscription management.
  -subscribers	Disables subscriber management for the instance of Notification Services.

• -nameinstanceName
  Specifies the name of the instance that is affected by nscontrol disable. If you specify the -name argument without specifying -application or a component, nscontrol disables all instance applications and components.

  See the -server argument for information about using the -name argument with the -server argument.

• -serverdatabaseServer
  Specifies the name of the server that hosts the instance and application databases. If you use a named instance of SQL Server to host the databases, you must specify the server name and the instance name using the format <servername>\<instancename>.

  When you run nscontrol disable on a system where the instance has previously been registered using the nscontrol register command, use the -name argument but not the -server argument. The nscontrol utility determines the SQL Server instance name by reading the registry information of the instance.

  When you run nscontrol disable on a system where the instance is not registered, you must use both the -name and -server arguments, because the nscontrol utility needs both the Notification Services instance name and the SQL Server instance name in order to locate the instance database.

  When you specify the -server argument, the nscontrol utility ignores any registry values for the instance.

• -applicationapplicationName
  Specifies the name of the application in which you are disabling one or more components. If you do not specify an application name, components are disabled for all applications that are hosted by the instance.

• -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 the login using this argument. Also specify a password using the -sqlpassword argument.

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

  Important

  When possible, use Windows Authentication.

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

Remarks

The nscontrol disable command changes the status of the specified components to Disable Pending by updating a value in a database. Instance state is stored in the instance database. Individual component state is stored in the application database.

When you run nscontrol disable, Notification Services broadcasts the desired state change to all components. The state changes from "Disable Pending" to "Disabled" after all running components have responded to the change. With the exception of the subscriber and subscription components, the instance must be running for component states to change from Disable Pending to Disabled. However, changing the state from Enable Pending to Disabled or Disable Pending to Enabled does not require the service to be running, because these actions simply cancel a pending operation.

After nscontrol disable modifies the database, it displays the current status of the instance, the applications, and the components. For descriptions of the status values, see Viewing the Status of Instances, Applications, and Components.

When an engine (usually the NS$instance_name Windows service) starts, it determines where it is running (its host name) and then compares this value to the SystemName value for each distributor, hosted event provider, and generator. If the host name matches the SystemName value, the service checks the component state. If the component is enabled, it runs on the server. If a component is disabled, the component does not run.

While the service is running, it checks the database every 30 seconds to determine the state of the hosted event providers, the generator, and the distributors. Therefore, if you make a change to the state of any of these components, it may take up to 30 seconds for that change to take effect.

The subscribers and subscriptions state is stored on the database server and the subscription management objects check this state before they perform subscription or subscriber operations.

Permissions

The account used to run nscontrol disable, or the SQL Server logon ID specified by the -sqlusername argument, can obtain the proper permissions through membership in the NSAdmin database role in individual application and instance databases. Members of the db_owner database role and the sysadmin and dbcreator fixed server roles also can run nscontrol disable.

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

A. Disabling the entire instance of Notification Services

The following example disables an entire instance of Notification Services, named StockInstance. The nscontrol command uses Windows Authentication to connect to SQL Server. The instance must be registered on the computer where you run the command.

nscontrol disable -name StockInstance

B. Disabling a single application

The following example disables all components of the Stock application hosted by the StockInstance instance of Notification Services. The nscontrol command uses Windows Authentication to connect to SQL Server. The instance must be registered on the computer where you run the command.

nscontrol disable -name StockInstance -application Stock

C. Disabling all hosted event providers

The following example disables all event collection for all applications in the StockInstance instance of Notification Services. The nscontrol command uses Windows Authentication to connect to SQL Server. The instance must be registered on the computer where you run the command.

nscontrol disable -name StockInstance -events

D. Disabling an instance from an administration computer

If you run nscontrol disable from a computer where StockInstance is not registered, you must supply the SQL Server instance name using the -server argument. The following example shows how to disable an instance when the databases are on an instance of SQL Server named nsuetest. The nscontrol command uses Windows Authentication to connect to SQL Server.

nscontrol disable -name StockInstance -server nsuetest

E. Disabling an instance using SQL Server Authentication

Important

When possible, use Windows Authentication.

The following example disables an entire instance of Notification Services named StockInstance. The nscontrol command uses SQL Server Authentication to connect to SQL Server. The instance must be registered on the computer where you run the command.

nscontrol disable -name StockInstance -sqlusername SqlUser 
    -sqlpassword sQl-P@sWd

See Also

Reference

nscontrol Utility

Other Resources

Enabling and Disabling Instances, Applications, or Components

Help and Information

Getting SQL Server 2005 Assistance

Change History

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