Get Started Using SQL Server 2005 Notification Services : Page 3

Using NSControl.exe
After configuring the SQLNS instance and application you must create all the necessary databases and tables specified in the configuration files. SQLNS provides a command utility tool called nscontrol.exe to simplify the process. Table 4 describes the nscontrol.exe options.

Table 4. The table lists the command-line options available for nscontrol.exe.

Option	Description
Create	Creates a new instance of SQLNS.
Delete	Deletes an existing instance of SQLNS.
Disable	Disables a SQLNS instance.
Enable	Enables a SQLNS instance.
Register	Registers a new instance of SQLNS.
Unregister	Unregisters a instance of SQLNS.
Update	Updates an existing instance of SQLNS.

For example, to create a new instance of SQLNS you call nscontrol.exe with the Create option and supply the name of the Instance Configuration file as a parameter to the call as follows:

   nscontrol.exe -Create -In Instance.xml 

The In parameter specifies the instance configuration file that nscontrol.exe should process. When you make this call, nscontrol.exe creates a new SQLNS instance and registers the SQLNS application with that new instance. In addition, it creates the instance database DMNSMain and the application database DMStockPrice with the structure specified in the Application Definition File. These database names are created automatically by nscontrol.exe and can't be customized in any configuration file.

Defining Events
To make use of SQLNS you need to define events that SQLNS will process to produce notifications. SQLNS processes events from an EventProvider, which writes the new events to the event table. You need to define Event classes that process new incoming events. You define the Event classes in the Application Definition file in the <EventClasses> section. Listing 2 shows the Event class definition for the sample application.

Listing 2 defines only defining one event, called StockEvt. This event consists of the properties StockCode, ExchangeCode and Price. When you create or update the application using nscontrol.exe, it creates a new event table for use by the SQLNS application. To process events you need one additional component—an Event Provider. Event Providers pass new events to SQLNS for processing. You configure Event Providers through the <Providers> section in the Application Definition file as illustrated by the following XML fragment. You can place the <Providers> node anywhere in the configuration file.

   <Providers>
      <HostedProvider>
         <ProviderName>
            StockEP
         </ProviderName>
         <ClassName>
            FileSystemWatcherProvider
         </ClassName>
         <SystemName>
            localhost
         </SystemName>
         <Arguments>
            <Argument>
              <Name>WatchDirectory</Name>
              <Value>C:\Events</Value>
            </Argument>
            <Argument>
               <Name>SchemaFile</Name>
               <Value>Schema.xsd</Value>
            </Argument>
           <Argument>
              <Name>EventClassName</Name>
              <Value>StockEvt</Value>
           </Argument>
         </Arguments>
      </HostedProvider>
   </Providers>

The <Providers> section shown above defines an Event Provider named StockEP that uses the built-in FileSystemWatcherProvider. This provider monitors a directory for new files. For example, in the sample application scenario another application periodically places a new file into the WatchDirectory, defined as C:\Events. The StockEP provider watches this directory, processes the event, and writes a new record into the event table. After adding the <Providers> section to the Application Definition file, you must update the SQLNS application using nscontrol.exe.

   nscontrol.exe --Update --in appADF.xml

Because the FileSystemWatcherProvider is a so-called Hosted Provider (the other option is a Non-hosted Provider), you must activate the Service Mode on the SQLNS instance. A Hosted Provider is hosted within a SQLNS instance and a Non-hosted Provider can be hosted in your own application. When you do that, the SQLNS instance runs as a normal Windows Service and monitors the specified directory for new incoming events in the form of XML files.

   nscontrol.exe --Register name DM --server 
      localhost --service

When you execute this command nscontrol.exe creates and starts a new Windows Service named NS$DM. SQLNS always adds the prefix NS$, which indicates that this is a Windows Service used for SQLNS. You can't change the service name prefix using configuration. Because the service is a normal Windows Service you can administer it through the standard MMC Services snap-in.

The <Providers> section shown above also specifies a XSD schema. All new event files written in the event directory must be successfully validated against that XML schema file. Here's the definition for the XML schema file used in the sample application.

   <xsd:schema 
      xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
      xmlns:sql=
      "urn:schemas-microsoft-com:mapping-schema">
      <xsd:element 
         name="event" 
         sql:relation"StockEvt">
         <xsd:complexType>
            <xsd:sequence>
               <xsd:element
                  name="StockCode" 
                  type="xsd:string" />
               <xsd:element
                  name="ExchangeCode"
                  type="xsd:string" />
               <xsd:element
                  name="price"
                  type="xsd:decimal"
            </xsd:sequence>
         </xsd:complexType>
      </xsd:element>
   </xsd:schema>

According to that schema, an XML event file can have the following structure:

   <?xml version="1.0" encoding="utf-8" ?>
      <event
         xmlns="http://tempuri.org/
         XMLSchema.xsd">
      <StockCode>MSFT</StockCode>
      <ExchangeCode>NYSE</ExchangeCode>
      <Price>60.54</Price>
   </event>

SQLNS processes those event files and writes a new record in the application's event table, NSStockEvtEvents.

Previous Page

Next Page

---

• Download The Code for this Article

---