Downloads
21223.zip

Using the Query Helper API in ASP to put Indexing Service into action

\[Author's Note: Each month, this column discusses various aspects of the advanced administration of e-business sites. Last month, I examined the setup, configuration, and implementation of Windows 2000 Indexing Service 3.0. This month, I show you how to put Indexing Service to use with a simple, customized Active Server Pages (ASP) application that provides powerful search capabilities.\]

Last month, I introduced you to Indexing Service and showed you how to set it up and configure it. This month, I show you how to customize a sample ASP application that uses the Query Helper API to put Indexing Service into action.

Indexing Service provides content indexing of Web site content and file-system content, a feature that separates Indexing Service 3.0 from its Windows NT 4.0 predecessor, Index Server. Indexing Service can extract text and property information from files on both the local host and remote, networked hosts. With Indexing Service, you can use custom search pages to create Web applications.

Indexing Service requires Win2K Professional, Win2K Server, Win2K Advanced Server, or Win2K Datacenter Server. For the examples I provide here, I assume that you have access to Win2K Server, Win2K AS, or Datacenter and have performed a default installation, which includes installation of IIS 5.0 and Indexing Service 3.0.

Indexing Service APIs
Before I show you how to create custom search pages, let me briefly discuss the APIs available to Indexing Service. Many programming languages have several APIs that communicate with Indexing Service. You or your developers can choose the API that's most applicable to your environment and experience. When choosing an API, you must balance programming complexity with application performance. In the most general terms, the OLE DB Provider API is the most difficult API to program. APIs that encapsulate the OLE DB Provider (e.g., Admin Helper, Query Helper) are easier to program, but they're less flexible and slower to execute. Consequently, the OLE DB Provider API is the fastest and offers the greatest flexibility. Later in this article, I show you how you can easily implement the Query Helper API in a simple ASP application. Table 1 summarizes the APIs available for Indexing Service.

Using the Sample Search Applications from the SDK
The Win2K Platform software development kit (SDK) has fantastic developer documentation and sample applications that provide everything you need to start writing custom search applications for Indexing Service. After you've installed the Platform SDK, you can install the sample search applications by navigating to \program files\microsoft platform sdk\samples\winbase\indexing\iissearch. Double-click install.bat. The installation command file copies many .html files and ASP applications to your \%systemdrive%\inetpub\iissamples\issamples folder. (You can also download query.asp from the Code Library on the IIS Administrator Web site at http://www.iisadministrator.com.) After you've installed the SDK, run Microsoft Internet Explorer (IE) or any other browser, then navigate to the sample Indexing Service application at http://localhost/iissamples/issamples, which Figure 1 shows.

Notice in the left pane of your browser's window that the sample application is more than just one ASP application. In fact, there are six different sample applications:

  • Query.asp—This simple ASP sample is written in server-side VBScript and client-side JScript (Microsoft's implementation of JavaScript) that uses the Query Helper API to execute Indexing Service Query Language queries. I explain this application and show you how to implement it later in the article.
  • Query.htm, query.idq, query.htx—This .htm, Internet Data Query (IDQ), and HTML Extension files (HTX) sample uses the Internet Server API (ISAPI) Extensions API.
  • Fastq.htm, fastq.idq, fastq.htx—This optimized IDQ and HTX example uses the ISAPI Extensions API.
  • Sqlqhit.asp, sqlqhit.htm—This simple ASP sample is written in VBScript and illustrates how to use the OLE DB Provider for Indexing Service API to execute queries.
  • Advquery.asp—This advanced ASP sample is written in VBScript and JScript and illustrates how to use the Query Helper API with server-side scripting to execute Indexing Service Query Language queries.
  • Advsqlq.asp—This advanced ASP sample is written in VBScript and JScript and illustrates how to use the ADO and Query Helper APIs with server-side scripting to execute SQL scripts on Microsoft SQL Server.

A simple HTML page called default.htm manages all six applications and provides easy access to each sample. You can easily modify and customize any of these sample applications for integration into your Web applications. Equally as important, each of these applications stands alone (i.e., can be called directly) without the default.htm menu application, which makes copying the code and integrating it into your Web applications simple.

Customizing Query.asp
To begin creating your custom search application, create a virtual directory or folder on your IIS 5.0 Web server to house your Indexing Service ASP search application. (I created a folder at \inetpub\wwwroot\search, created a virtual directory called Search under the Default Web site, then mapped to the \search folder.) Default access permissions are sufficient. Copy the query.asp application file and its supporting .htm Help files and images (i.e., query.asp, is2foot.inc, ixtiphlp.htm, ixqlang.htm, rankbtn1.gif through rankbtn5.gif, hilight.gif) to the Search folder. To test whether the ASP application functions correctly, follow these steps:

  1. Open a browser.
  2. Navigate to and run query.asp, as Figure 2 shows.
  3. Run a search. (I searched for Platform SDK.)
  4. View the results of the successful search.

Notice that the image on the query.asp page is a broken link. I show you how to replace that image with a custom image later.

Now, open query.asp in your favorite editor. (I use Microsoft Visual InterDev.) Notice that query.asp includes instructions in the form of VBScript comments about how to customize the application. Even if you have no programming experience, you can use these instructions to create a custom search application. Let's begin by modifying the look and feel of query.asp by changing some of the HTML. Copy an image file of your company logo into the Search folder, then change the line at callout A in Listing 1 to the name of your logo file. In my case, I changed

FormLogo = "is2logo.gif"

to

FormLogo = "InterKnowlogyLogo.gif"

Save query.asp, then refresh the page in your browser. Your logo will appear on the search page.

Next, you can change the page background to a color or an image by changing the lines at callout B in Listing 1. If you want to use an image for your background, change the first line and comment out the second line. If you want to use a color for your background, change the second line and comment out the first line.

Now, change the title of the page to something more descriptive. In my case, I changed the line

<TR><TD ALIGN="RIGHT"><H3>Sample ASP Search
Form</H3></TD></TR>

to the line at callout A in Listing 2. Save query.asp, then refresh the page in your browser to see the new title.

Finally, remove the broken images and text relating to Microsoft in the page footer. To remove the images and text, completely remove the reference to the footer file is2foot.inc by deleting the line

<!-- #include file ="is2foot.inc" -->

If you want to change the footer to content more specific to your application, you can edit is2foot.inc rather than deleting it. Similarly, if you're integrating this search functionality into an existing application, you might include a standard footer file that you're already using in the other pages of your application. Whichever method you choose, make your changes, save the file, then refresh the page in your browser to see the changes. Figure 3 shows a customized query.asp application.

You now have a fully functional, customized, and robust search application that you can easily integrate into any existing application. Query.asp contains simple instructions about how to customize the page even further. For example, you can

  • modify the form's search scope
  • modify the number of returned query results
  • set the language locale
  • enable the persistence of active searches in session variables

I encourage you to examine the Indexing Service COM components from the Query Helper API that query.asp uses so that you can see how easy it is to iterate the results in the application's ADO recordset.

Summary
Indexing Service is a powerful tool that you can use to provide searching utility to your intranet, extranet, or Internet applications simply, quickly, and easily. Integrating the sample applications from the Platform SDK into your existing applications is equally simple, which makes the implementation of search capability into your applications quick and easy, even for nonprogrammers.

Remember that if you want to research Indexing Service further, searching the Web (or the Microsoft site) for "Index Server" is only going to produce frustration. You must search for "Indexing Service." Another great resource for Indexing Service is http://msdn.microsoft.com/library/psdk/indexsrv/indexingservicestartpage_6td1.htm.

For more details about the Indexing Services sample files included in the Platform SDK, search the Platform SDK Help for "IISSearch Sample." Next month, I'll introduce you to two distinct programming approaches to Web administration. I'll show you how to use ASP and Windows Script Host (WSH) to create, administer, and maintain Web sites.

Note: The complete Platform SDK is available as part of Microsoft Visual C++ (VC++) 6.0, a Microsoft Developer Network (MSDN) Professional subscription, an MSDN Universal subscription, or from http://www.microsoft.com/msdownload/platformsdk/setuplauncher.htm. A low-cost SDK CD-ROM is also available from http://developerstore.com.