*************************************************************** Microsoft SQL Server Notification Services Readme File August 12, 2002 *************************************************************** (c) Copyright Microsoft Corporation, 2002. All rights reserved. This file contains information that supplements the Microsoft® SQL Server™ Notification Services documentation. *************************************************************** CONTENTS *************************************************************** 1.0 Introduction 1.1 Accessing Notification Services Documentation 2.0 Installing SQL Server 2000 2.1 Hardware and Software Requirements 2.2 Installing Notification Services 2.3 Running Notification Services Samples 2.4 Uninstalling Notification Services 3.0 Product and Documentation Notes 3.1 Troubleshooting: SSL Security Errors 3.2 Disable Instance Before Running NSControl Upgrade 3.3 EventCollector.Write Method Does Not Return a Value 3.4 Do Not Use Digest Delivery With a Large Notification Batch Size 3.5 Incorrect Event Source Name in Documentation 3.6 Troubleshooting: Setup Completes Without Installing Notification Services 3.7 Event Messages Indicate Event Message DLL Cannot Be Found 3.8 Encryption Argument Key Value is Character String 3.9 Disabling Subscribers Disables the Instance *************************************************************** 1.0 Introduction *************************************************************** This file contains important information you should read before using Notification Services. For the latest information about Notification Services, visit the Notification Services Web site at www.microsoft.com/sql/ns. *************************************************************** 1.1 Accessing Notification Services Documentation *************************************************************** The Notification Services documentation is installed by the Setup program. You can install the documentation without installing Notification Services, which enables you to read the installation instructions and learn about the Setup options before installing Notification Services. *************************************************************** 2.0 Installation *************************************************************** Notification Services Setup can install five sets of components and one subcomponent: * The engine components, which run the Notification Services event collection, generation, formatting, and delivery functions. These components must be installed on all servers that perform any of these functions. * The client components, which must be installed on servers that host independent event providers and subscription management applications. These components contain the interfaces used by your independent event providers and subscription management applications. The NSControl utility, which you use to administer an instance of Notification Services, is also installed as part of the client components. * The Bulk Event Submission subcomponent, which must be installed with the client components if you want to use the SQLXML bulk loader to submit XML data to SQL Server 2000. * The database components, which must be installed on the SQL Server 2000 database engine system. The database components include extended stored procedures used to generate notifications. * Documentation, which can be installed anywhere you want to have access to the Notification Services documentation. * A set of sample applications that you can use to become familiar with Notification Services. You can run the samples from within Microsoft Visual Studio® .NET. You can install all components on one server, or you can install components on separate servers as needed. -------------------------------------- 2.1 Hardware and Software Requirements -------------------------------------- Before you install Notification Services, ensure that your computer meets the following requirements: Hardware for Core Components =============================================================== * Computer Pentium 450 MHz minimum, Pentium 733 MHz or higher recommended. * Memory (RAM) 128 MB minimum, 256 MB or more recommended. * Hard disk space Notification Services components: 10 MB. If the databases are on the same server as Notification Services, additional disk space is required for your database tables, log files, and temporary database tables. Software for Engine Components =============================================================== * Operating system Microsoft Windows® 2000 (or higher) or Windows XP Professional. * Microsoft Data MDAC version 2.6 or higher, required Access Components to install the Microsoft .NET Framework; (MDAC) also required by Microsoft SQLXML. * SQL Server 2000 SQL Server 2000 client tools, required Client Tools by SQLXML. * Microsoft SQLXML SQLXML version 3.0 or higher. Microsoft recommends SQLXML 3.0 SP1 or higher. * .NET Framework .NET Framework version 1.0.3705 or higher. To obtain MDAC, MSXML, and SQLXML, go to http://www.microsoft.com/downloads. Software for Client Components =============================================================== * Operating system Microsoft Windows 2000 SP2 (or higher) or Windows XP Professional. * Microsoft Data MDAC version 2.6 or higher, required to Access Components install the .NET Framework; also (MDAC) required by SQLXML. * .NET Framework .NET Framework version 1.0.3705 or higher. Software for Bulk Event Submission Subcomponent =============================================================== * SQL Server Tools SQL Server 2000 client tools, required by SQLXML. * Microsoft SQLXML SQLXML version 3.0 or higher. Microsoft recommends SQLXML 3.0 SP1 or higher. Software for Database Components =============================================================== * SQL Server SQL Server 2000 Standard Edition, SQL Server 2000 Enterprise Edition, or SQL Server 2000 Developer Edition Microsoft recommends the most recent service pack for SQL Server 2000. Software for Documentation =============================================================== * Internet software Microsoft Internet Explorer 5.01 or higher. Software for Samples =============================================================== * Development tools All the samples are presented as Visual Studio .NET solutions with solution (.sln) files. You can use the samples without Visual Studio. NET; however you will need to edit the files with a text editor or other XML editor. * Internet Information The system that runs the samples must Services (IIS) have Internet Information Services (IIS) 5.0 or higher installed and running. This includes the Simple Mail Transfer Protocol (SMTP) service, the World Wide Web Publishing service, and the IIS Admin service. ------------------------------------ 2.2 Installing Notification Services ------------------------------------ Installation Notes: * To run Notification Services Setup, the account you are using must be a member of the local Administrators group. To install the database components, the account you are using or an account you specify during Setup must be a member of the SQL Server sysadmin fixed server role. * You must run installation locally. Remote Setup is not available. * When you install the database components, make sure that the SQL Server 2000 database engine is running. Setup will not attempt to start SQL Server. Installation Instructions: 1. Run MicrosoftSQLServerNotificationServices.exe. 2. On the Custom Setup screen, select the components you want to install. Ensure that the system meets the software requirements listed above. If the system does not meet the requirement for a component, you will not be able to install that component. You do not need to take corrective steps unless you want to install a component that is not available. 3. If you are installing the database components, enter additional information on the Database Component Setup and SQL Server Login Information screens: * If you have multiple instances of the SQL Server database engine installed, select one instance on the Database Components Setup screen. You can install the components on additional instances using the InstallXPs utility. * Select the type of authentication to use to log in to SQL Server on the SQL Server Login Information screen. Enter your user name and password if using SQL Server Authentication. 4. On the Ready to Install the Program screen, click Install. ----------------------------------------- 2.3 Running Notification Services Samples ----------------------------------------- When you install the sample applications, Setup adds the sample applications to the Notification Services Vn.n.n.n\Samples folder. For more information about the sample applications, view the SQL Server Notification Services Samples Web page. The Web page is available from the Start menu. On the Start menu, point to Programs, and then point to Microsoft SQL Server Notification Services. -------------------------------------- 2.4 Uninstalling Notification Services -------------------------------------- To uninstall Notification Services: 1. From the Samples folder, run RemoveSamplesDB.cmd to delete any samples that use the Notification Services version you are removing. 2. Stop all instances of Notification Services that use the version you are removing. To stop an instance, run the following command: net stop NS$ 3. If using SQL Authentication, run UninstallXPs.cmd to remove the database components. Uninstall does not prompt for the SQL Server user name and password. The UninstallXPs script allows you to provide this information. 4. Click Add/Remove Programs in Control Panel. 5. Select Microsoft SQL Server Notification Services, and then click Remove. 6. Follow the on-screen instructions. *************************************************************** 3.0 Product and Documentation Notes *************************************************************** These are issues that arose after the Notification Services Books Online documentation was completed. ---------------------------------------- 3.1 Troubleshooting: SSL Security Errors ---------------------------------------- If you receive SSL security errors in the event log when creating an instance or running the NS$ service, Notification Services might not be able to connect to SQL Server 2000. This error might be caused by the following issues: * If the Certificate Server is installed on a Microsoft Windows 2000 computer and the Certificate Authority (CA) name is the same as or starts with the machine host name, an attempt to connect to SQL Server 2000 might fail. To resolve this problem, obtain the latest service pack for SQL Server 2000. For more information, search for Knowledge Base article Q302409 at the Microsoft Product Support Services Web site at http://support.microsoft.com. * If there is a slow network connection to the target server that is running SQL Server or to the server that authenticates Windows credentials, an attempt by Notification Services to connect to SQL Server might fail. This problem occurs only if you have a Secure Sockets Layer (SSL) certificate installed on the computer that is running SQL Server and if that SSL certificate meets the requirements to perform encryption. To resolve this problem, follow the instructions in Knowledge Base article Q322144 at the Microsoft Product Support Services Web site at http://support.microsoft.com. ----------------------------------------------------- 3.2 Disable Instance Before Running NSControl Upgrade ----------------------------------------------------- Before running NSControl Upgrade to upgrade instances of Notification Services from Standard Edition to Enterprise Edition, disable the instances before uninstalling Standard Edition. Use the following procedure to perform an upgrade from Standard Edition to Enterprise Edition: 1. Use the NSControl Disable command to disable all instances that use Standard Edition. 2. Use the Net Stop command to stop the corresponding NS$ services. 3. Uninstall Notification Services Standard Edition. 4. Install Notification Services Enterprise Edition. 5. Use NSControl Upgrade to upgrade each instance that used Standard Edition to Enterprise Edition. 6. Use NSControl Enable to enable all instances that you upgraded. 7. Use the Net Start command to start the corresponding NS$ services. ------------------------------------------------------- 3.3 EventCollector.Write Method Does Not Return a Value ------------------------------------------------------- The EventCollector.Write Method topic shows the method returning an integer value. EventCollector.Write does not return a value. The corrected information for this method follows: [Visual Basic .NET] Public Function Write(ByVal As Object) [C#] public void Write(object ); [C++] public: void Write(Object* ); [JScript] public function Write( : Object); ------------------------------------------------------- 3.4 Do Not Use Digest Delivery With a Large Notification Batch Size ------------------------------------------------------- If you enable digest delivery for a notification class by setting the value in the application definition file (ADF) to true, do not set a custom notification batch size using the element. Setting a large value can cause the number of connections to SQL Server to quickly increase, consuming all available memory. ------------------------------------------------ 3.5 Incorrect Event Source Name in Documentation ------------------------------------------------ Notification Services events are logged to the Windows application log. Windows Event Viewer shows the source of the events in the application log in the Source column. The source of all Notification Services events is NotificationServices. The Event Logging Overview and Choosing Monitoring Tools topics incorrectly document the source as NS$. ------------------------------------------------------- 3.6 Troubleshooting: Setup Completes Without Installing Notification Services ------------------------------------------------------- When you run Setup, if the "InstallShield Wizard Completed" page appears immediately and contains the following text, the account used to run setup might not have the necessary permissions: The wizard was interrupted before Microsoft SQL Server Notification Services could be completely installed. Your system has not been modified. To complete installation at another time, please run setup again. First, ensure that the account used to run Setup has local Administrator privileges. If the account does have local Administrator privileges, the problem can still occur if the following two conditions exist on the computer: * The registry key value "DefaultAccessPermission" exists under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Ole. * The default access permissions assigned to Component Services do not include the account used to run Setup. Note: By default, the registry value DefaultAccessPermission under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Ole does not exist. The value is created by other applications or when you use the Component Services tool to add groups or users to the COM default access permissions. To add the account used to run Setup to Component Services: 1. From the Start menu, click Run. 2. In the Run box, enter Dcomcnfg.exe. 3. Display the Default COM Security tab using the instructions for your operating system: * If running the Windows 2000 operating system, click the Default Security tab. * If running the Windows XP operating system, do the following: a. Navigate to Component Services\Computers\My Computer. b. Right-click My Computer and select Properties. c. Click the Default COM Security tab. 4. Click the Edit Default button. 5. Click the Add button and add the account used to run Setup. -------------------------------------------------------------- 3.7 Event Messages Indicate Event Message DLL Cannot Be Found -------------------------------------------------------------- If you install multiple versions of Notification Services on a computer and then uninstall a version, Notification Services messages in the event log might contain the following text, which indicates that the instance cannot find the event message DLL. The description for Event ID ( #### ) in Source ( NotificationServices ) cannot be found. The local computer may not have the necessary registry information or message DLL files to display messages from a remote computer.... The full text of the event message is present after this text; however, the link to Web content for the event message is not included with the message. To fix this issue, use NSControl Register to re-register any instance of Notification Services that uses an installed version. This repairs a pointer to the event message DLL. For more information, see "Re-Registering an Instance" in Notification Services Books Online. ------------------------------------------------------- 3.8 Encryption Argument Key Value is a Character String ------------------------------------------------------- The NSControl Create, NSControl Update, and NSControl Register commands have an optional "argumentkey" argument that specifies a key value used to encrypt delivery channel and event provider arguments. The key value must be a character string. If the string contains any spaces, enclose the string in quotation marks. For more information, see the "Configuring Argument Encryption" topic in Notification Services Books Online. ----------------------------------------------- 3.9 Disabling Subscribers Disables the Instance ----------------------------------------------- If you use NSControl Disable to attempt to disable only the subscribers of an instance, NSControl will disable the entire instance and all applications hosted by the instance. To resolve this issue, use one of the following two methods: * After you disable the subscribers component, re-enable all other components of the instance using NSControl Enable: nscontrol enable -n -distributor -events -generator -subscriptions * When disabling subscribers, include another component to disable and then re-enable that component: nscontrol disable -n -generator -subscribers nscontrol enable -n -generator You can check the status of the instance using the NSControl Status command: nscontrol status -n