Indexing Service

Version 3.0

Purpose

Indexing Service is a Microsoft® Windows® 2000 base service for file systems and Web servers. Formerly known as Index Server, its original function was to index the content of Internet Information Services (IIS) Web servers. Indexing Service now creates indexed catalogs for the contents and properties of both file systems and virtual Webs.

Where Applicable

Indexing Service is available to applications and scripts for providing an efficient means of managing, querying, and indexing information in file systems or Web servers. Indexing Service also provides query mechanisms for efficiently accessing the information in the catalogs. The indexed information results from filtering the file systems and the Web servers using Microsoft-supplied filters and, optionally, custom-supplied filters. This documentation provides overview information, task guidance, and reference information for the programmatic use of Indexing Service.

Developer Audience

The information in this documentation for Indexing Service is relevant to administrators, application and script developers, and power users interested in content filtering. To use this documentation programming experience in the following areas is desirable:

  • Visual C++®, Visual Basic®, or Visual J++® applications; or Visual Basic Scripting Edition (VBScript), JScript®, or ISAPI scripting.

  • Microsoft OLE DB and Internet Information Services.

Run-Time Requirements

To run Indexing Service requires Windows 2000 Professional, Server, or Advanced Server.

See Also

Internet Information Services

Microsoft OLE DB

Overview

General information about Indexing Service.

Using Indexing Service with File Systems

For an audience primarily interested in file system-oriented tasks.

Using Indexing Service with Web Servers

For users primarily interested in Web server-oriented tasks.

Using Custom Filters with Indexing Service

Description of the use of filters with Indexing Service to extract content and properties from custom file types.

Reference

Documentation of Indexing Service objects, interfaces, functions, structures, and other programming elements.

OLE DB Provider for Indexing Service

Describes and summarizes usage of the OLE DB Provider for Indexing Service, and provides a reference for its programming elements.

Samples

Sample programs written in Visual Basic, VBScript, Visual C++, Visual J++, JScript, and HTML.

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


Legal Information

Indexing Service

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 1997-2000 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows NT ActiveX, BackOffice, JScript, Microsoft Press, MSDN, PowerPoint, Visual Basic, Visual C++, Visual J++, Visual Studio, and Win32 are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries/regions.

International CorrectSpell® is a trademark of Lernout & Hauspie Speech Products, N.V..

Other product and company names mentioned herein may be the trademarks of their respective owners.


About Indexing Service

This section introduces Indexing Service, describes how to get started with programming, and provides overviews of its architecture, application programming interfaces (APIs), and query languages. The section consists of the following topics.

  • What is Indexing Service?
  • What's New in Indexing Service 3.0?
  • Getting Started
  • Installing the Samples
  • Further Reading
  • Architecture of Indexing Service
  • Programming for Indexing Service
  • Query Languages for Indexing Service


What is Indexing Service?

Indexing Service is a base service of Microsoft® Windows NT®/Windows® 2000 that extracts content from files and constructs an indexed catalog to facilitate efficient and rapid searching.

Indexing Service can extract both text and property information from files on the local host and on remote, networked hosts. The files can be simply members of a selected file system or part of a virtual Web hosted by, for example, Internet Information Services (IIS).

Indexing Service extracts the content by filtering—using filter components that understand a file's format. The format could include multilanguage features such as international languages and locales. A filter component implements the IFilter interface, which supplies methods to read a file to extract text and properties. Windows 2000 supplies filters for Microsoft Office files, HTML files, Multipurpose Internet Mail Extension (MIME) messages, and plain-text files.

Indexing Service then merges the extracted information into catalogs of indexes for efficient searches. Indexing is the overall process of filtering, creating index entries, and merging them into catalogs.

The final step in the indexing process is creation of a catalog that contains a master index (and any temporary word lists and shadow indexes) storing words and their locations within a set of indexed documents. Subsequently, searching, or querying, the catalogs for particular word combinations uses the master index as well as word lists and shadow indexes to execute queries quickly and efficiently.

Windows 2000 includes basic facilities for querying the Indexing Service catalog and for managing the state and properties of Indexing Service itself. These facilities include:

  • When Indexing Service is running, Start/Search/For Files or Folders uses the Indexing Service catalog.
  • The Indexing Service snap-in for the Microsoft Management Console (MMC) provides the means to start, stop, and pause Indexing Service, and to administer many of its properties, such as those defining its catalogs.

The Platform SDK provides additional versatile and flexible facilities for programmatically interacting with Indexing Service. These facilities include:

  • Admin and Query Helper objects and ActiveX® Data Object (ADO) methods for use with Microsoft Visual Basic®, Visual Basic Scripting Edition (VBScript), Visual J++® and JScript®.
  • ISAPI Extensions for use in .idq, .ida, and .htx files.
  • OLE DB Helper functions for use with Microsoft Visual C++®.
  • OLE DB Provider for Indexing Service interfaces for use with Visual C++.
  • IFilter interface for use with Visual C++.


What's New in Indexing Service 3.0?

Indexing Service 3.0 includes the following new features in Windows® 2000:

  • Indexing Service is now a system service that indexes the content and properties of all files defined for the "system" catalog in addition to all virtual Webs defined for the "Web" catalog.
  • When Indexing Service is started, time-intensive disk scans aren't required on NTFS file system volumes. Disk volumes converted to NTFS file system 5.0 format support the use of Update Sequence Number (USN) from the change journal. Indexing Service benefits directly from the sparse file formats and native property sets of the NTFS file system.
  • The Start/Search dialog uses Indexing Service, when available, to perform queries.
  • Programmatic read-only access is available to Indexing Service content and property indexes for resolving queries through the Microsoft® OLE DB Provider for Indexing Service:
    • Script writers (those using Microsoft® Visual Basic®, Visual Basic Scripting Edition (VBScript), JScript®, Windows Scripting Host, dynamic HTML (DHTML), or any other automation-supported programming environment) can use ADO methods and properties along with Indexing Service Query and Utility helper objects to create and control queries and display results. Indexing Service also supplies AdminIndexServer, CatAdm , and ScopeAdm administration helper objects to manage the indexing catalogs and performance.
    • C and C++ programmers can use OLE DB interface methods and properties and Indexing Service OLE DB helper functions to manage the state of the catalog, create and control queries, and display results.
  • Three query languages are now available:
    • Indexing Service query language, Dialect 1. The original query language supported in Index Server 2.0 and earlier.
    • Indexing Service query language, Dialect 2. A more powerful and extensible query language that is new to Indexing Service 3.0.
    • SQL Query Language. The SQL language with extensions tailored to accept query-related terms.
  • Expanded processing is available for query results. The functionality of the GroupBy property of the Query object can now be applied to search results so that you can specify grouping within a column in addition to specifying the columns of the result table.
  • Catalogs for removable media, including CD-ROMs, can be created using the MMC. The catalogs can reside on the removable medium, and when that medium is inserted into a computer running Indexing Service, the catalog is opened in read-only format for queries.


Getting Started

If you're seeking information about Indexing Service in the Platform SDK, you're likely to be in one of the following categories.

  • Power user or administrator
  • File system-oriented programmer or script writer
  • Web server-oriented programmer or script writer
  • Custom filter-component programmer

To get started quickly, you can select the most appropriate category and follow the suggestions in the corresponding reference. There is considerable overlap of applicable information in these sections, and eventually you might want to look through more than one.

Power User or Administrator

If you're a power user or an administrator, you probably would like to know more about how Indexing Service works and how to manage it.

To Learn About | See
The structure and operation of Indexing Service | Architecture of Indexing Service
Standard Indexing Service filters available for indexing files | Filter DLLs
Controlling how Indexing Service filters files | Controlling Filtering
Managing Indexing Service with scripts | Programming with Scripts IISAdmin Sample
Managing Indexing Service with applications | Programming with Applications ChgState Sample VBAdmin Sample

File System-Oriented Programmer or Script Writer

If you're a programmer or script writer and want to use Index Service with file systems, you probably would like to learn how Indexing Service interacts with them.

To Learn About | See
An overview of programming for Indexing Service | Programming for Indexing Service
How to program Indexing Service for file systems | Using Indexing Service with File Systems
Writing simple query applications using helper functions or ActiveX Data Objects (ADOs) | Simple Sample VBQuery Sample VJQuery Sample
Writing efficient query applications that directly access the OLE DB Provider for Indexing Service | AdvQuery Sample CatQ Sample

Web Server-Oriented Programmer or Script Writer

If you're a programmer or script writer aiming to use Index Service with Web servers, you probably would like to know more about how Indexing Service interacts with them.

To Learn About | See
An overview of programming for Indexing Service. | Programming for Indexing Service
How to program Indexing Service for Web servers | Using Indexing Service with Web Servers
Writing scripts to query Indexing Service using Dynamic HTML (DHTML) | DHtml Sample
Writing queries using an Indexing Service Query Language or the SQL language and an ASP page | IISSearch Sample

Custom Filter-Component Programmer

If you're a programmer who needs to build a custom filter, you probably would like to know more about standard Indexing Service filters and how to build a custom one.

To Learn About | See
The information needed to write an Indexing Service filter for a specific file format | Using Custom Filters with Indexing Service
Standard Indexing Service filters available for indexing files | Filter DLLs
Writing a simple filter | Constructing Filters, SmpFilt Sample
Writing more complex filters that extract value-type properties | IFilter Sample HtmlProp Sample
Testing a filter implementation | Testing Filters


Installing the Samples

To install the sample code for Indexing Service that comes with the Microsoft® Platform SDK, select Sample Code, Windows Base Samples, Indexing Service Samples in the Platform SDK Setup Wizard during installation. The system installs the sample files in subdirectories of the mssdk\samples\winbase\indexing directory.

The current topic alphabetically summarizes the Indexing Service samples. For an organization of the samples by task, language, API, and tool, see Samples by Task, Language, API, and Tool.

The following table lists the samples for Indexing Service included in the Platform SDK and provides implementation language and a short description of each sample. Selecting the name of a sample takes you to a more detailed reference for that sample.

Sample | Language | Description
AdvQuery | C++ | A command-line application that executes a query using OLE DB Provider interfaces such as ICommand and ICommandTree. It shows how to specify a catalog, machine name, and scope. It can also display the OLE DB command tree for the query.
CatQ | C++ | A Windows application that executes queries using the OLE DB Provider API. The queries are on the catalog of the local computer and restrict the scope to text files in the Platform SDK by using the MSSDK environment variable.
ChgState | C++ | A command-line application that can either report the current state of a catalog or change the state of the catalog using the SetCatalogState function of the OLE DB Helper API.
DHtml (CiDHtml) | Visual Basic® Scripting Edition (VBScript) | A dynamic HTML (DHTML) application that creates a client-side query form to query an Indexing Service catalog. The sample uses the Query Helper API for the query and an ADO recordset to return the results.
HtmlProp | C++ | An example IFilter implementation that specializes the Indexing Service HTML filter to extract value-type properties. It converts HTML meta properties to data types other than strings as specified by a configuration file.
IFilter (HtmlFilt) | C++ | An example IFilter implementation (HtmlFilt) for HTML files. It is more complex than a basic text filter, because it demonstrates techniques for extracting both text-type and value-type properties.
IISAdmin | VBScript, JScript®, IDA+HTX | A set of HTML and ASP forms that demonstrates how to use Internet Information Services (IIS) to administer Indexing Service. The forms retrieve indexing statistics, force a master merge, rescan paths, and check for documents that could not be filtered.
IISSearch | VBScript, JScript, IDQ+HTX | A set of HTML and ASP forms that demonstrates how to use Internet Information Services (IIS) to query Indexing Service. The forms use Indexing Service Query Language queries and the Query Helper API, use SQL queries and the ADO and Query Helper APIs, and use IDQ+HTX and the ISAPI Extension API.
Simple (QSample) | C++ | A command-line application that executes a query using the OLE DB Helper API functions CICreateCommand and CITextToFullTree to simplify the coding needed to create a query to an Indexing Service catalog.
SmpFilt | C++ | An example IFilter implementation that reads an unformatted text file (with the extension .smp) using the ANSI code page of the current thread, and outputs UNICODE text for the current locale. It accepts as input only single-byte-character text files and not multibyte-character or UNICODE text files. It is the simplest example of an IFilter implementation included in the Indexing Service sample code.
SQuery | VBScript, JScript | Three scripts that execute using Windows Script Host. VBSQuery is written in VBScript and performs a simple query. JSQuery is a translation of VBSQuery to JScript. QSample is written in VBScript and functions similarly to the C++ Simple Sample with managing and querying functionality.
VBAdmin | Visual Basic | A Windows application that illustrates how to administer Indexing Service using the AdminIndexServer, CatAdm, and ScopeAdm automation objects of the Admin Helper API.
VBQuery | Visual Basic | A Windows application that illustrates how to query Indexing Service using the Indexing Service Query Language Dialects and the SQL language and the ADO and Query Helper APIs.
VJQuery | Visual J++® | A command-line application that illustrates how to query Indexing Service using the SQL query language and the ADO API.


Further Reading

There are several sources of additional information about Indexing Service.

The Microsoft® Developer Network (MSDN™) Library contains several technical articles about Indexing Service:

  • Nareddy, Krishna, "Anatomy of a Search Solution," 1997.
  • Nareddy, Krishna, "Introduction to Microsoft Index Server," 1997.
  • Nareddy, Krishna,"Indexing with Microsoft Index Server," 1998.
  • Lee, David, "Using HTML Meta Properties with Microsoft Index Server," 1998.
  • Lee, David, "How to Write an IFilter," 1999.

The following two books contain information about using Index Server 2.0 with Internet Information Server 4.0.

  • Braginski, Leonid and Matthew Powell, Running Microsoft Internet Information Server, Microsoft Press®, 1998.
  • Microsoft Internet Information Server Resource Kit, Microsoft Press, 1998.

The Microsoft Windows NT® 4.0 Option Pack contains documentation that describes Index Server 2.0.

For descriptions of early versions of Indexing Service, see Swank, Mark and Drew Kittel, Designing and Implementing Microsoft Index Server, Sams.net publishing, 1997.


Architecture of Indexing Service

Indexing Service has an architecture centered around documents. It gathers and filters documents and then indexes the resulting words and properties from the documents into a catalog. Concurrently, Indexing Service processes queries for specified words and properties and then returns references to the documents in the catalog that contain the specified items.

This section illustrates the architecture of Indexing Service by describing the characteristics of documents; the components of Indexing Service that perform indexing on and querying of documents; and the flow of information from documents through the components of Indexing Service. The section consists of the following topics.

  • Properties of Documents
  • Components of Indexing Service
  • Processing in Indexing Service


Properties of Documents

Indexing Service views the documents that it processes as objects with an assortment of properties. It separates the information that a document represents into these properties — according to their characteristics — as it filters, indexes, and queries the properties. This section describes the important characteristics of document properties and how Indexing Service processes them. The following table lists the topics in the section and describes the characteristic that each topic discusses.

Topic | Characteristic
Property Names | Each property has a unique name.
Property Types | Each property represents either unformatted text in the content of the document or a formatted value that describes the whole document.
Property Filtering | Properties are extracted from documents by filters implemented for specific document types.
Property Indexing | The type of a property determines what kind of indexing occurs for the property.
Property Querying | The type of a property determines what kind of querying can occur for the property.

Indexing Service stores and accesses its information using the Microsoft® OLE DB Provider. Consequently, Indexing Service documentation sometimes uses database nomenclature — referring to document properties as attributes, columns, or fields — appropriate for the context.


Property Names

Each document property has a unique name determined by a COM-compatible naming scheme; that is, both a globally unique identifier (GUID) for a property set and a PROPSPEC structure (which specifies a numeric ID or a string name) uniquely define each property. Each property optionally can have one or more friendly names, which act as aliases for the property. For example, the same property could have different friendly names in different languages.

The following table includes several examples of document property names.

Property Set GUID (Name) | PROPSPEC ID or Name | Friendly Name
b725f130-47ef-101a-a5f1-02608c9eebac (PropertyStorage) | 0x13 | Contents
b725f130-47ef-101a-a5f1-02608c9eebac (PropertyStorage) | 0x0c | Size
f29f85e0-4ff9-1068-ab91-08002b27b3d9 (SummaryInformation) | 0x02 | DocTitle
d1b5d3f0-c0b3-11cf-9a92-00a0c908dbf1 (MetaProperty) | "description" | (none)
70eb7a10-55d9-11cf-b75b-00aa0051fe20 (HtmlInformation) | 0x03 | HtmlHeading1

These examples are just a few of the existing properties available in Indexing Service. For a complete list, see Filtering Well-Known Properties and List of Property Names for a Web Catalog. You can define and use additional properties for specific document types by entering the properties with the Microsoft Management Console (MMC) and by implementing a custom filter to extract them.


Property Types

Each document property represents either unformatted text or a formatted value. Thus, each property is said to be either a text-type or a value-type property. Text-type properties describe the possibly complex content of a document. Value-type properties describe a single property of the entire document.

A text-type property has only unformatted text associated with its name. A value-type property has a data type ID and a value of that data type associated with its name. The data type ID can be textual (for example, VT_LPWSTR) or nontextual (for example, VT_I8). If a value-type property is cached, it also has an associated cached size and a storage level, which is either primary or secondary. For details about caching and storage level, see Property Indexing.

The following table gives either the friendly name or the PROPSPEC string name of several properties and fills in the details appropriate for each property type.

Name | Type | Data Type Identifier | Cached Size | Storage Level
Contents | Text | – | – | –
Size | Value (nontextual) | VT_I8 | 8 bytes | Secondary
DocTitle | Value (textual) | VT_LPWSTR | 4 bytes | Secondary
"description" | Value (textual) | VT_LPWSTR | 4 bytes | Secondary
HtmlHeading1 | Text | – | – | –

The text-type property named Contents is a special case. It corresponds to the main body of unformatted text in a document. A document can have any number of instances of text-type properties with the same name (and typically might have many words associated with the Contents property). However, a processed document can retain the value from only one instance (usually the one encountered last) of a value-type property with a specific name.

The type of a document property determines how Indexing Service indexes the property and the kind of querying Indexing Service can perform with the property. For details about indexing, see Property Indexing, and for details about querying, see Property Querying.


Property Filtering

Properties are extracted from documents by filters implemented for specific document types. Some value-type properties are obtained by other means; for example, by the property-storage interfaces. The implementer of a custom IFilter interface can interpret the contents of a document type in any number of ways, and the descriptions here represent "best practices" for an implementation.

The IFilter interface contains several methods that Indexing Service uses when filtering a document. The methods include:

  • IFilter::Init, which returns the IFILTER_FLAGS enumeration. If the IFILTER_FLAGS_OLE_PROPERTIES member of this enumeration is set to one, Indexing Service uses the IPropertySetStorage and IPropertyStorage interfaces to enumerate and access external value-type properties.
  • IFilter::GetChunk, which returns information from a document in "chunks" with chunk type (text or value), name, and locale. A chunk contains one document property.
  • IFilter::GetText, which gets a text-type property from a chunk.
  • IFilter::GetValue, which gets a value-type property from a chunk.

The following figure graphically represents an example document. The external value-type property DocTitle (obtained using methods of the IPropertySetStorage and IPropertyStorage interfaces) and the internal value-type property Book (obtained as a result of a custom IFilter implementation) describe the document as a whole. The text-type properties Contents and Chapter describe the content of the document. When processing this document, the IFilter implementation identifies and extracts these properties.


Property Indexing

This section describes what happens to document properties as they are indexed after being filtered from a document. The topics include:

  • Indexing Text-Type and Value-Type Properties
  • Caching Value-Type Properties
  • Representing the Catalog Conceptually


Indexing Text-Type and Value-Type Properties

Indexing Service indexes all text-type properties using their associated, unformatted text. The unformatted text undergoes word breaking and noise-word removal before eventually being merged into the master index of the catalog. Text-type properties are entered as words in the index along with their name, so that queries for text selected by property name are possible.

Indexing Service indexes value-type properties according to their data type identifiers.

  • Properties with a textual data type are indexed identically to text-type properties. Textual data type identifiers are: VT_LPSTR, VT_LPWSTR, VT_BSTR, and combinations of these made by a logical OR operation with VT_VECTOR.
  • Properties with a nontextual data type are indexed similarly to text-type properties using the appropriate data type and the data value of the property. Nontextual data type identifiers include: VT_I4, VT_I8, VT_R8, VT_DATE, and others.


Caching Value-Type Properties

For either textual or nontextual value-type properties, Indexing Service can optionally store selected internal values in the property cache of the catalog for fast and efficient retrieval. If multiple instances of a value-type property occur for a document, the value in the cache is the last-encountered instance. External value-type properties are not stored in the property cache, but are accessed where they are natively stored.

The cached size of an internal value-type property is the number of bytes the value occupies in the property cache, and the storage level is either primary or secondary. As much of the information from primary and secondary caches is kept in memory as possible, to provide fast access. The primary cache has precedence for memory usage over the secondary cache, so typically the primary cache contains only a few, important, value-type properties. This means the values in the primary cache are usually memory-resident, and those in the secondary cache are memory-resident if there is enough storage available.


Representing the Catalog Conceptually

The result of indexing is a catalog that conceptually consists of a logical "table" of properties with the text or value and locale stored in columns of the table. A text-type property entry also has a location in the document stored with the text and locale. Each row of the table corresponds to a separate document in the scope of the catalog. The following table shows how the results for the example document from the topic Property Filtering would appear as a row in the table. (The following table does not show columns for the locale or the location in the document.)

Document Name | Contents | Chapter | … | DocTitle | Book | …
 | Text-Type Properties |  |  | Value-Type Properties
… | … | … | … | … | … | …
stormy.xyz | detective exclaimed fini minutes room silent small … | A Scream Confessions The Knife … | … | Stormy Night | Stormy Night | …
… | … | … | … | … | … | …

It is important to note that entries for the value-type properties are single-valued and correspond to the last-set value of each property. Entries in the text-type properties can be, and usually are, multivalued. Note that in this context, vectors and arrays (data types VT_VECTOR and VT_ARRAY) are considered to be single-valued quantities.


Property Querying

Once the document properties are filtered and indexed, they are available for querying. The type of query operations that Indexing Service can perform on a specified property depends on the type of the property.

  • If the property is a text-type property, the only type of queries possible are content searches for the property.
  • If the property is a value-type property, queries can retrieve, relationally manipulate, and sort the property as well as perform content searches for it.

(Conceptually, these capabilities exist because there are single-valued entries for the value-type properties in the "table" for the catalog, but there can be — and usually are — multivalued entries for the text-type properties.)

The following table gives several examples of query types and the types of properties that each can use.

Query Type Example Property Types
Content search

(Short form)

(WHERE clause)

@Chapter "Confessions"
  WHERE CONTAINS(Chapter,"Confessions")
Text and value types
Retrieval

(SELECT statement)

SELECT DocTitle
  FROM SCOPE()
  WHERE CONTAINS(Chapter,"Confessions")
Value type
Relational

(WHERE clause)

SELECT DocTitle
  FROM SCOPE()
  WHERE Book = 'Stormy Night'
Value type
Sorted

(ORDER BY clause)

SELECT DocTitle, Book
  FROM SCOPE()
  WHERE CONTAINS(Chapter,"Confessions")
  ORDER BY DocTitle Book DESC
Value type


Components of Indexing Service

Indexing Service consists of several logical components that perform its managing, indexing, and querying tasks. Each of these logical components consists of one or more files, such as executable files (exe), dynamic-link libraries (DLL), or other file types.

An end user of Indexing Service usually accesses these components through the MMC or the Start, Search for Files, or Folder dialog box of Windows 2000. To see how an application or script accesses these components, see Combinations of Tasks, Languages, and APIs.

The following topics describe the logical components and list the files that constitute each component in Indexing Service 3.0.

  • Administration Component
  • Change-Notification Component
  • Filtering Component
  • IFilter Component
  • Indexing Component
  • Localization Component
  • Querying Component
  • Retrieval Component
  • Scanning Component


Administration Component

The Administration component provides access to the indexing and filtering processes. Examples of administration include: adjusting parameters for performance or index size, managing catalogs and directories (to be indexed or not to be indexed), and adjusting querying parameters. The Administration component consists of the following files.

File Name | Description
ciadmin.dll | Indexing Service snap-in for the MMC.
ciodm.dll | Admin Helper automation objects (AdminIndexServer, CatAdm, ScopeAdm).
idq.dll | Internet Server Application Programming Interface (ISAPI) extensions for Indexing Service.


Change-Notification Component

The Change-Notification component informs Indexing Service when files have been altered (added, modified, deleted) to trigger indexing or re-indexing of the contents and values of changed files.

The Change-Notification component is part of the cisvc.exe file.


Filtering Component

The Filtering component coordinates filtering of files. Its output is called a word list. This component is called by the Indexing component.

The CiDaemon.exe file contains the Filtering component. One executing instance of CiDaemon.exe exists for each Indexing Service catalog.


IFilter Component

The IFilter component is an in-process COM server that extracts the text and values for a specific file type. The appropriate IFilter component for a file type is called by the Filtering component.

A customized IFilter component can be developed for almost any selected file type. The standard IFilter components supplied with Indexing Service include the following ones.

File Name | Description
mimefilt.dll | Filters Multipurpose Internet Mail Extension (MIME) files.
nlhtml.dll | Filters HTML 3.0 or earlier files.
offfilt.dll | Filters Microsoft Office files: Microsoft Word, Microsoft Excel, and Microsoft PowerPoint®.
query.dll | Filters plain text files (default filter) and binary files (null filter).


Indexing Component

The Indexing component calls the Filtering component to extract the text and values from files that need to be filtered. After additional processing, it merges the resulting word lists into an index that is saved to disk. Indexing Service eventually merges content information (the text within a file) into the master index and saves value information (properties internal to the file) in the property cache.

The cisvc.exe file contains the Indexing component.


Localization Component

The Localization component processes text strings in the context of a native language and locale for both the Indexing component and the Querying component. For indexing, text extracted from filters passes through word breakers to identify grammatical constructs. It also passes through noise word removal procedures before it is merged into the index. (In English, words such as "the" and "and" are removed; in French, words such as "la" and "et" are removed; and so forth). For querying, in addition to language-specific word breakers and noise word removal, words pass through a stemming process before the query command passes to the query resolution process. (In English, "swim" expands to include terms "swimming", "swam", "swum," and others).

The following files are part of the Localization component.

File Name | Description
chsbrkr.dll | Simplified Chinese language word breaker.
chtbrkr.dll | Traditional Chinese language word breaker.
infosoft.dll | U.S. and Western European languages word breaker.
korwbrkr.dll | Korean language word breaker.
msir2jp.dll | Japanese language word breaker.
noise.* | Noise-word lists; the extension determines the locale.
thaibrkr.dll | Thai language word breaker.


Querying Component

The Querying component takes a search string from a client composed in one of the supported query languages and, after appropriate processing, passes it to a query processor that searches the catalog to find matches.

The following files make up the Querying component.

File Name | Description
idq.dll | ISAPI extensions for Indexing Service.
ixsso.dll | Query Helper automation objects (Query, Utility).
msad*.dll | Microsoft ActiveX® Data Objects (ADOs).
ntquery.lib | OLE DB Helper functions.
query.dll | OLE DB Provider for Indexing Service.


Retrieval Component

The Retrieval component retrieves the query results and returns them to the client.

The Retrieval component consists of the following files.

File Name | Description
idq.dll | ISAPI extensions for Indexing Service.
ixsso.dll | Query Helper automation objects (Query, Utility).
ntquery.lib | OLE DB Helper functions.


Scanning Component

The Scanning component detects file modifications that trigger filtering of the files. If all indexed files exist on drives that support change notification in some way, scanning operations are only necessary the first time a catalog is created or during crash recovery. Otherwise, the Indexing component calls the Scanning component when the operating system has no way to flag change notifications.

The cisvc.exe file contains the Scanning component.


Processing in Indexing Service

When Indexing Service is fully active, a user or application can perform several types of tasks, including managing tasks, querying tasks, and indexing tasks. In particular, it is important to note that querying and indexing proceed concurrently using a common set of distributed documents and common catalogs.

The following diagram summarizes the flow of data among the concurrent querying and indexing tasks. (The diagram does not show possible managing tasks.)

In the diagram, rectangles represent sources and sinks of Indexing Service data, and ellipses represent Indexing Service processes or groups of processes. A shaded rectangle denotes a Windows data source or sink that Indexing Service uses. The solid lines indicate the flow of data in the direction of the arrows. The following topics describe the querying and indexing processes in greater detail.

  • Querying a Catalog of Indexed Documents
  • Indexing a Set of Distributed Documents


Querying a Catalog of Indexed Documents

Querying-related processing of Indexing Service receives a query in one of the supported query languages and then returns references from the selected catalog to documents that match the specified query. The catalog can reside on the local host computer performing the querying, or the catalog can reside on a remote computer. The following topics describe the querying in greater detail.

  • Querying and Managing
  • Optimizing and Processing Queries


Querying and Managing

Querying-related processing occurs when an application submits a request in one of the supported query languages. Queries execute based on several entries in the Windows registry. You can manage querying by adjusting the registry entries, selecting the catalogs and scopes, providing locale-specific word breakers and noise-word lists, and directly controlling the state of the Querying component.

The following diagram illustrates how the task of managing Indexing Service integrates with the querying process.

In the diagram, rectangles represent sources and sinks of Indexing Service data, and the ellipse represents a group of Indexing Service processes. A shaded rectangle denotes a Windows data source or sink that Indexing Service uses. The solid lines indicate the flow of data in the direction of the arrows. A dotted line indicates a control functionality between processes.

An end user of Indexing Service usually manages querying through the MMC. An application or script can programmatically manage querying using the methods and properties of the Indexing Service Admin Helper automation objects (AdminIndexServer, CatAdm, and ScopeAdm). These programming elements provide read-write access to Indexing Service Registry entries, provide properties and methods for manipulating catalogs and scopes, and provide methods for changing the state of the Querying component. Also, the ISAPI extensions for Indexing Service provide programmatic control of Indexing Service using Internet Data Administration (.ida) files.


Optimizing and Processing Queries

An end user, application, or script submits a query to Indexing Service using one of the Query Languages for Indexing Service. The Querying component first optimizes the query for fastest performance or for greatest hit recall, and then returns the resulting documents and locations for matches from the Indexing Service catalog.

The following diagram shows the querying process in detail.

In the diagram, rectangles represent sources and sinks of Indexing Service data, and an ellipse represents an Indexing Service process. The solid lines indicate the flow of data in the direction of the arrows. A rounded, dotted rectangle delineates an Indexing Service component — in this case, the Querying component, which optimizes and processes queries.

An end-user of Indexing Service can query Indexing Service using the Start, Search for Files, or Folder dialog box of Windows 2000. An application or script can programmatically query Indexing Service using the methods and properties of the Indexing Service Query Helper automation objects (Query and Utility) or the ActiveX Data Objects (ADO). These programming elements provide properties and methods for selecting catalogs and scopes, provide methods and properties for setting query parameters and query content, and provide methods for executing queries and retrieving the results. Also, the ISAPI extensions for Indexing Service provide programmatic querying of Indexing Service using Internet Data Query (.idq) files. Finally, an application can use the OLE DB Helper functions or the OLE DB Provider for Indexing Service interfaces to execute queries.


Indexing a Set of Distributed Documents

The indexing-related processing of Indexing Service takes one or more sets of distributed documents and produces indexed catalogs for those sets. The document sets can reside on the local host computer performing the indexing, or the documents can reside on a remote computer. The following topics describe the indexing in greater detail.

  • Indexing and Managing
  • Updating a Catalog
  • Filtering, Word Breaking, and Removing Noise Words
  • Merging Indexes


Indexing and Managing

Indexing is triggered by changes to documents in the set of distributed documents indexed by a catalog. Indexing proceeds based on several entries in the Windows registry. You can manage indexing by adjusting the registry entries, manipulating the catalogs, providing custom filters and locale-specific word breakers and noise-word lists, and directly controlling the state of the Indexing component.

The following diagram illustrates how the task of managing Indexing Service integrates with the indexing process.

In the diagram, rectangles represent sources and sinks of Indexing Service data, and the ellipse represents a group of Indexing Service processes. A shaded rectangle denotes a Windows data source or sink that Indexing Service uses. The solid lines indicate the flow of data in the direction of the arrows. A dotted line indicates a control functionality between processes.

An end-user of Indexing Service usually manages indexing using the MMC. An application or script can programmatically manage indexing using the methods and properties of the Indexing Service Admin Helper automation objects (AdminIndexServer, CatAdm, and ScopeAdm). These programming elements provide read-write access to Indexing Service Registry entries, provide properties and methods for manipulating catalogs and scopes, and provide methods for changing the state of Indexing Service. Also, the ISAPI extensions for Indexing Service provide programmatic control of Indexing Service using Internet Data Administration files.


Updating a Catalog

Indexing Service scans the directories and files in the scope of a catalog to produce an initial catalog. After an initial scan, either a change notification (on NTFS file system volumes) or a periodic scan produces a list of objects to scan in the change log of the catalog. The following diagram shows the catalog updating part of the indexing process in detail.

In the diagram, rectangles represent sources and sinks of Indexing Service data, and the ellipse represents a group of Indexing Service processes. The shaded rectangle denotes a Windows 2000 data source that Indexing Service uses. The solid lines indicate the flow of data in the direction of the arrows. A rounded, dotted rectangle delineates Indexing Service components — in this case, the Change Notification and Scanning components, which gather changed documents and construct a change log of documents to re-index.

An end-user of Indexing Service can manually start scans using the MMC. An application or script can programmatically start a scan using the methods and properties of the Indexing Service ScopeAdm automation object. (It is generally unnecessary to manually scan unless a filter, word breaker, or noise-word list has changed.)


Filtering, Word Breaking, and Removing Noise Words

The Indexing component of Indexing Service creates a Filtering component for each of its catalogs. The Filtering component takes documents that appear in its change log and filters them for text-type and value-type properties using the appropriate IFilter component. The Filtering component places internal value-type properties into the property cache and passes the text-type properties to the word breaker for the appropriate locale. The word breaker produces words and passes them to the noise-word removal process, which uses the noise-word list for the appropriate locale. Finally, the resulting words are placed into word lists along with the containing document name, word location, and locale.

The following diagram shows the document filtering part of the indexing process in detail.

In the diagram, rectangles represent sources and sinks of Indexing Service data, and the ellipses represent Indexing Service processes. The solid lines indicate the flow of data in the direction of the arrows. Dotted lines between processes indicate where components can be substituted. A rounded, dotted rectangle delineates Indexing Service components — in this case, the Indexing, Filtering, IFilter, and Localization components. The diagram shows how the customizable IFilter and Localization components affect the transformation of documents and their properties into word lists for the Indexing Service catalog.


Merging Indexes

The word lists in an Indexing Service catalog are temporary, memory-resident, lightly compressed, and quick to create (and recreate). Registry settings determine the maximum size of each word list and the maximum number of word lists for a catalog, because having a large amount of the catalog in the form of word lists uses a large amount of memory.

When the number of word lists exceeds the maximum allowable number, the Indexing component performs a shadow merge, which transforms word lists into shadow indexes, to reduce memory usage. Shadow indexes are persistent, disk-resident, and highly compressed. A special case of a shadow merge, the annealing merge, includes both existing shadow indexes and word lists in the merge process into shadow indexes. This reduces the number of shadow indexes and increases the efficiency of querying without having to perform a master merge.

Once a day, as determined by a registry setting, the Indexing component performs a master merge, which combines shadow indexes with the master index. The master index is persistent, disk-resident, highly compressed, and optimized for querying.

The following diagram shows the merging part of the indexing process in detail.

In the diagram, rectangles represent sources and sinks of Indexing Service data, and the ellipses represent Indexing Service processes. The solid lines indicate the flow of data in the direction of the arrows. A rounded, dotted rectangle delineates an Indexing Service component — in this case, the Indexing component. The diagram shows the progression of indexes from word lists to shadow indexes to the master index in the Indexing Service catalog. A special case of the shadow merge is an annealing merge. It includes both existing shadow indexes and word lists in a merge process into shadow indexes. This reduces the number of shadow indexes and increases the efficiency of querying without having to perform a master merge.

An end user of Indexing Service can manually start a master merge using the MMC.


Programming for Indexing Service

Programming for Indexing Service involves a flexible and diverse combination of languages, APIs, and tools for performing Indexing Service tasks. This section summarizes the available languages, APIs, and tools and describes the various combinations that apply to categories of tasks. It also summarizes the sample applications in the Platform SDK that illustrate the combinations of task, languages, APIs, and tools. This section includes:

  • Summary of Tasks, Languages, APIs, and Tools
  • Combinations of Tasks, Languages, and APIs
  • Samples by Task, Language, API, and Tool


Summary of Tasks, Languages, APIs, and Tools

The number of possible combinations of Indexing Service tasks, languages, APIs, and tools is large. Before trying to describe the combinations and the samples that illustrate them, it's best to first consider the components. The topics in this section summarize:

  • Programming Tasks
  • Programming Languages
  • Programming APIs
  • Programming Tools


Programming Tasks

When you program for Indexing Service, the tasks you want to accomplish fall into three general categories: managing, querying, and indexing. The following table lists these types of tasks and gives a brief description of each.

Task Type | Description
Managing | Includes retrieving and setting the Indexing Service catalogs and their scopes, retrieving and setting entries in the Windows® registry, and determining and controlling the state of Indexing Service activity.
Querying | Includes constructing, submitting, and presenting a query in one of the Indexing Service query languages to a specified Indexing Service catalog and retrieving the results.
Indexing (Filtering) | Includes developing IFilter implementations for custom file types and selecting features of standard filter implementations.


Programming Languages

You can use a broad variety of programming languages when programming an Indexing Service task. Each language typically has more than one API to interface it to Indexing Service. The following table lists the Microsoft® languages available and gives a brief description of each.

Language | Description
Visual Basic® | A programming language available in Microsoft Visual Studio®. For more information, see http://msdn.microsoft.com/vbasic/.
Visual Basic Scripting Edition (VBScript) | An interpreted subset of the Visual Basic programming language used in Web browsers and other scripting applications. For more information, see http://msdn.microsoft.com/scripting/vbscript/.
Visual J++® | Microsoft's implementation of the Java language for building Windows applications. For additional information, see http://msdn.microsoft.com/visualj/.
JScript® | Microsoft's implementation of the European Computer Manufacturers Association (ECMA) 262 language specification. An interpreted, object-oriented programming language, JScript can access many object models and object libraries. For additional information, see http://msdn.microsoft.com/scripting/jscript/.
Visual C++® | Microsoft's implementation of the C++ language for building high-performance Windows applications. For additional information, see http://msdn.microsoft.com/visualc/.
IDA+HTX, IDQ+HTX | Used with HTML, the Internet Data Administration (IDA) and Internet Data Query (IDQ) files specify administrative tasks and query tasks, respectively. HTML extension (HTX) files format the results.


Programming APIs

Each programming language has several APIs that communicate with Indexing Service, and you can choose the API most suitable for a task. When you choose an API, you can balance programming complexity with application performance. In general, the OLE DB Provider API is the most difficult API to program, but it is the most flexible and executes fastest. APIs that encapsulate the OLE DB Provider (such as Admin Helper or Query Helper) are easier to program, but they are less flexible and slower in execution. If you have a choice, consider this tradeoff when selecting an API.

The following table lists the APIs available for performing Indexing Service tasks and gives a brief description of each.

API | Description
OLE DB Provider | The lowest-level API for querying with Indexing Service. It specializes the COM interfaces of standard Microsoft OLE DB to access Indexing Service data. It's the highest performance, but most complex, API and is usually used with C++ programs.
OLE DB Helper | A high-level API for querying and filtering with Indexing Service. It provides a functional interface for accessing Indexing Service data, primarily from C++ language programs.
ActiveX® Data Objects (ADO) | An intermediate-level API for querying Indexing Service. It provides an automation layer between the OLE DB Provider and automation languages for accessing Indexing Service data.
Admin Helper | A high-level API for managing Indexing Service. It provides an object-based interface to Indexing Service from automation languages.
Query Helper | A high-level API for querying Indexing Service. It provides an object-based interface for accessing Indexing Service data from automation languages.
ISAPI Extensions | An intermediate-level, high-performance API extension to the Internet Server Applications Programming Interface (ISAPI). It provides access for managing and querying Indexing Service from Internet Information Services (IIS) applications. For information about ISAPI extensions, see the Programmer's Guide in the Internet Information Services SDK.
IFilter Component | A low-level, customizable COM interface, usually written in C++, for extracting text and values from documents.


Programming Tools

The phrase "programming tool" refers here to a variety of objects. It can be a development environment (such as Visual Studio) that produces an executable Indexing Service application. Or, it can be an execution environment (like Microsoft Internet Explorer or Windows Script Host) that hosts Indexing Service scripts. It can even be a complete Windows 2000 service (such as IIS) that provides an integrated Web server environment for Indexing Service.

The following table lists the major tools available for performing Indexing Service tasks and gives a brief description of each.

Tool | Description
Internet Information Services (IIS) | A Windows NT/Windows 2000 service that provides a programming environment and foundation for hosting Internet and Web applications, including Active Server Pages (ASP), and ISAPI applications. For additional information, see http://www.microsoft.com/windows/server/Overview/features/web.asp.
Internet Explorer | A Web browser that provides features such as dynamic HTML (DHTML) and ActiveX scripting engines to support Web application development. For additional information, see http://www.microsoft.com/windows/IE/.
Windows Script Host | A language-independent execution environment that hosts scripting engines for languages such as VBScript and JScript. For additional information, see http://msdn.microsoft.com/scripting/windowshost/.
Visual Studio | An integrated development environment (IDE) that provides a suite of compilers, linkers, libraries, and other components for Windows application development. For additional information, see http://msdn.microsoft.com/vstudio/.


Combinations of Tasks, Languages, and APIs

Many combinations of languages, APIs, and tools are available for programming Indexing Service to achieve your desired tasks. The combination you choose depends on many factors, including your orientation (file system or Web server), programming background (application developer or script writer and language), desired performance, and task category.

The following diagram shows possible combinations of tasks, languages, and APIs and indicates their relationships with Indexing Service and COM components. The diagram does not include tools, because it is sometimes possible to use several tools for some of the combinations shown. For a description of the tools, see Programming Tools.

The dotted lines divide the diagram into three regions that represent the task categories of managing, querying, and indexing. Each box in the diagram denotes a language, API, or component. The color (or shading) key for the boxes is the following.

  • White (unshaded) boxes represent components of Indexing Service or COM. For a description of the Indexing Service components, see Components of Indexing Service.
  • Yellow (lightly shaded) boxes represent languages. For a description of the programming languages, see Programming Languages.
  • Blue (intermediately shaded) boxes represent APIs. For a description of the APIs, see Programming APIs.
  • Green (darkly shaded) boxes represent an API that is customized using one of the languages — most likely Visual C++®.

The arrows in the diagram indicate calling or usage relationships between the languages, APIs, and components.


Samples by Task, Language, API, and Tool

The Platform SDK includes several samples of programming for Indexing Service. This section summarizes those samples organized by task, language, API, and tool. The following topics list the included samples by task category.

  • Managing Samples
  • Querying Samples
  • Indexing Samples

For an alphabetical summary of the samples with brief descriptions, see Installing the Samples.


Managing Samples

The following samples are examples of managing Indexing Service. The table gives the name of the sample and the tool, language, and API that the sample illustrates. Selecting the name of a sample takes you to a detailed reference for that sample.

Name | Tool | Language | API
ChgState | Visual Studio | Visual C++ | OLE DB Helper
IISAdmin | IIS | VBScript, JScript, IDA+HTX | Admin Helper, ISAPI Extensions
SQuery | Windows Script Host | VBScript, JScript | Admin Helper
VBAdmin | Visual Studio | Visual Basic | Admin Helper


Querying Samples

The following samples are examples of querying Indexing Service. The table gives the name of the sample and the tool, language, and API that the sample illustrates. Selecting the name of a sample takes you to a detailed reference for that sample.

Name | Tool | Language | API
AdvQuery | Visual Studio | Visual C++ | OLE DB Provider
CatQ | Visual Studio | Visual C++ | OLE DB Provider
DHtml (CiDhtml) | IE+DHTML | VBScript | Query Helper
IISSearch | IIS | VBScript, JScript, IDQ+HTX | ADO, Query Helper, ISAPI Extensions
Simple (QSample) | Visual Studio | Visual C++ | OLE DB Helper
SQuery | Windows Script Host | VBScript, JScript | ADO, Query Helper
VBQuery | Visual Studio | Visual Basic | ADO, Query Helper
VJQuery | Visual Studio | Visual J++ | ADO


Indexing Samples

The following samples are examples of indexing (the filtering component) with Indexing Service. The table gives the name of the sample and the tool, language, and API that the sample illustrates. Selecting the name of a sample takes you to a detailed reference for that sample.

Name | Tool | Language | API
HtmlProp | Visual Studio | Visual C++ | IFilter Component
IFilter (HtmlFilt) | Visual Studio | Visual C++ | IFilter Component
SmpFilt | Visual Studio | Visual C++ | IFilter Component


Query Languages for Indexing Service

Indexing Service supports two types of query languages: the Indexing Service query language and the SQL query language. An application or script that uses the appropriate application programming interface (API) can use either type of query language to submit the queries to Indexing Service. (The choice of API depends on several factors; see Programming APIs for a brief discussion.) The following table summarizes the correspondence between query languages and the APIs that support them.

Query Language | Supporting APIs
Indexing Service Query Language | ISAPI Extensions, OLE DB Helper, Query Helper
SQL Query Language | ActiveX Data Objects, OLE DB Provider

This section describes the Indexing Service query language and its dialects. It also describes the SQL language and its extensions. The topics include the following.

  • Indexing Service Query Language is a special language created for Indexing Service, first as Dialect 1 for Index Server 1.0, and now as Dialect 2, an extensible query language introduced with Indexing Service 3.0.
  • SQL Query Language is standard SQL with several extensions. It has been available for submitting queries from applications and scripts since Index Server 2.0.
  • Example Queries presents a few examples of queries that compare the two Indexing Service query language dialects and the SQL language.

For a reference to the syntaxes of Dialects 1 and 2 and the SQL language, see Query Language Syntax.


Indexing Service Query Language

New in Indexing Service 3.0 is the extensible Dialect 2 of the Indexing Service query language. Its short form contains as a subset — with a few incompatibilities — the syntax of the original Indexing Service query language, now called Dialect 1. Except for the few incompatibilities, Dialect 2 processes queries written in both its long form and its short form (Dialect 1 subset). Most applications and scripts will specify Indexing Service query language queries in Dialect 2. For compatibility with earlier releases, applications and scripts can submit a query written in Dialect 1 and specify that Indexing Service process it as a Dialect 1 query. An alternative to the Indexing Service query language is the SQL query language.

This section describes several features of the Indexing Service query language. It consists of the following topics.

  • Query Submittal for Indexing Service Query Language
  • Query Syntax of Indexing Service Query Language
  • Content Queries
  • CONTAINS Operator
  • Boolean and Proximity Operators
  • Property-Value Queries
  • Relational Queries
  • Pattern-Matching Queries
  • Term Weighting
  • Vector-Space Queries
  • Incompatibilities of Dialect 2 with Dialect 1

For a reference to the Indexing Service query language, see Query-Language Dialects.


Query Submittal for Indexing Service Query Language

To use the Indexing Service query language, either Dialect 1 or Dialect 2, an application or script must use one of three APIs to submit a query. In general, these APIs feature ease of programming rather than flexibility or the fastest execution. The following table lists the APIs and summarizes how to select the dialect.

API | Select Dialect By
ISAPI Extensions | Specifying a value of the CiDialect variable in the .idq file.
OLE DB Helper | Specifying a value from the ISQLANG_* constants for the ulDialect parameter of a CITextToFullTreeEx or CITextToSelectTreeEx function call that constructs a query.
Query Helper | Specifying an appropriate value for the Query.Dialect property of a query.

For information about which languages and tools you can use with these APIs, see Combinations of Tasks, Languages, and APIs. For additional information about using these APIs to submit queries and for examples, see Using Indexing Service with File Systems and Using Indexing Service with Web Servers.


Query Syntax of Indexing Service Query Language

This section describes the main features of Dialect 2 of the Indexing Service query language — similar to Standard Generalized Markup Language (SGML) — and its long- and short-form expressions and its default values and modes. It also describes the two broad types of queries — content and property-value queries — and how to specify property names. For a reference to the complete Dialect 2 syntax, see Syntax of Query Language Dialect 2. This section includes the following topics.

  • SGML-Style Syntax
  • Long Form, Short Form, and Defaults
  • Content and Property-Value Queries
  • Property-Name Syntax


SGML-Style Syntax

Dialect 2 introduces an SGML-style syntax that employs tags to interpret query terms and modify query operators. The query tags, indicated by braces (the "{" and "}" symbols), are used to open and close query expressions. In many cases, a query expression can have an implied closing tag. The query tags can also include attributes to define additional variations of the tag. This permits easy construction of complex queries.

The general syntax of a query tag is the following.

{query-tag attribute1=value1, attribute2=value2, ...} query expression {/query-tag}

The syntax is similar to that of SGML, except that Dialect 2 uses braces instead of angle brackets (the latter are the "<" and ">" symbols) to delineate tags. This prevents confusion of tags with the relational operators "less than" and "greater than".


Long Form, Short Form, and Defaults

Dialect 2 supports queries in long form and short form, providing ease of expression and smooth transition from complex to simple queries. The long-form expression, which uses the full SGML-style syntax, supports all query-language features and is extensible for future syntax additions. The short-form expression, which is Dialect 1 with a few exceptions, handles the most common query cases. The short form does not support all query features and usually is not extensible. For information about incompatibilities of Dialect 2 with Dialect 1, see Incompatibilities of Dialect 2 with Dialect 1.

Dialect 2 also provides default values and modes for the query language elements. The defaults promote ease of use and provide solutions to common query scenarios. This includes, for example, using free-text queries as the default mode in Dialect 2. For other differences in Dialect 2 and Dialect 1, see Incompatibilities of Dialect 2 with Dialect 1.


Content and Property-Value Queries

Indexing Service considers a document to be an assemblage of properties, which are either text-type or value-type. (See Property Types for a description of the types of properties.) Most queries of text-type properties involve the Contents property, so these queries are often called "content queries." Queries of value-type properties are similarly often called "property-value queries."

Queries involving text-type properties or textual value-type properties are limited in comparison to queries of nontextual value-type properties. For example, queries can contain Boolean operators when they involve either type of property, but queries can contain relational operators only when they involve value-type properties. (See Property Querying for a description of properties and queries.)


Property-Name Syntax

The long form of Dialect 2 expresses property names using the {prop} tag. The general syntax for a property name is the following.

{prop name = property_name} [{/prop}]

For completeness, the optional closing tag {/prop} is supported. This tag can be used for clarity when specifying relational operators with properties. Property names are case-insensitive, and if property_name consists of more than one word, the words must be quoted. The short form uses the "@" character as a prefix to indicate the property name.

The following table summarizes property names and their long and short forms.

Long Form | Short Form
{prop name = property_name} [{/prop}] | @property_name

The Contents property, @Contents in short form, is a special case. This property refers to the contents of the text-type property of a document. When a query doesn't specify a property name, @Contents is assumed.

Properties available for all documents include the following.

Property Name | Description
All | Matches words, phrases, and any property.
Contents | Words and phrases in the document.
Filename | Name of the document.
Size | Document size.
Write | Last time the document was modified.

A query can also use Microsoft® ActiveX® property values. Documents created by most ActiveX-aware applications can be queried for the following properties.

Property Name | Description
DocTitle | Title of the document.
DocSubject | Subject of the document.
DocAuthor | Author of the document.
DocKeywords | Keywords for the document.
DocComments | Comments about the document.

There is also a list of additional standard Indexing Service properties that are available in queries. For the list, see Default Property Names for a Web Catalog.

The following table illustrates several property names in both long and short form.

Long Form | Short Form
{prop name = filename} | @filename
{prop name = "shoe size" | @"shoe size"
{prop name = contents} | @contents
{prop name = all} | @all


Content Queries

Content queries search text-type properties of documents. Content queries process the textual content of a sequence of words in one of two ways. A series of words such as "Web server administrator" can be treated as a phrase, where the proximity of words and the word order is significant (no intervening words, and words must appear in a specific order). Alternatively, the words can be treated independently, ignoring the order and proximity of the words.

To handle both cases, phrase and non-phrase (free-text) interpretation of textual content, Dialect 2 has two modes for content queries: phrase and freetext. It uses the two following text interpretation tags.

{phrase} text {/phrase}
{freetext} text {/freetext}

The {phrase} tag specifies the use of the phrase mode, and the text within the tags is considered to be a single entity. The search engine treats the word sequence and position as significant. The {freetext} tag specifies the use of free-text mode, where the word sequence and position are insignificant, and which includes word stemming. The {phrase} and {freetext} tags are mutually exclusive and cannot be embedded or nested. The default mode of Dialect 2, if no tag is used, is free-text mode. (In Dialect 1, the default mode is phrase mode.) To indicate free-text mode in the short form, either leave off any enclosing quote marks around the text or use the dollar sign ($) with the Contents property.

The following table summarizes the text modes and their long and short forms.

Text Mode | Long Form | Short Form
phrase | {phrase} text {/phrase} | " text "
freetext | {freetext} text {/freetext} | text —Or— $contents text

The following table illustrates examples of the use of text modes in content queries.

To Search For | Example | Results
Documents that match a phrase. | {phrase} big red truck {/phrase} —Or— "big red truck" | Documents that contain the phrase big red truck.
Documents that match terms. | {freetext} Why is the sky blue? {/freetext} —Or— Why is the sky blue? —Or— $contents Why is the sky blue? | Documents about the blue sky, ranked by estimated relevance.

Note In Dialect 2, the query

@contents Why is the sky blue?

without quotes around the text is a phrase-mode query equivalent to

@contents "Why is the sky blue?"


CONTAINS Operator

The CONTAINS operator indicates a search for any of the specified words or phrases within a particular property. If no operator is specified, the CONTAINS operator is assumed. The CONTAINS operator contrasts with the relational operator "equals to" (=), which requires a match of the specified words or phrases and only those words or phrases. The CONTAINS operator is available only in its English spelling.

The following examples illustrate the use of the CONTAINS operator.

To Search For | Example | Results
Documents that contain any of the terms. | {prop name=Contents} Contains {freetext} big red truck {/freetext} —Or— $Contents contains big red truck —Or— $Contents big red truck | Documents whose contents property contains the terms big, red, or truck.
Documents that contain a phrase. | {prop name=All} Contains {phrase} big red truck {/phrase}{/prop} —Or— @All contains "big red truck" —Or— @All "big red truck" | Documents with any property that contains the phrase big red truck.


Boolean and Proximity Operators

Boolean and proximity operators combine terms in a query to produce a restricted query result. This section describes the following topics.

  • Boolean Operators
  • Proximity Operator
  • Order of Precedence Rules
  • Other Usage Rules
  • Examples of Operator Use


Boolean Operators

The standard Boolean operators, AND, OR, and NOT, can be used in both content and property-value queries. The NOT operator is supported in an AND NOT operation as the full form of the NOT operator. Unary NOT is supported as an operator for value-type property queries (for example, ! @size > 100). In addition, the Boolean operators can be replaced by symbols. The Boolean operators and their associated full forms and symbols are the following.

Operator | Full form | Symbol | Notes
AND | AND | & | Only the English spelling of the long form is available in Dialect 2.
OR | OR | | | Only the English spelling of the long form is available in Dialect 2.
NOT (binary) | AND NOT | &! | Only the English spelling of the long form is available in Dialect 2.
NOT (unary) | NOT | ! | Unary NOT for value-type property queries. Only the English spelling of the long form is available in Dialect 2.

In Dialect 1, the Boolean operators are localized for several non-English languages. See Incompatibilities of Dialect 2 with Dialect 1 for complete details.


Proximity Operator

The proximity operator is available in content queries for searching with proximity thresholds (for example, within 40 words of another term, or within the same sentence or paragraph). The proximity operator works as a weighted AND query, where the rank of the match increases as the terms appear "closer" together in the content stream. The proximity operator and its long form and short form are the following.

Operator | Long form | Short form | Notes
NEAR | {NEAR dist = dist_value, unit = unit_value} | Near, ~ | Only the English spelling of the long form is available in Dialect 2.

In Dialect 1, the proximity operator is localized for several non-English languages. See Incompatibilities of Dialect 2 with Dialect 1 for complete details.

The dist_value of the dist attribute specifies the threshold count of units to use between text clauses. The text clauses must appear within each other's specified counted units. If dist = 0 is specified, the text clauses must all occur within the particular unit.

The unit_value of the unit attribute specifies the distance unit to use. The following table gives the valid values of the unit attribute.

Value | Description
Word | word
Sent | sentence
Par | paragraph
Chap | chapter

If dist = 0 and unit = sent, then the text clause must appear in the same sentence. If unit = word, then dist = 0 is illegal.

Note Indexing Service 3.0 only supports the NEAR operator with dist <= 50 and unit=word. Indexing Service 3.0 does not support same sentence, same paragraph, or same chapter searching. Nor does it support any value for unit other than word.

The short-form version of the NEAR operator assumes the default value of 50 for dist and assumes that the unit is word. The following examples are equivalent in Indexing Service.

Dog ~ Cat
Dog near Cat
Dog {near dist = 50, unit = word} Cat


Order of Precedence Rules

The Boolean and proximity operators follow conventional precedence rules. The order of precedence is the following.

  1. NOT
  2. AND and NEAR
  3. OR

The proximity operator has the same precedence as AND. After precedence rules are applied, operators are processed left to right. You can add parentheses to nest expressions within a query to explicitly specify the precedence. Expressions within parentheses are evaluated first.


Other Usage Rules

The following rules also apply to the use of the Boolean and proximity operators.

  • Use double quotes (") to indicate that a Boolean or proximity operator keyword should be ignored in your query. For example, "Jack and Jill" will match documents with that exact phrase, not documents that match the Boolean expression. (In addition to being an operator, the word and is a noise word in English.)
  • The NEAR operator is similar to the AND operator in that NEAR returns a match if both words being sought are in the same document. However, the NEAR operator differs from AND because the rank assigned by NEAR depends on the proximity of words. That is, the rank of a document in which the sought words are closer together is higher than or equal to the rank of a document in which the words are farther apart. If these words are more than 50 words apart, they are not considered near enough to be related, and the document is assigned a rank of zero.
  • The NOT operator can be used only after an AND operator in content (text-type) queries; it can be used only to exclude documents that match a previous content restriction. For value-type property queries, the NOT operator can be used apart from the AND operator.
  • The symbols (&, |, !, ~) and the English keywords AND, OR, NOT, and NEAR work the same way in all languages supported by Indexing Service.
  • The NEAR operator can be applied only to words or phrases.


Examples of Operator Use

The following examples illustrate the use of the Boolean and proximity operators.

To Search For | Example | Results
Both terms in the same document. | red AND dog —Or— red & dog | Documents with both the words red and dog.
Either term in a document. | red OR dog —Or— red | dog | Documents with either of the words red or dog.
The first term without the second term. | red AND NOT dog —Or— red & ! dog | Documents with the word red but not dog.
Several terms in the same document, close together. | red {NEAR dist = 50, unit = word} dog {NEAR dist = 50, unit = word} cat —Or— red NEAR dog NEAR cat —Or— (red ~ dog) ~ cat | Documents with the word red near the word dog and that combination near the word cat.
Several terms in the same document, but not others close together. | (red OR dog) AND NOT (black {NEAR dist = 50, unit = word} cat) —Or— (red OR dog) AND NOT (black NEAR cat) —Or— (red | dog) &! (black ~ cat) | Documents with the word red or the word dog, but not the word black near the word cat.
Documents not matching a value-type property. | NOT @size = 100 —Or— ! @size = 100 | Documents that are not 100 bytes.


Property-Value Queries

Property-value queries find documents with value-type properties that match a given criterion. The properties for which you can query include basic document information (such as file name and file size), as well as Microsoft ActiveX® properties (such as the document summary stored in documents created by ActiveX-aware applications). For information about property names, see Property-Name Syntax.

Indexing Service provides two types of property-value queries: relational queries and pattern-matching queries. It also provides vector-space queries for querying with a (possibly complex) list of properties.

The following general rules apply to the syntax of property-value queries.

  • Date and time values are of the form yyyy/mm/dd hh:mm:ss or yyyy-mm-dd hh:mm:ss. The first two characters of the year and the entire time can be omitted. If you omit the first two characters of the year, then 29 or less is interpreted as a year between 2000 and 2029, and 30 or greater is interpreted as between the years 1930 and 1999. All dates and times are in Coordinated Universal Time (UTC).
  • Dates and times relative to the current time can be expressed by using a hyphen as a minus sign (-), followed by zero or by more integer-unit and time-unit pairs. Time units are expressed as: (y) for years, (m) for months, (w) for weeks, (d) for days, (h) for hours, (n) for minutes, and (s) for seconds. A three-digit millisecond value can be optionally specified after the seconds value in date expressions, for example, 1997/12/8 10:10:03:452.
  • Currency values are of the form x.y, where x is the whole value amount and y is the fractional amount. There is no assumption about units.
  • Boolean values are (t) or (true) for TRUE and (f) or (false) for FALSE.
  • Vector properties (of type VT_VECTOR) are expressed as an opening parenthesis "(", followed by a semicolon-separated list of values, then a closing parenthesis ")".
  • Single-value expressions that are compared against vectors are expressed as a relational operator, then an AllOf operator (^a) for all of or a SomeOf operator (^s) for some of.
  • Numeric values can be in decimal or hexadecimal (preceded by 0x) form.
  • The contents property does not support relational operators. If a relational operator is specified, no results will be found. For example in short form, @contents Microsoft will find documents containing Microsoft, but @contents=Microsoft will find none. However, @title=vector space returns results only if the entire title is vector space. If you leave out the equal sign, @title vector space returns results even if vector space is only a phrase in a longer title.
  • In the short form, use the number sign (#) before the property name when using a regular expression in a property value, and an at sign (@) otherwise. The equal to relational operator (=) is assumed for regular-expression queries.
  • The Filename property (#filename) is the only property that efficiently supports regular expressions with wildcard characters to the left of text.


Relational Queries

Relational queries are property-value queries that use relational and bitwise-comparison operators to compare the values of value-type properties to specified values. Under the following topics, this section describes the use of relational queries.

  • Relational Operators
  • Relational Queries with Vector Properties
  • Bitwise-Comparison Operators
  • Examples of Relational Queries


Relational Operators

Relational operators provide a means of selecting documents with values of a value-type property restricted to a specified interval. The following table lists the standard relational operators.

Operator | Description
< | less than
<= | less than or equal to
= | equal to
>= | greater than or equal to
> | greater than
!= | not equal to

The following table gives some simple relational queries.

Long Form | Short Form
{prop name = shoesize} >= 6 {/prop} | @shoesize >= 6
{prop name = createdate} >= -1d6 {/prop} | @CreateDate > -1d
{prop name = DocAuthor} = "David" | @DocAuthor = "David"


Relational Queries with Vector Properties

A vector property has more than one element, each with a value. When used with vector properties, the relational operators are applied to corresponding vector elements in turn, left to right. A complete test passes if all the individual element tests pass.

Consider the two vector properties, A and B, with the following elements: A (a1; a2; a3) and B (b1; b2; b3). With these elements, A > B if, and only if, a1 > b1 AND a2 > b2 AND a3 > b3.

If one vector has more elements than the other, the test is only applied against the matching elements and the extra elements are ignored.

A series of relational comparisons connected by other operators apply to the most recently specified property. The following two queries are equivalent.

@shoesize > 6 AND < 10
@shoesize > 6 AND @shoesize < 10

To perform a relational query with the long-form property tag, a {/prop} can be (optionally) used to complete the clause and to improve readability. The following query is a valid property restriction.

{prop name = shoesize} > 6 & < 10{/prop}

The {/prop} construct is used to separate property clauses but it can usually be omitted, because a new property specification (either long or short) implies closure of the previous clause. It is also assumed that there is a "super" closure at the end of the query expression to close all property tags.


Bitwise-Comparison Operators

Bitwise-comparison operators are also available in addition to the traditional relational operators. The AllOf (^a) and SomeOf (^s) operators allow property values to be compared against bit pattern on a bit-by-bit basis. The following table gives an example of each bitwise-comparison operator.

Operator | Example | Note
^a | @attrib^a 0x820 | Specifies compressed documents that have the archive bit attribute on.
^s | @attrib^s 0x20 | Specifies any documents that have the archived bit set on.

The AllOf and SomeOf operators can be used in conjunction with the relational operators when performing vector property comparisons. When using the ^a operator, every vector element on the left side must pass the comparison against every vector element on the right side. When using the ^s operator, at least one of the vector elements must match the comparison for the test to pass.

The following table illustrates what happens with the comparison of two vectors with different numbers of elements.

Test | Result | Note
(1; 2; 3)^a>(1; 2) | FAILS | (1; 2; 3)>(1; 2) normally passes. However, when ^a is specified, the test fails since the first element on the left side is less than the second element on the right side.
(1; 2; 3)^s>(2; 1) | PASSES | (1; 2; 3)>(2; 1) normally fails. However, when ^s is specified, the test passes because the third element on the left side is greater than the first element on the right side.


Examples of Relational Queries

The following examples illustrate the use of the relational and bitwise-comparison operators.

To Search For | Example | Results
Property values in relation to a specified value. | {prop name = size} < 100 —Or— @size < 100 | Documents whose size matches the relational restriction. Any of the five other relational operators can replace the < operator.
Property values with all of a set of bits on. | {prop name = attrib} ^a 0x820 —Or— @attrib ^a 0x820 | Compressed documents with the archive bit on.
Property values with some of a set of bits on. | {prop name = attrib} ^s 0x20 —Or— @attrib ^s 0x20 | Documents with the archive bit on.


Pattern-Matching Queries

Pattern-matching queries are property-value queries that use UNIX-style regular expressions, MS-DOS®/Windows® wildcard characters, or alternate word forms to compare the values of value-type properties to specified patterns. The topics in this section describes the pattern-matching syntax used in Dialect 2.

  • UNIX-Style Regular Expressions
  • MS-DOS/Windows Wildcard Characters
  • Alternate Word Forms


UNIX-Style Regular Expressions

The {regex} tag specifies a match using UNIX-style regular expressions. The syntax of the {regex} tag is the following.

{regex} regular expression {/regex}

Any character except an asterisk (*), period (.), question mark (?) or vertical bar (|) matches itself. A regular expression can be enclosed in matching quotes ("…"), and must be enclosed in quotes if it contains a space or closing parenthesis (the ")" character ).

The asterisk, period, and question mark behave as they do in Windows. The asterisk matches any number of characters. The period matches end of string. The question mark matches any one character. The vertical bar (|) is an escape character, which indicates special behavior for the open bracket character ([). The following table explains the meanings of special characters in regular expressions.

Character | Meaning
( | An opening parenthesis opens a group. It must be followed by a matching closing parenthesis.
) | A closing parenthesis closes a group. It must be preceded by a matching opening parenthesis.
| [ | An opening square bracket preceded (escaped) by a vertical pipe character opens a character class. It must be followed by a matching (unescaped) closing square bracket.
{ | An opening brace opens a counted match. It must be followed by a matching closing brace.
} | A closing brace closes a counted match. It must be preceded by a matching opening brace.
, | A comma separates OR clauses.
* | An asterisk matches zero or more occurrences of the preceding expression.
? | A question mark matches zero or one occurrence of the preceding expression.
+ | A plus sign matches one or more occurrences of the preceding expression.
Other | All other characters match themselves.

The following table describes characters which, when located between square brackets ([ ]), have special meanings.

Character | Meaning
^ | A caret matches everything but following classes. ( It must be the first character in the string.)
] | A closing square bracket matches another closing square bracket. It may be preceded only by a caret (^); otherwise it closes the class.
- | A hyphen is a range operator. It is preceded and followed by normal characters.
Other | All other characters match themselves (or begin or end a range).

The following table describes the syntax used between braces ({ }).

Character | Meaning
{m} | Matches exactly m occurrences of the preceding expression (0 < m < 256).
{m,} | Matches at least m occurrences of the preceding expression (1 < m < 256).
{m, n} | Matches between m and n occurrences of the preceding expression, inclusive (0 < m < 256, 0 < n < 256)

To match the asterisk and question mark, enclose them within brackets. For example, [*]sample matches "*sample". The following table illustrates some additional examples of pattern-matching queries.

To Search For | Example | Results
Documents with extensions that match several patterns. | {prop name=filename} {regex} *.|(do?|,xl?|,p?t|,mdb|) {/regex} —Or— #filename *.|(do?|,xl?|,p?t|,mdb|) | Microsoft Office documents, including files with extensions "doc", "dot", "xla", "xls", "xlt", "pot", "ppt", and "mdb".
Paths with long names. | {prop name=path} {regex} "*\|[^\]|{14,|}\*" {/regex} —Or— #path "*\|[^\]|{14,|}\*" | Paths with a directory component containing 14 or more characters.


MS-DOS/Windows Wildcard Characters

The asterisk (*) and question mark (?) are used as wildcard characters, as they are in MS-DOS and Windows. The asterisk matches any sequence of characters, whereas the question mark matches any single character. In its long form, Dialect 2 uses the {regex} tag with the asterisk or the question mark to specify the wildcard characters. In its short form, Dialect 2 uses the equal sign (=) to indicate that wildcard characters are used. Essentially, "=" turns on the MS-DOS/Windows wildcard character mode. If no equal sign is used, a CONTAINS operator is assumed.

To Search For | Example | Results
Documents with any number of characters in the name. | {prop name=filename} {regex} *.doc {/regex}{/prop} —Or— #filename = *.doc | Documents with any name and the extension doc.
Documents with any number of characters in the extension. | {prop name=filename} {regex} readme.* {/regex}{/prop} —Or— #filename = readme.* | Documents with the name readme and any extension.
Documents with a specified number of characters in the extension. | {prop name=filename} {regex} readme.??? {/regex}{/prop} —Or— #filename = readme.??? | Documents with the name readme and any three-character extension.

Note In the Indexing Service query language, the syntax #contents = text is invalid.


Alternate Word Forms

Dialect 2 provides an effective, but imperfect, mechanism to create alternate word-form, or "fuzzy", queries. These queries take an input word and create alternate forms of the word when submitting the query. This feature goes beyond simple pattern-matching support and uses linguistic or other advanced technologies to generate the alternate word forms.

Alternate word-form query expressions are created using the {generate} tag and specifying a method as an attribute.

{generate method=value} query terms {/generate}

The method attribute specifies the algorithm to be used to generate alternate words for searching. Currently, the valid values for method are prefix and inflect. When prefix is specified, all words beginning with the query terms are found. When inflect is specified, linguistic inflection is performed.

In the short form, the one or two asterisk characters are appended to a word to specify generation of alternate word forms. A single asterisk specifies prefix generation, and a double asterisk specifies inflection generation.

The following table gives examples of alternate word-form queries.

To Search For | Example | Results
Documents containing a term as a prefix. | {prop name=contents} {generate method=prefix} dog {/generate} —Or— @contents dog* | Documents containing dog, dogs, doghouse, dogma, and so forth.
Documents containing inflectional forms of a term. | prop name=contents} {generate method=inflect} swim {/generate} —Or— @contents swim** | Documents containing swim, swam, or swum.

Note Indexing Service provides only inflectional, not derivational, generation. Therefore, only words in the same family (noun, verb, adjective, adverb, and so forth) are generated. For example, gerunds are not generated from nouns. Stemming "swim" generates swim, swam, swum, since these are all verbs — but not nouns such as swimmer and swimmers.

Some search engines may provide other forms of generation on words, such as derivational morphology or soundex. There is no short form for these extended features. The long form must be used.


Term Weighting

Query terms can be weighted at the time of submitting the query to influence the ranking of results. Relatively highly-weighted terms give documents a high ranking.

Query terms can be weighted when submitting a query by using the {weight} tag. This tag is a unary operator, and it appears before the query term and has no closing tag. The syntax is the following.

{weight value = n} query term

The value attribute specifies the weight to assign to the query term. The value of n can range from 0.0 to 1.0. Search engines are free to interpret weighting values within these guidelines.

A linear scale is assumed between 0.0 and 1.0. In Dialect 2, no short-form expression is available for weighting. For information about term weighting in Dialect 1, see Incompatibilities of Dialect 2 with Dialect 1.

The following table gives an example of term weighting.

To Search For | Example | Results
Documents that match terms with specified weights. | {weight value=0.25} dog OR {weight value=0.50} cat OR {weight value=1.00} pig | Documents containing pig followed by documents containing cat followed by documents containing dog.


Vector-Space Queries

Vector-space queries return documents that match a list of words and phrases. The rank of each document indicates how well the document matches the query. To specify a vector-space query, use the following syntax.

{vector RankMethod = method} {ve} query terms {/vector}

A vector-space query specification must be closed with the {/vector} tag. The RankMethod attribute specifies the ranking algorithm to use to evaluate the rank of a query match. The supported ranking methods include the following.

  • Jaccard coefficient
  • Dice coefficient
  • Inner product
  • Minimum
  • Maximum

If any other method is specified, it is ignored and the engine uses the default ranking algorithm, the Jaccard coefficient.

The {ve} tag is a vector element tag. It specifies that the following query specification is an element of the vector query. All the text following the {ve} tag up to the next {ve} tag is interpreted as a query. There is no closing tag for {ve}.

The following table gives several examples of vector-space queries.

To Search For | Example | Results
Documents containing a list of specified words. | {vector RankMethod=maximum} {ve} light {ve} bulb {/vector} —Or— light, bulb | Documents with one or both words. Documents with both words are ranked higher than those with only one.
Documents containing a list of specified prefixes, words, and phrases. | {vector RankMethod=maximum} {ve} {generate method=prefix} invent {/generate} {ve} {weight value=0.3} light {weight value=0.1} bulb {weight value=0.6} {phrase} light bulb {/phrase} {/vector} —Or— invent*, {weight value=0.3} light, {weight value=0.1} bulb, {weight value=0.6} "light bulb" | Documents containing words prefixed by invent, the words light and bulb, and the phrase light bulb. Documents containing the phrase light bulb are ranked before those containing light, which precede those containing bulb.
Documents containing a complex list of words, phrases, property values, and inflected forms. | {vector RankMethod=Jaccard} {ve} {weight value=0.2} printers {ve} {prop name = DocTitle} {freetext} Hewlett Packard HP laserjet laser printer {/freetext} {ve} @contents hang** {/vector} | Documents containing the word printers; the value-type property DocTitle, which contains any of the words Hewlett, Packard, HP, laserjet, laser, printer; or inflectional forms of the word hang.


Incompatibilities of Dialect 2 with Dialect 1

Query Language Dialect 1 is the original query language introduced with Index Server 1.0. In general, it corresponds to the short form of Query Language Dialect 2. This topic describes the incompatibilities between the syntax of the short form of Dialect 2 and Dialect 1. For a reference to the syntax of Dialect 1, see Query-Language Dialects.

Incompatibilities exist in several features, including the default phrase mode, the syntax of vector values, the syntax of term weighting, and language localization. The following table describes these differences in detail.

Dialect 2 | Dialect 1 | Remark
Freetext is the default mode. | Phrase is the default mode. | Freetext became default in Dialect 2.
Multi-element vector is specified as (a;b;…;z). | Multi-element vector is specified as {a,b,…,z}. | "(", ";", and ")" in Dialect 2 were "{", ",", and "}" in Dialect 1.
Weights are in the range 0.0 to 1.0. A weight of 0.1 for term T is specified by {weight value = 0.1} T. | Weights are in the range 0 to 1000. A weight of 100 for term T is specified by T[100]. | The range for Dialect 2 allows greater resolution.
Boolean and proximity operator keywords are available only in their English spellings (AND, OR, NOT, NEAR). | Localized Boolean and proximity operator keywords are also available when the browser locale is set to certain non-English languages. | Dialect 2 keywords will not be localized to accommodate future additions.

The following table lists the non-English supported languages and the localized keywords for the Boolean and proximity operators (AND, OR, NOT, NEAR). These keywords and the short forms (&, |, !, ~) function identically in all supported languages.

Language | Keywords
German | UND, ODER, NICHT, NAH
French | ET, OU, SANS, PRES
Spanish | Y, O, NO, CERCA
Dutch | EN, OF, NIET, NABIJ
Swedish | OCH, ELLER, INTE, NÄRA
Italian | E, O, NO, VICINO


SQL Query Language

In addition to its own Indexing Service Query Language, Indexing Service has supported queries in the SQL query language since Index Server 2.0. This provides expression of queries in a standard query language.

This section describes several features of the SQL query language and its extensions for Indexing Service. It consists of the following topics.

  • Query Submittal for SQL Query Language
  • Query Syntax of SQL Query Language
  • Extensions to SQL for Indexing Service

For a reference to the SQL query language and its extensions, see SQL Queries and SQL Extensions.


Query Submittal for SQL Query Language

To use the SQL query language, an application or script must use one of two APIs to submit a query. In general, these APIs feature flexibility and the fastest execution rather than ease of programming. The following table lists the APIs and provides pointers to summary topics of how to submit queries.

API | For Query Submittal, See
ActiveX Data Objects | Setting the Provider Property Setting the Locale and Other Properties
OLE DB Provider | Using OLE DB Provider for Indexing Service

For information about which languages and tools you can use with these APIs, see Combinations of Tasks, Languages, and APIs. For additional information about using these APIs to submit queries and for examples, see Using Indexing Service with File Systems and Using Indexing Service with Web Servers.


Setting the Provider Property

To use the ActiveX Data Objects (ADO) API, a program or script needs to open a connection to the OLE DB Provider for Indexing Service and set the Provider property of the ADO Connection object to the string "MSIDXS". The Provider property can also be set by the contents of the ConnectionString property or the ConnectionString parameter of the Open method. Alternatively, you can generate a Recordset object and ensure that the associated Open method includes a ConnectionString parameter containing the string "PROVIDER=MSIDXS;".

The following is an example of the minimal Microsoft Visual Basic® Scripting Edition (VBScript) code needed to generate an ADO Recordset object.

Set rstMain = Server.CreateObject("ADODB.Recordset")
RstMain.Open "SELECT DocAuthor, DocTitle, FileName
                FROM SCOPE() WHERE size > 50000",
                "PROVIDER=MSIDXS;"

The following is an example of the ADO code that creates a Connection object.

Set Conn = Server.CreateObject ("ADODB.Connection")
Conn.ConnectionString = "provider=msidxs;"
Conn.Open

After executing the preceding example, you can create a Command object, associate it to the active connection you opened, set the CommandText property of the Command object to the desired SQL query string, and create the associated Recordset object to retrieve the results of your query.


Setting the Locale and Other Properties

To use the ADO API, a program or script often needs to set various dynamic ADO properties of the Command, Connection, and Recordset objects. For a listing of all ADO dynamic properties available for Indexing Service, see Dynamic ADO Properties. The remainder of this topic uses, as an example, setting the locale.

You can change the locale for a Command object by setting the dynamic ADO property "SQL Content Query Locale String" to the appropriate string. Alternatively, you can set the dynamic ADO property "Locale Identifier" of the Connection object to the appropriate locale identifier (LCID).

The following examples illustrate setting the locale for queries.

  • The following example sets the "SQL Content Query Locale String" property of the Command object AdoCommand to the locale "GE".
    AdoCommand.Properties("SQL Content Query Locale String") = "GE"
  • The following example obtains the default locale from the browser HTTP_ACCEPT_LANGUAGE variable and uses it to set the locale.
    strLocale = Request.ServerVariable("HTTP_ACCEPT_LANGUAGE")
AdoCommand.Properties("SQL Content Query Locale String") = strLocale
  • The following example sets the "Locale Identifier" property of the Connection object AdoConnection to the US-English locale.
    AdoConnection.Properties("Locale Identifier") = 1033 'EN-US locale code

Note The Locale property that you set, in either a Connection or Command object, does not affect the displayed error messages. The displayed error messages are based on the default locale specified in the user profile. The Locale property that you set is passed to Indexing Service, which uses it for searching.


Query Syntax of SQL Query Language

A typical sequence of statements in the SQL query language consists of the following.

SET Property_Name_Clause | Rank_Method_Clause
...
CREATE VIEW #View_Name
  AS SELECT Select_List
            FROM_Clause
...
SELECT Select_List | *
       FROM_Clause
       [ WHERE_Clause ]
       [ ORDER_BY_Clause ]

SQL statements can be submitted individually, or batched together. The following table lists the component statements and clauses in their usual order of use and briefly summarizes each.

Statement or Clause | Description
SET statement | Maps document-specific properties to column names or selects a ranking method for content searches.
CREATE VIEW statement | Associates a subset of properties with a user-defined virtual table name that can then be used to satisfy queries. Several predefined views can be used.
SELECT statement | Retrieves rows by specifying the columns of interest, the scope (the set of documents) for the search, and the search criteria.
FROM clause | Part of the SELECT statement that defines the query scope by specifying the documents on which to perform the search.
WHERE clause | Optional part of the SELECT statement that specifies the rows in the virtual table that make up the resulting rowset.
ORDER BY clause | Optional part of the SELECT statement that sorts the rows returned in the rowset according to a specified set of criteria.
Batched statements | Allow setting and executing several SQL statements, optionally separated by semicolons, as one command.


Extensions to SQL for Indexing Service

The SQL query language includes extensions to the standard SQL data manipulation language (DML) for querying the indexed contents of Indexing Service catalogs. Conceptually, the SQL query language considers a catalog to be a table with columns containing properties and rows containing documents. (For additional details, see Representing the Catalog Conceptually.) The extensions include the following.

  • Extensions for Properties
  • Extensions for Queries

The SQL extensions for Indexing Service do not support cross-data source queries. You need to issue separate queries to another source — for example, the ODBC Provider to SQL Server™ — when combining information from more than one source.


Extensions for Properties

Columns can be either a standard Indexing Service property or a new property defined by a SET PROPERTYNAME statement.

Standard properties available for all documents include the following.

Property Name | Description
All | Matches words, phrases, and any property.
Contents | Words and phrases in the document.
Filename | Name of the document.
Size | Document size.
Write | Last time the document was modified.

A query can also use ActiveX property values. Documents created by most ActiveX-aware applications can be queried for the following properties.

Property Name | Description
DocTitle | Title of the document.
DocSubject | Subject of the document.
DocAuthor | Author of the document.
DocKeywords | Keywords for the document.
DocComments | Comments about the document.

There is also a list of additional standard Indexing Service properties that are available in queries. For the list, see Default Property Names for a Web Catalog.


Extensions for Queries

The following table summarizes the extensions to the SQL syntax for specifying queries to Indexing Service.

SQL Extension | Description
SET PROPERTYNAME | Defines the column name and a data type for a property.
SET RANKMETHOD | Sets the document ranking method used for the results of queries.
CREATE VIEW # | Creates a temporary view using column names and scope.
Indexing Service Predefined Views Site Server Predefined Views | Defines permanent views using standard Indexing Service properties.
SELECT * | Selects all columns in a predefined or temporary view.
FROM SCOPE | Defines the server, catalog, and path to use to create a virtual table of rows of documents.
ARRAY predicate | Enables comparison of multivalued Indexing Service properties.
Comparison predicate | Enables comparison of columns with literal data using relational operators.
MATCHES predicate | Similar to the LIKE predicate, but enables grouping matches against more than one pattern.
Batched statements | Enables setting and executing several SQL statements as one command.


Example Queries

The following table illustrates several example queries. The examples for the short form of Dialect 2 generally apply to Dialect 1 with the exception of the incompatibilities noted in Incompatibilities of Dialect 2 with Dialect 1.

Example | Version | Results
{prop name=Contents} apple tree {/prop} | Dialect 2 | Documents with the phrase apple tree.
{phrase} apple tree {/phrase} | Dialect 2 | Documents with the phrase apple tree.
"apple tree" | Dialect 2, short form | Documents with the phrase apple tree.
apple tree | Dialect 2, short form | Documents with either or both of the words apple and tree.
apple tree | Dialect 1 | Documents with the phrase apple tree.
apple {near dist=50, unit=word} tree | Dialect 2 | Documents with the words apple and tree within 50 words of each other.
Microsoft near release and {prop name=rank} > 0 | Dialect 2 | Documents containing the words Microsoft and release occurring near each other.
Microsoft ~ release & @rank > 0 | Dialect 2, short form, or Dialect 1 | Documents containing the words Microsoft and release occurring near each other.
$contents Why is the sky blue? | Dialect 2, short form, or Dialect 1 | Documents that match the free-text query (which are about the blue sky).
@size > 1000000 & < 2000000 | Dialect 2, short form, or Dialect 1 | Documents larger than 1 million bytes but smaller than 2 million bytes.
{prop name=size} > 1000000 & < 2000000 | Dialect 2 | Documents larger than 1 million bytes but smaller than 2 million bytes.
@attrib ^s 32 | Dialect 2, short form, or Dialect 1 | Documents with the archive attribute bit on.
@all Excel & ( @size > 1000 & < 100000 ) & Microsoft | Dialect 2, short form, or Dialect 1 | Documents containing the words Excel and Microsoft that are between 1,000 and 100,000 bytes in size.
{prop name=all} Excel and {prop name=size} > 1000 and < 100000 ) {/prop} and Microsoft | Dialect 2 | Documents containing the words Excel and Microsoft that are between 1,000 and 100,000 bytes in size.
@Write > -2d | Dialect 2, short form, or Dialect 1 | All documents changed within the last two days.
@Write > 2000-1-1 | Dialect 2, short form, or Dialect 1 | All documents on or after the year 2000.
@filename = *.avi | Dialect 2, short form, or Dialect 1 | Video files. The = indicates the query contains an MS-DOS/Windows wildcard character.
#filename *.avi | Dialect 2, short form, or Dialect 1 | Video files. The # prefix indicates the query contains a regular expression.
#filename *.|(do?|,xl?|,p?t|,mdb|) | Dialect 2, short form, or Dialect 1 | Microsoft Office documents.
{prop name=filename} {regex}*.|(do?|,xl?|,p?t|,mdb|){/regex} | Dialect 2 | Microsoft Office documents.
#path "*\|[^\]|[14,|}\*" | Dialect 2, short form, or Dialect 1 | Paths with a directory component containing fourteen or more characters.
{prop name=path}{regex}"*\|[^\]|[14,|}\*"{/regex} | Dialect 2 | Paths with a directory component containing fourteen or more characters.
{generate method=prefix} dog {/generate} | Dialect 2 | All words beginning with dog: For example, dog, dogs, doghouse, dogma.
@contents BackOffice &! #vpath *\_vti_* | Dialect 2, short form, or Dialect 1 | Documents containing the word BackOffice, but which are not in Microsoft FrontPage® hidden directories. Microsoft BackOffice® is a family of server software, designed to integrate various computer functions for businesses.
{prop name=contents} BackOffice AND NOT {prop name=vpath}{regex}*\_vti_*{/regex} | Dialect 2 | Documents containing the word BackOffice, but which are not in Microsoft FrontPage hidden directories.
SELECT * FROM FILEINFO
  WHERE size > 1000000
 SQL Documents larger than 1 million bytes.
SELECT FileName FROM SCOPE()
  WHERE CONTAINS ('search')
    AND NOT CONTAINS ('slow')
 SQL Documents with the phrase search but not the phrase slow.
SELECT DocAuthor, DocTitle
FROM SCOPE()
  WHERE CONTAINS(DocAuthor,
         'smith')
 SQL Documents written by Smith.
...WHERE CONTAINS(DocSubject,
         '"Microsoft"
          AND "Indexing"
          NEAR "Service"')
 SQL Documents containing the words Microsoft and Indexing near the word Service.


Using Indexing Service with File Systems

Beginning with version 3.0, Indexing Service indexes and queries, by default, all files that occur in the "system" catalog, in addition to virtual Webs in the "Web" catalog. This extends the usefulness of the search facilities of Indexing Service to a broader range of scripts and applications. This section describes how to programmatically use Indexing Service when the primary emphasis of a task involves file systems rather than Web servers. This section consists of the following topics:

  • Programming with Scripts
  • Programming with Applications
  • File System Samples

For information about applying Indexing Service to Web servers, see Using Indexing Service with Web Servers. For summary information about programming for Indexing Service in general — including tasks, languages, APIs, and tools — see Programming for Indexing Service.


Programming with Scripts

Prior to Indexing Service 3.0, you typically had to perform most Indexing Service scripting tasks with Web-server tools such as Microsoft® Internet Explorer or Internet Information Services (IIS). With Indexing Service 3.0 you can perform file-system oriented tasks with scripts using Windows® Script Host as well as with several programming languages. With either of two scripting languages, Microsoft Visual Basic® Scripting Edition (VBScript) or JScript®, you can perform managing and querying tasks with Windows Script Host. This section includes the following sections that describe the use of the VBScript and JScript languages with the Windows Script Host.

  • Using Indexing Service APIs from Scripts
  • Using Visual Basic Scripting Edition with Indexing Service
  • Using JScript with Indexing Service

For information about using scripts with a Web-server tool, see Using Indexing Service with Web Servers. For examples of using scripts with Web servers, see the scripts embedded in the Web Server Samples. For information about programming Indexing Service with applications, see Programming with Applications.


Using Indexing Service APIs from Scripts

Scripts can manage and query Indexing Service using the Admin Helper API and the Query Helper API, which make programming easier than directly using the OLE DB Provider for Indexing Service. Scripts can also use the ActiveX Data Objects (ADO) API, which represents the rowset of the OLE DB Provider as a Recordset object. The topics in this section describe the use of these APIs with scripts and include the following.

  • Admin Helper API and Scripts
  • Query Helper API and Scripts
  • ActiveX Data Objects API and Scripts


Admin Helper API and Scripts

The Admin Helper API provides the AdminIndexServer, CatAdm, and ScopeAdm objects for managing the tasks, catalogs, and scopes of Indexing Service. A script can use these objects, for example, to start, pause, or stop Indexing Service; set, get, or add a catalog; and set, get, or add a scope for a catalog.

The following table shows how to create in scripts an AdminIndexServer object, shows one way to create a CatAdm object, and shows one way to create a ScopeAdm object. For additional ways of creating CatAdm objects, see the methods of the AdminIndexServer object. For additional ways of creating ScopeAdm objects, see the methods of the CatAdm object.

Object Creation in VBScript Creation in JScript
AdminIndexServer
Set objAdminIS = WScript.CreateObject("Microsoft.ISAdm")

objAdminIS = new ActiveXObject("Microsoft.ISAdm");
CatAdm
Set objCatAdm = objAdminIS.GetCatalog( )

objCatAdm = new objAdminIS.GetCatalog( );
ScopeAdm
Set objScopeAdm = objCatAdm.GetScope( )

objScopeAdm = new objCatAdm.GetScope( );

The ciodm.dll file contains the objects of the Admin Helper API.


Query Helper API and Scripts

The Query Helper API provides the Query and Utility objects for creating and managing queries to the OLE DB Provider for Indexing Service. A script can use these objects along with an ADO Recordset object (see ActiveX Data Objects API and Scripts), which represents the resulting records from a query.

The following table shows how to create a Query object and a Utility object in scripts.

Object Creation in VBScript Creation in JScript
Query
Set objQuery = WScript.CreateObject("IXSSO.Query")

objQuery = new ActiveXObject("IXSSO.Query");
Utility
Set objUtility = WScript.CreateObject("IXSSO.Util")

objUtility = new ActiveXObject("IXSSO.Util");

The ixsso.dll file contains the objects of the Query Helper API.


ActiveX Data Objects API and Scripts

The ActiveX Data Objects (ADO) API provides the Connection, Command, and Recordset objects for accessing and manipulating data from the OLE DB Provider for Indexing Service. Of these objects, an Indexing Service script typically uses only the Recordset object to represent the set of records that results from a query submitted by means of the Query Helper API (see Query Helper API and Scripts).

The following table shows how to use the Query.CreateRecordset method to create a Recordset object in scripts.

Object Creation in VBScript Creation in JScript
Recordset
Set objRecordset = objQuery.CreateRecordset("sequential")

objRecordset = objQuery.CreateRecordset("sequential");

The msad*.dll files contain the ADO objects.


Using Visual Basic Scripting Edition with Indexing Service

Visual Basic Scripting Edition (VBScript) is a powerful and flexible scripting language that you can use with Windows Script Host to manage and query Indexing Service. This section discusses several aspects of using VBScript with Indexing Service and includes VBScript code examples. The topics include the following.

  • Creating a Query in Visual Basic Scripting Edition
  • Running a Visual Basic Scripting Edition Query
  • Managing Indexing Service in Visual Basic Scripting Edition
  • Converting OLE DB Data Types to Visual Basic Scripting Edition Variant Types


Creating a Query in Visual Basic Scripting Edition

The VBSQuery.vbs script of the SQuery Sample executes a query that is embedded in the script. The query produces a parent, chaptered Recordset object (which represents a hierarchical rowset) with selected columns forming a child chapter. This script is also translated into the JScript language. For a discussion of the JScript version, see Creating a Query in JScript.

The following pseudocode divides the sample script into segments and shows the structure of the complete script. The individual topic for each segment describes the details of the code for that segment.

' Declare Variables.
' Create a Query Object.
' Set Properties of the Query Object.
' Create a Utility Object.
' Add the Physical Path and all Subdirectories.
' Output Query Properties.
' Create a Parent Recordset Object for the Query.
' Determine the Name of the GroupBy Column.
' Read through the Parent Recordset Object.
' Extract and Output Values for Non-Chaptered Columns.
' Create a Child Recordset Object for Chaptered Columns.
' Read through the Child Recordset Object, Extracting and Outputting Values for Chaptered Columns.
' Close the Child Recordset Object.
' Close the Parent Recordset Object.


Declare Variables

This code segment declares all the (global) variables for the script, because the script doesn't contain any Sub or Function procedures with local variables. Although it is optional to declare variables before you use them in VBScript, it is good programming practice to use the Option Explicit statement and to declare variables that the script uses.

Option Explicit

Dim strGroupBy          ' Name of GroupBy column.
Dim intI, intJ          ' Index variables.
Dim objQ                ' Query object.
Dim strRecord           ' Output record of query results.
Dim objRS_Child         ' Child Recordset object.
Dim objRS_Parent        ' Parent Recordset object.
Dim intRS_Child_Count   ' Number of current record of child Recordset.
Dim intRS_Parent_Count  ' Number of current record of parent Recordset.
Dim objU                ' Utility object.


Create a Query Object

This code segment uses the CreateObject method of the WScript (Windows Script Host) object to create objQ, a Query object, from ixsso.dll.

Set objQ = WScript.CreateObject("IXSSO.Query")


Set Properties of the Query Object

This code segment sets several properties of the objQ Query object. The Columns property specifies to return the file name, directory, size, and write time columns in the results, and the GroupBy property specifies to group the results in a hierarchical recordset by values of the directory column, in ascending order. This creates a query with a parent recordset consisting of directory names and the chaptered file name, size, and write time columns. The chaptered columns are a child recordset of the parent directory.

objQ.Columns = "filename, directory, size, write"
objQ.Query   = "#filename *.asp"
objQ.GroupBy = "directory[a]"
objQ.Catalog = "system"
objQ.OptimizeFor      = "recall"
objQ.AllowEnumeration = TRUE
objQ.MaxRecords       = 20000

The Query property specifies the query text "#filename *.asp", which is in query language Dialect 1 by default, and which is a pattern-matching query that uses a UNIX-style regular expression.


Create a Utility Object

This code segment uses the CreateObject method of the WScript object to create objU, a Utility object, from ixsso.dll.

Set objU = WScript.CreateObject("IXSSO.Util")


Add the Physical Path and all Subdirectories

This code segment uses the AddScopeToQuery method of the objU Utility object to add the scope "\" and all its subdirectories to the query.

objU.AddScopeToQuery objQ, "\", "deep"


Output Query Properties

This code segment uses the Echo method of the WScript object to output the properties of the query that the script set earlier. When the script is run as a Windows application using wscript.exe, each Echo method produces a dialog with its specified output. When run with cscript.exe at the command prompt, each Echo method produces a line of output.

WScript.Echo " Columns = " & objQ.Columns
WScript.Echo " Query = " & objQ.Query
WScript.Echo " GroupBy = " & objQ.GroupBy
WScript.Echo " Catalog = " & objQ.Catalog
WScript.Echo " CiScope = " & objQ.CiScope
WScript.Echo " CiFlags = " & objQ.CiFlags
WScript.Echo " OptimizeFor = " & objQ.OptimizeFor
WScript.Echo " AllowEnumeration = " & CStr(objQ.AllowEnumeration)
WScript.Echo " MaxRecords = " & objQ.MaxRecords

Up to this point, the output when running the script with cscript.exe is the following.

 Columns = filename, directory, size, write
 Query = #filename *.asp
 GroupBy = directory[a]
 Catalog = system
 CiScope = \
 CiFlags = DEEP
 OptimizeFor = recall,hitcount
 AllowEnumeration = True
 MaxRecords = 20000


Create a Parent Recordset Object for the Query

This code segment uses the CreateRecordset method of the Query object to execute the query and to create objRS_Parent, an ADO parent Recordset object of query results.

Set objRS_Parent = objQ.CreateRecordset("nonsequential")

For a description of the "nonsequential" parameter, see Sequential vs. Nonsequential Execution.


Determine the Name of the GroupBy Column

This code segment iterates through all the fields of the objRS_Parent Recordset object and concatenates the names of the columns in the parent recordset, excluding any chaptered columns.

strGroupBy = ""
For intI = 0 to objRS_Parent.Fields.Count - 1
    If objRS_Parent(intI).Name <> "Chapter" Then
        If strGroupBy <> "" Then
            strGroupBy = strGroupBy & "    " & objRS_Parent(intI).Name
        Else
            strGroupBy = objRS_Parent(intI).Name
        End If
    End If
Next

For the properties set in this example, the strGroupBy variable is "DIRECTORY".


Read through the Parent Recordset Object

This code segment steps through the parent objRS_Parent Recordset object until an end of file occurs. For each parent recordset (directory for this example), the code segment outputs the values of the child recordsets (file names, sizes, and writes for this example).

The following pseudocode divides the segment into subsegments and shows the structure of the complete segment. The individual topic for each subsegment describes the details of the code for that subsegment.

intRS_Parent_Count = 0
Do While Not objRS_Parent.EOF
    intRS_Parent_Count = intRS_Parent_Count + 1
    strRecord = Left(CStr(intRS_Parent_Count) & ".      ", 4)

    ' Extract and Output Values for Non-Chaptered Columns.
    ' Create a Child Recordset Object for Chaptered Columns.
    ' Read through the Child Recordset Object, Extracting and Outputting Values for Chaptered Columns.
    ' Close the Child Recordset Object.

    objRS_Parent.MoveNext
Loop

The output when running the script with cscript.exe is similar to the following.

1.    c:\inetpub\iissamples\default
1.1.      learn.asp  4859  9/17/98 1:48:10 AM
1.2.      exair.asp  4641  6/16/98 6:22:58 AM
2.    c:\inetpub\iissamples\sdk\asp\applications
2.1.      session_vbscript.asp  1553  5/30/98 2:52:24 AM
2.2.      session_jscript.asp  1568  5/30/98 2:52:24 AM
2.3.      application_vbscript.asp  2011  5/30/98 2:52:24 AM
2.4.      application_jscript.asp  2017  5/30/98 2:52:24 AM
...


Extract and Output Values for Non-Chaptered Columns

This code subsegment iterates through all the fields of the objRS_Parent Recordset object and concatenates the values of the columns in the parent recordset, excluding any chaptered columns.

For intI = 0 to objRS_Parent.Fields.Count - 1
    If objRS_Parent(intI).Name <> "Chapter" Then
        strRecord = strRecord & "  " & objRS_Parent(intI).Value
    End If
Next

WScript.Echo strRecord

For the query properties that this example sets, the strRecord variable is, for example, the following.

1.    c:\inetpub\iissamples\default


Create a Child Recordset Object for Chaptered Columns

This code subsegment uses the Value property of the "Chapter" Field object of the objRS_Parent Recordset object to create an objRS_Child Recordset object.

Set objRS_Child = objRS_Parent.Fields("Chapter").Value


Read through the Child Recordset Object, Extracting and Outputting Values for Chaptered Columns

This code subsegment steps through the child objRS_Child Recordset object until an end of file occurs, and, for each child recordset (of filename, size, and write for this example), outputs the values in the child recordsets.

intRS_Child_Count = 0
Do While Not objRS_Child.EOF
    intRS_Child_Count = intRS_Child_Count + 1
    strRecord = Left(CStr(intRS_Parent_Count) + "." + CStr(intRS_Child_Count) + ".      ", 8)

    For intJ = 0 to objRS_Child.Fields.Count - 1
        If objRS_Child(intJ).Name <> "Chapter" Then
            If objRS_Child(intJ).Name <> strGroupBy Then
                strRecord = strRecord & "  " & objRS_Child(intJ).Value
            End If
        End If
    Next

    WScript.Echo strRecord
    objRS_Child.MoveNext
Loop

For the query properties set in this example, the strRecord variable is, for example, the following.

1.1.      learn.asp  4859  9/17/98 1:48:10 AM
1.2.      exair.asp  4641  6/16/98 6:22:58 AM
...


Close the Child Recordset Object

This code subsegment uses the Close method of the objRS_Child Recordset object to free the system resources of the child recordset. Setting the objRS_Child Recordset object to Nothing removes the child object from memory.

objRS_Child.Close
Set objRS_Child = Nothing


Close the Parent Recordset Object

This code segment uses the Close method of the objRS_Parent Recordset object to free the system resources of the parent recordset. Setting the objRS_Parent Recordset object to Nothing removes the parent object from memory.

objRS_Parent.Close
Set objRS_Parent = Nothing


Running a Visual Basic Scripting Edition Query

You can run a script written in Visual Basic Scripting Edition (VBScript) to submit a query (or to perform a managing task) with Windows Script Host in several ways, which include the following.

To execute a query such as VBScript.vbs as a command-prompt application

  1. Open a command window and change the directory to the path of the script.
  2. Submit the query by entering, at the command-line prompt,
    cscript vbscript.vbs

The output of the script appears in the command window.

To execute a query such as VBScript.vbs as a Windows application

  1. Select Start, Run... from the Windows toolbar.
  2. Submit the query by entering the absolute path of the script in the Open dialog box or by clicking the Browse button to find the appropriate directory and select the script file.

The output of each Echo method in the script appears in a separate dialog box. This is handy for debugging, but for a query with a large number of matches you will need to close each dialog box to proceed.


Managing Indexing Service in Visual Basic Scripting Edition

The QSample.vbs script of the SQuery Sample executes a query that you specify as part of the script input parameters. This script functions similarly to the Simple sample, which is written in the C++ language. It also performs some managing tasks with Indexing Service.

A major part of the QSample.vbs script is the Sub procedure DoQuery, which is defined with the following statement.

sub DoQuery( query, catalog, locale, forceci, forcemerge, shallow, dialect, machine, columns, scope, quiet, sort, stats, uptodate, maxhits )

A portion of this procedure displays statistics for the catalog, checks if the catalog is up to date, or forces a master merge. The following code segment begins this portion.

set a = WScript.CreateObject( "microsoft.ISAdm" )
a.MachineName = machine
set c = a.GetCatalogByName( catalog )

The first statement uses the CreateObject method of the WScript object to create a, which is an AdminIndexServer object, from ciodm.dll. The second statement sets the MachineName property of the object to the name of the computer specified on the script input. The third statement uses the GetCatalogByName method of the AdminIndexServer object to create c, which is a CatAdm object that represents the catalog.

If the script input specifies to force a master merge, the script uses the ForceMasterMerge method to start the master merge operation.

        if forcemerge then c.ForceMasterMerge

When the input to the script specifies to determine whether the catalog is up to date, the script uses the IsUpToDate property of the CatAdm object to determine and output the status.

if c.IsUpToDate then
    out "The catalog is up to date."
else
    out "The catalog is not up to date."
end if

These are just a few examples of using the Admin Helper API in scripts to manage Indexing Service.


Converting OLE DB Data Types to Visual Basic Scripting Edition Variant Types

Because all programming access to Indexing Service is through the OLE DB Provider, you can retrieve only supported OLE DB data types when you ask for information back from a query. Visual Basic Scripting Edition (VBScript) supports certain Automation data types within its VARIANT data-type implementation. The following table lists the OLE DB data types supported, their equivalent Automation variant types, and any formatting restrictions imposed when displaying the data to an end user through VBScript.

OLE DB data type | Automation Variant type | Formatting restrictions
DBTYPE_I1 | VT_I1 | Integer. Expressed either in decimal (base 10) or hexadecimal (base 16) notation. The latter requires 0x before the number, for example, 0x3F8.
DBTYPE_UI1 | VT_UI1 | Integer. Expressed either in decimal (base 10) or hexadecimal (base 16) notation. The latter requires 0x before the number.
DBTYPE_I2 | VT_I2 | Integer. Expressed either in decimal (base 10) or hexadecimal (base 16) notation. The latter requires 0x before the number.
DBTYPE_UI2 | VT_UI2 | Integer. Expressed either in decimal (base 10) or hexadecimal (base 16) notation. The latter requires 0x before the number.
DBTYPE_I4 | VT_I4 | Integer. Expressed either in decimal (base 10) or hexadecimal (base 16) notation. The latter requires 0x before the number.
DBTYPE_UI4 | VT_UI4 | Integer. Expressed either in decimal (base 10) or hexadecimal (base 16) notation. The latter requires 0x before the number.
DBTYPE_I8 | VT_I8 | Integer. Expressed either in decimal (base 10) or hexadecimal (base 16) notation. The latter requires 0x before the number.
DBTYPE_UI8 | VT_UI8 | Integer. Expressed either in decimal (base 10) or hexadecimal (base 16) notation. The latter requires 0x before the number.
DBTYPE_R4 | VT_R4 | Real number. Can be expressed in scientific notation.
DBTYPE_R8 | VT_R8 | Real number. Can be expressed in scientific notation.
DBTYPE_CY | VT_CY | Currency. Expressed as two integers, separated by a period; for example, 100.55. Cannot be preceded by $, ¥, £, or other such signs. This data type does not specify the currency format.
DBTYPE_DATE | VT_DATE | Date. Expressed as an absolute in two forms: yyyy/mm/dd and yyyy/mm/dd hh:mm:ss. Also expressed as a relative date: -#y, -#m, -#w, -#d, -#h, -#n, -#s where the letters correspond to year, month, week, day, hour, minute and second. Positive relative dates in the future are not supported.
DBTYPE_BOOL | VT_BOOL | Boolean. Expressed as TRUE or FALSE.
DBTYPE_STR | VT_LPSTR | String. Any input accepted.
DBTYPE_WSTR | VT_LPWSTR | Unicode string. Any input accepted.
DBTYPE_BSTR | VT_BSTR | Basic string. Any input accepted.
DBTYPE_GUID | VT_CLSID | Globally unique identifier (GUID). Expressed as XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
DBTYPE_BYREF | (not applicable) | For queries, this should be added to DBTYPE_STR and DBTYPE_WSTR string types. For example: DBTYPE_WSTR | DBTYPE_BYREF.
DBTYPE_VECTOR | VT_VECTOR | Vector properties are fully supported.
VT_FILETIME | VT_FILETIME | Expressed as an absolute in two forms: yyyy/mm/dd and yyyy/mm/dd hh:mm:ss. Also expressed as a relative date: -#y, -#m, -#w, -#d, -#h, -#n, -#s where the letters correspond to year, month, week, day, hour, minute and second. Positive relative dates into the future are not supported.


Using JScript with Indexing Service

JScript is a standard scripting language used primarily for the Web that you can use with Windows Script Host to manage and query Indexing Service. This section discusses several aspects of using JScript with Indexing Service and includes a JScript code example. The topics include the following.

  • Creating a Query in JScript
  • Running a JScript Query


Creating a Query in JScript

The JSQuery.js script of the SQuery Sample executes a query that is embedded in the script. The query produces a parent, chaptered recordset (which represents a hierarchical rowset) that contains selected columns forming a child chapter. The JSQuery.js script is a translation of the VBScript.vbs script into the JScript language. For a discussion of the VBScript version, see Creating a Query in Visual Basic Scripting Edition.

The following pseudocode divides the sample script into segments and shows the structure of the complete script. The individual topic for each segment describes the details of the code for that segment.

// Declare Variables.
// Create a Query Object.
// Set Properties of the Query Object.
// Create a Utility Object.
// Add the Physical Path and all Subdirectories.
// Output Query Properties.
// Create a Parent Recordset Object for the Query.
// Determine the Name of the GroupBy Column.
// Read through the Parent Recordset Object.
// Extract and Output Values for Non-Chaptered Columns.
// Create a Child Recordset Object for Chaptered Columns.
// Read through the Child Recordset Object, Extracting and Outputting Values for Chaptered Columns.
// Close the Child Recordset Object.
// Close the Parent Recordset Object.


Declare Variables

This code segment declares all the (global) variables for the script, because the script doesn't contain any functions with local variables. Although it is optional to declare global variables before you use them in JScript, it is good programming practice to so.

var strGroupBy;         // Name of GroupBy column.
var intI, intJ;         // Index variables.
var objQ;               // Query object.
var strRecord;          // Output record of query results.
var objRS_Child;        // Child Recordset object.
var objRS_Parent;       // Parent Recordset object.
var intRS_Child_Count;  // Number of current record of child Recordset.
var intRS_Parent_Count; // Number of current record of parent Recordset.
var objU;               // Utility object.


Create a Query Object

This code segment creates objQ, a Query object, as a new ActiveXObject object from ixsso.dll.

objQ = new ActiveXObject("IXSSO.Query");


Set Properties of the Query Object

This code segment sets several properties of the objQ Query object. The Columns property specifies to return the filename, directory, size, and write time columns in the results, and the GroupBy property specifies to group the results in a hierarchical recordset by values of the directory column in ascending order. This creates a query with a parent recordset consisting of directory names and the chaptered file name, size, and write time columns. The chaptered columns are a child recordset of the parent directory.

objQ.Columns = "filename, directory, size, write";
objQ.Query   = "#filename *.asp";
objQ.GroupBy = "directory[a]";
objQ.Catalog = "system";
objQ.OptimizeFor      = "recall";
objQ.AllowEnumeration = true;
objQ.MaxRecords       = 20000;

The Query property specifies the query text "#filename *.asp", which is in query language Dialect 1 by default, and which is a pattern-matching query that uses a UNIX-style regular expression.


Create a Utility Object

This code segment creates objU, a Utility object, as a new ActiveXObject object from ixsso.dll.

objU = new ActiveXObject("IXSSO.Util");


Add the Physical Path and all Subdirectories

This code segment uses the AddScopeToQuery method of the objU Utility object to add the scope "\" and all its subdirectories to the query.

objU.AddScopeToQuery(objQ, "\\", "deep");


Output Query Properties

This code segment uses the Echo method of the WScript object to output the properties of the query that the script set earlier. When the script is run as a Windows application using wscript.exe, each Echo method produces a dialog with its specified output. When run with cscript.exe at the command prompt, each Echo method produces a line of output.

WScript.Echo(" Columns = " + objQ.Columns);
WScript.Echo(" Query = " + objQ.Query);
WScript.Echo(" GroupBy = " + objQ.GroupBy);
WScript.Echo(" Catalog = " + objQ.Catalog);
WScript.Echo(" CiScope = " + objQ.CiScope);
WScript.Echo(" CiFlags = " + objQ.CiFlags);
WScript.Echo(" OptimizeFor = " + objQ.OptimizeFor);
WScript.Echo(" AllowEnumeration = " + objQ.AllowEnumeration);
WScript.Echo(" MaxRecords = " + objQ.MaxRecords);

Up to this point, the output when running the script with cscript.exe is the following.

 Columns = filename, directory, size, write
 Query = #filename *.asp
 GroupBy = directory[a]
 Catalog = system
 CiScope = \
 CiFlags = DEEP
 OptimizeFor = recall,hitcount
 AllowEnumeration = True
 MaxRecords = 20000


Create a Parent Recordset Object for the Query

This code segment uses the CreateRecordset method of the Query object to execute the query and to create objRS_Parent, an ActiveX Data Objects (ADO) parent Recordset object of query results.

objRS_Parent = objQ.CreateRecordset("nonsequential");

For a description of the "nonsequential" parameter, see Sequential vs. Nonsequential Execution.


Determine the Name of the GroupBy Column

This code segment iterates through all the fields of the objRS_Parent Recordset object and concatenates the names of the columns in the parent recordset, excluding any chaptered columns.

strGroupBy = "";
for (intI=0; intI<objRS_Parent.Fields.Count; intI++) {
    if (objRS_Parent(intI).Name != "Chapter") {
        if (strGroupBy != "")
            strGroupBy = strGroupBy + "    " + objRS_Parent(intI).Name
        else
            strGroupBy = objRS_Parent(intI).Name;
    };
};

For the properties set in this example, the strGroupBy variable is "DIRECTORY".


Read through the Parent Recordset Object

This code segment steps through the parent objRS_Parent Recordset object until an end of file occurs, and, for each parent recordset (directory for this example), outputs the values of the child recordsets (filenames, sizes, and writes for this example).

The following pseudocode divides the segment into subsegments and shows the structure of the complete segment. The individual topic for each subsegment describes the details of the code for that subsegment.

intRS_Parent_Count = 0;
while (!objRS_Parent.EOF) {
    intRS_Parent_Count = intRS_Parent_Count + 1;
    strRecord = (intRS_Parent_Count + ".      ").slice(0,4);

    // Extract and Output Values for Non-Chaptered Columns.
    // Create a Child Recordset Object for Chaptered Columns.
    // Read through the Child Recordset Object, Extracting and Outputting Values for Chaptered Columns.
    // Close the Child Recordset Object.

    objRS_Parent.MoveNext;
};

The output when running the script with cscript.exe is similar to the following.

1.    c:\inetpub\iissamples\default
1.1.      learn.asp  4859  Thu Sep 17 01:48:10 PDT 1998
1.2.      exair.asp  4641  Tue Jun 16 06:22:58 PDT 1998
2.    c:\inetpub\iissamples\sdk\asp\applications
2.1.      session_vbscript.asp  1553  Sat May 30 02:52:24 PDT 1998
2.2.      session_jscript.asp  1568  Sat May 30 02:52:24 PDT 1998
2.3.      application_vbscript.asp  2011  Sat May 30 02:52:24 PDT 1998
2.4.      application_jscript.asp  2017  Sat May 30 02:52:24 PDT 1998
...


Extract and Output Values for Non-Chaptered Columns

This code subsegment iterates through all the fields of the objRS_Parent Recordset object and concatenates the values of the columns in the parent recordset, excluding any chaptered columns.

for (intI=0; intI<objRS_Parent.Fields.Count; intI++) {
    if (objRS_Parent(intI).Name != "Chapter")
        strRecord = strRecord + "  " + objRS_Parent(intI).Value;
};

WScript.Echo(strRecord);

For the query properties set in this example, the strRecord variable is, for example, the following.

1.    c:\inetpub\iissamples\default


Create a Child Recordset Object for Chaptered Columns

This code subsegment uses the Value property of the "Chapter" Field object of the parent objRS_Parent Recordset object to create a child objRS_Child Recordset object.

objRS_Child = objRS_Parent.Fields("Chapter").Value


Read through the Child Recordset Object, Extracting and Outputting Values for Chaptered Columns

This code subsegment steps through the child objRS_Child Recordset object until an end of file occurs, and, for each child recordset (of filename, size, and write for this example), outputs the values in the child recordsets.

intRS_Child_Count = 0;
while (!objRS_Child.EOF) {
    intRS_Child_Count = intRS_Child_Count + 1;
    strRecord = (intRS_Parent_Count + "." + intRS_Child_Count + ".      ").slice(0,8);

    for (intJ=0; intJ<objRS_Child.Fields.Count; intJ++) {
        if (objRS_Child(intJ).Name != "Chapter") {
            if (objRS_Child(intJ).Name != strGroupBy)
                strRecord = strRecord + "  " + objRS_Child(intJ).Value;
        };
    };

    WScript.Echo(strRecord);
    objRS_Child.MoveNext;
};

For the query properties set in this code example, the strRecord variable is, for example, the following.

1.1.      learn.asp  4859  Thu Sep 17 01:48:10 PDT 1998
1.2.      exair.asp  4641  Tue Jun 16 06:22:58 PDT 1998
...


Close the Child Recordset Object

This code subsegment uses the Close method of the objRS_Child Recordset object to free the system resources of the child recordset. Setting the objRS_Child Recordset object to Null removes the child object from memory.

objRS_Child.Close;
objRS_Child = null;


Close the Parent Recordset Object

This code segment uses the Close method of the objRS_Parent Recordset object to free the system resources of the parent recordset. Setting the objRS_Parent Recordset object to Null removes the parent object from memory.

objRS_Parent.Close;
objRS_Parent = null;


Running a JScript Query

You can run a script written in JScript to submit a query (or to perform a managing task) with Windows Script Host in several ways, which include the following.

To execute a query like JScript.js as a command-prompt application

  1. Open a command window and change the directory to the path of the script.
  2. Submit the query by entering, at the command-line prompt,
    cscript jscript.js

The output of the script appears in the command window.

To execute a query like JScript.vbs as a Windows application

  1. Select Start, Run... from the Windows toolbar.
  2. Submit the query by entering the absolute path of the script in the Open dialog box or by clicking the Browse button to find the appropriate directory and select the script file.

The output of each Echo method in the script appears in a separate dialog. This is handy for debugging, but for a query with a large number of matches, you will need to close each dialog box to proceed.


Programming with Applications

Prior to Indexing Service 3.0, you typically had to perform most Indexing Service tasks using scripts with Web-server tools such as Internet Explorer or Internet Information Services (IIS). With Indexing Service 3.0 you can perform file system-oriented tasks with several programming languages as well as several scripting languages. This section includes the following topics that describe the use of the Microsoft® Visual Basic®, Visual C++®, and Visual J++® languages with the Visual Studio® development system to construct applications:

  • Programming with Visual Basic
  • Programming with Visual C++
  • Programming with Visual J++

For information about using the Visual Basic Scripting Edition (VBScript) and JScript® languages with Windows® Script Host, see Programming with Scripts. For information about using scripts with a Web-server tool, see Using Indexing Service with Web Servers. For information about ActiveX® Data Objects (ADO), see ActiveX Data Objects.


Programming with Visual Basic

Visual Basic is a productive language for creating robust applications and components. With Visual Basic and the Admin Helper, Query Helper, and ActiveX Data Objects (ADO) APIs, you can build applications that manage and query Indexing Service. This section discusses several aspects of using Visual Basic with Indexing Service and includes Visual Basic code examples. The topics include the following.

  • Using Visual Basic with Indexing Service APIs
  • Managing with Visual Basic
  • Querying with Visual Basic


Using Visual Basic with Indexing Service APIs

When you use Indexing Service APIs with Visual Basic, you can choose early binding or late binding of your application to the objects that implement the APIs. Early binding occurs at compile time and generally produces applications that execute faster. Early binding can also provide interactive development features such as object browsing and automatic class and member expansion. Late binding occurs at execution time and gives you greater flexibility in programmatically picking alternative object implementations when they are available. Late binding is also more closely compatible with the style of programming used with VBScript (see Using Indexing Service APIs from Scripts ).

Either binding method uses the prog ID of the objects in the API, and early binding can use references to type libraries. This section discusses the following topics concerning the use of early and late binding.

  • Using Prog IDs of Objects
  • Using References to Type Libraries
  • Creating Objects with Early and Late Binding


Using Prog IDs of Objects

You can declare and create objects from the Indexing Service APIs using the prog IDs of the objects. The following table lists the APIs and each object of an API with a prog ID.

API | Object | Prog ID
Admin Helper | AdminIndexServer | Microsoft.ISAdm
Query Helper | Query Utility | IXSSO.Query IXSSO.Util
ADO | Recordset | ADODB.Recordset

See Creating Objects with Early and Late Binding for details on using this information.


Using References to Type Libraries

You can declare and create objects from the Indexing Service APIs using references to type libraries. To do this you need to select the appropriate libraries in the Visual Basic development environment. The following table lists the APIs and the reference and type library for each.

API | Reference | Library
Admin Helper | Indexing Service Administration Type Library 1.0 | CIODMLib
Query Helper | ixsso Control Library | Cisso
ADO | ActiveX Data Objects (ADO) version Library, where version is one of the available versions. | ADODB

See Creating Objects with Early and Late Binding for details on using this information.


Creating Objects with Early and Late Binding

The way you programmatically create objects of the Indexing Service APIs determines whether the objects are bound early or late. To use early binding, you declare an object using its prog ID, or you first create a reference for the object to a type library. To use late binding, you declare an object as the generic Object class. This section shows how to create, either with early or late binding, the objects for the Indexing Service APIs. The topics include the following.

  • Creating Admin Helper Objects
  • Creating Query Helper Objects
  • Creating ADO Objects


Creating Admin Helper Objects

The Admin Helper API provides the AdminIndexServer, CatAdm, and ScopeAdm objects for managing the tasks, catalogs, and scopes of Indexing Service. An application can use these objects, for example, to start, pause, or stop Indexing Service; set, get, or add a catalog; or set, get, or add a scope for a catalog.

AdminIndexServer

The following table shows how to declare an AdminIndexServer object with either early or late binding.

Object Early Binding Late Binding
AdminIndexServer
Dim objAdminIS as Microsoft.ISAdm

– Or –

Reference to CIODMLib Type Library

Dim objAdminIS as Object

You subsequently can use either of the following statements to create the AdminIndexServer object.

Set objAdminIS = New Microsoft.ISAdm
Set objAdminIS = CreateObject("Microsoft.ISAdm")

CatAdm

The following table shows how to declare a CatAdm object with either early or late binding. The CatAdm object doesn't have a prog ID, so you must use a reference to the CIODMLib type library for early binding.

Object Early Binding Late Binding
CatAdm
Reference to CIODMLib Type Library

Dim objCatAdm as Object

You subsequently can use the following statement to create the CatAdm object.

Set objCatAdm = objAdminIS.GetCatalog( )

For additional ways of creating a CatAdm object, see the other methods of the AdminIndexServer object.

ScopeAdm

The following table shows how to declare a ScopeAdm object with either early or late binding. The ScopeAdm object doesn't have a prog ID, so you must use a reference to the CIODMLib type library for early binding.

Object Early Binding Late Binding
ScopeAdm
Reference to CIODMLib Type Library

Dim objScopeAdm as Object

You subsequently can use the following statement to create the ScopeAdm object.

Set objScopeAdm = objCatAdm.GetScope( )

For additional ways of creating a ScopeAdm object, see the other methods of the CatAdm object.


Creating Query Helper Objects

The Query Helper API provides the Query and Utility objects for creating and managing queries to the OLE DB Provider for Indexing Service. An application can use these objects along with an ADO Recordset object (see Creating ADO Objects) that represents the resulting records from a query.

Query

The following table shows how to declare a Query object with either early or late binding.

Object Early Binding Late Binding
Query
Dim objQuery as IXSSO.Query

– Or –

Reference to Cisso Type Library

Dim objQuery as Object

You subsequently can use either of the following statements to create the Query object.

Set objQuery = New IXSSO.Query
Set objQuery = CreateObject("IXSSO.Query")

Utility

The following table shows how to declare a Utility object with either early or late binding.

Object Early Binding Late Binding
Utility
Dim objUtility as IXSSO.Util

– Or –

Reference to Cisso Type Library

Dim objUtility as Object

You subsequently can use either of the following statements to create the Utility object.

Set objUtility = New IXSSO.Util
Set objUtility = CreateObject("IXSSO.Util")


Creating ADO Objects

The ActiveX Data Objects (ADO) API provides the Connection, Command, and Recordset objects for accessing and manipulating data from the OLE DB Provider for Indexing Service. Of these objects, an Indexing Service application typically uses just the Recordset object to represent the set of records resulting from a query submitted using the Query Helper API (see Creating Query Helper Objects).

The following table shows how to declare a Recordset object with either early or late binding.

Object Early Binding Late Binding
Recordset
Dim objRecordset as ADODB.Recordset

– Or –

Reference to ADODB Type Library

Dim objRecordset as Object

You subsequently can use either of the following statements to create the Recordset object.

Set objRecordset = New ADODB.Recordset
Set objRecordset = objQuery.CreateRecordset("ADODB.Recordset")


Managing with Visual Basic

The VBAdmin Sample illustrates several management tasks for Indexing Service using the Admin Helper API. The sample can connect to a specified computer to display the status of Indexing Service as well as to start and stop the service. The VBAdmin sample has five forms, and the following topics discuss the code for each of those forms.

  • ISAdminForm
  • AddCatalog
  • AdminCatalog
  • AdminScopes
  • ScopeInfo


ISAdminForm

The ISAdmin form is the startup form of the application. It contains the following controls.

  • A text box for entry of the name of the computer to manage.
  • Command buttons to connect to, start, and stop Indexing Service on the specified computer.
  • A tree view of the catalog structure on the specified computer.
  • A list view that shows either the status of the catalogs on the specified computer or the scope of the selected catalog. The catalog status is dynamically updated at a regular interval by the timer control.
  • An (invisible) timer control that determines the update interval of the catalog status list view.

The following topics discuss selected code segments for the ISAdmin form that perform actions specific to Indexing Service.

  • Creating the AdminIndexServer Object
  • Populating the Catalog Tree View
  • Getting the Catalog Status
  • Getting the Scopes
  • Starting and Stopping Indexing Service
  • Updating the Catalog Status


Creating the AdminIndexServer Object

This code segment creates gCiAdmin, a global AdminIndexServer object, for use in the sample using the CreateObject function. It uses the IsRunning method of the gCiAdmin AdminIndexServer object to set the appropriate states of the command buttons for starting and stopping Indexing Service. The Connect_Click procedure is called when the application starts and whenever the Connect button is clicked.

...
Public gCiAdmin As Object
...
Public Sub Connect_Click()
...
    Set gCiAdmin = Nothing

    ' Create Indexing Service Admin object.
    Set gCiAdmin = CreateObject("Microsoft.ISAdm")

    ' Set MachineName to administer IS, if not local.
    If Text1.Text <> "Local Machine" Then
        gCiAdmin.MachineName = Text1.Text
    End If

    If (gCiAdmin.IsRunning) Then
        StopCisvc.Enabled = True
        StartCisvc.Enabled = False
    Else
        StopCisvc.Enabled = False
        StartCisvc.Enabled = True
    End If
...
End Sub


Populating the Catalog Tree View

This code segment uses the FindFirstCatalog and FindNextCatalog methods of the gCiAdmin AdminIndexServer object to enumerate all Indexing Service catalogs. For each found catalog, it uses the GetCatalog method of the gCiAdmin AdminIndexServer object to create CiCatalog, a CatAdm object. It then uses the CatalogName and CatalogLocation properties of the CiCatalog CatAdm object to add the name and location of each found catalog to the tree view and list view on the form. The PopulateCatalogTreeView procedure is called when the application starts and whenever the Connect button is clicked.

Private Sub PopulateCatalogTreeView()
...
    Dim fFound As Boolean

    ' Loop through Indexing Service catalogs populating the tree control.
    fFound = gCiAdmin.FindFirstCatalog

    Dim CiCatalog As Object
    Dim lItem     As ListItem
    mTVNodeCount = 1

    While (fFound)

        mTVNodeCount = mTVNodeCount + 1

        Set CiCatalog = gCiAdmin.GetCatalog()

        Set nodX = TreeView1.Nodes.Add(mtcIndex, tvwChild, , CiCatalog.CatalogName)

        nodX.Tag = CiCatalog.CatalogLocation

        Set lItem = ListView1.ListItems.Add(, , CiCatalog.CatalogLocation)

        Set CiCatalog = Nothing

        fFound = gCiAdmin.FindNextCatalog

    Wend
...
End Sub


Getting the Catalog Status

This code segment uses the FindFirstCatalog and FindNextCatalog methods of the gCiAdmin AdminIndexServer object to enumerate all Indexing Service catalogs. For each found catalog, it uses the GetCatalog method of the gCiAdmin AdminIndexServer object to create CiCatalog, a CatAdm object. It then adds the CatalogLocation and other properties of the CiCatalog CatAdm object to the list view on the form that describes the status of each found catalog. The MakeCatalogColumns procedure is called when the application starts, whenever the Connect button is clicked, and at periodic intervals to update the catalog status information.

Private Sub MakeCatalogColumns()
...
    Dim CiCatalog As Object
    Dim lItem As ListItem
    Dim fFound As Boolean

    ' Loop, getting each catalog status info.
    fFound = gCiAdmin.FindFirstCatalog

    While (fFound)
        Set CiCatalog = gCiAdmin.GetCatalog

        Set lItem = ListView1.ListItems.Add(, , CiCatalog.CatalogLocation)

        If (gCiAdmin.IsRunning) Then
            lItem.SubItems(1) = CiCatalog.IndexSize
            lItem.SubItems(2) = CiCatalog.IsUpToDate
            lItem.SubItems(3) = CiCatalog.PendingScanCount
            lItem.SubItems(4) = CiCatalog.DocumentsToFilter
            lItem.SubItems(5) = CiCatalog.FilteredDocumentCount
            lItem.SubItems(6) = CiCatalog.TotalDocumentCount
            lItem.SubItems(7) = CiCatalog.PctMergeComplete
        End If
...
GetMoreProperties:
        Set CiCatalog = Nothing
        Set lItem = Nothing
        fFound = gCiAdmin.FindNextCatalog
    Wend

...
End Sub


Getting the Scopes

This code segment uses the GetCatalogByName method of the gCiAdmin AdminIndexServer object to create CiCatalog, a CatAdm object. It then uses the FindFirstScope and FindNextScope methods of the CiCatalog CatAdm object to enumerate all scopes of the catalog. For each found scope, it uses the GetScope method of the CiCatalog CatAdm object to create CiScope, a ScopeAdm object. It then adds the Path and other properties of the CiScope ScopeAdm object to the list view on the form that describes the scopes of a selected catalog. The MakeScopesColumns procedure is called whenever a catalog is selected in the tree view of the form.

Private Sub MakeScopesColumns(ByVal CatalogName As String)

...
    Dim CiCatalog As Object
    Dim CiScope As Object
    Dim fFound As Boolean
    Dim lItem As ListItem

    ' Get Indexing Service catalog object, then enumerate its scopes.
    Set CiCatalog = gCiAdmin.GetCatalogByName(CatalogName)

    fFound = CiCatalog.FindFirstScope
    While (fFound)
        Set CiScope = CiCatalog.GetScope()

        Set lItem = ListView1.ListItems.Add(, , CiScope.Path)

        lItem.SubItems(1) = CiScope.Alias
        lItem.SubItems(3) = CiScope.VirtualScope
        lItem.Tag = CiCatalog.CatalogName

        If CiScope.ExcludeScope Then
            lItem.SubItems(2) = False
        Else
            lItem.SubItems(2) = True
        End If

        fFound = CiCatalog.FindNextScope

        Set CiScope = Nothing
        Set lItem = Nothing
    Wend
...
End Sub


Starting and Stopping Indexing Service

These code segments use the Start and Stop methods of the gCiAdmin AdminIndexServer object to start and stop the scanning and indexing components of Indexing Service. The StartCisvc_Click procedure is called when the Start command is clicked, and the StopCisvc_Click procedure is called when the Stop command is clicked.

Private Sub StartCisvc_Click()
...
    gCiAdmin.Start  ' Start cisvc.exe service.
    Sleep (30000)   ' Give time for cisvc.exe to run.
    StopCisvc.Enabled = True
    StartCisvc.Enabled = False
...
End Sub
...
Private Sub StopCisvc_Click()
...
    gCiAdmin.Stop   ' Stop cisvc.exe service.

    StopCisvc.Enabled = False
    StartCisvc.Enabled = True
...
End Sub


Updating the Catalog Status

This code segment uses the IsRunning method of the gCiAdmin AdminIndexServer object to decide whether to update the status of the all catalogs in the list view on the form. The Timer1_Timer procedure is called when the timer event occurs, which is at five second intervals.

Private Sub Timer1_Timer()
    If (gCiAdmin.IsRunning) Then
        Call MakeCatalogColumns
    End If
End Sub


AddCatalog

The AddCatalog form creates a new catalog. This form appears when the root ("Catalog") of the catalog tree view on the ISAdminForm form is right-clicked. The AddCatalog form contains the following controls.

  • A text box for the name of the catalog.
  • A text box for the location of the catalog.
  • A command button to create the specified catalog.
  • A command button to cancel the operation.

The following code segment for the AddCatalog form creates and adds a catalog to the ISAdminForm form. It uses the AddCatalog method of the AdminIndexServer object to create CiCatalog, a CatAdm object with the catalog name and location specified on the form.

Private Sub Ok_Click()
...
    Dim CiCatalog As Object

    Set CiCatalog = ISAdminForm.gCiAdmin.AddCatalog(strName, strLocation)
...
End Sub


AdminCatalog

The AdminCatalog form performs one of several actions on a selected catalog. This form appears when the name of a catalog in the catalog tree view on the ISAdminForm form is right-clicked. The AdminCatalog form contains the following controls.

  • An option button to force a full rescan of all scopes of the catalog.
  • An option button to force a master merge of the catalog.
  • An option button to create a new directory for the catalog.
  • An option button to remove the catalog.
  • A command button to perform the selected action.
  • A command button to cancel the action.

The following topics discuss selected code segments for the AdminCatalog form that perform actions specific to Indexing Service.

  • Rescanning All Scopes
  • Forcing a Master Merge
  • Removing a Catalog


Rescanning All Scopes

This code segment uses the GetCatalogByName method of the gCiAdmin AdminIndexServer object to create CiCatalog, a CatAdm object. It then uses the FindFirstScope and FindNextScope methods of the CiCatalog CatAdm object to enumerate all scopes of the catalog. For each found scope, it uses the GetScope method of the CiCatalog CatAdm object to create CiScope, a ScopeAdm object. It then uses the Rescan method of the ScopeAdm object to rescan the scope. The ScanAllScopes procedure is called whenever the option to force a full rescan of all scopes of the catalog is selected on the form.

Private Sub ScanAllScopes()
...
    Dim CiCatalog As Object
    Dim CiScope   As Object
    Dim fFound    As Boolean

    Set CiCatalog = ISAdminForm.gCiAdmin.GetCatalogByName(Tag)

    fFound = CiCatalog.FindFirstScope
    While (fFound)
        Set CiScope = CiCatalog.GetScope()
        CiScope.Rescan True ' Full rescan.
        Set CiScope = Nothing

        fFound = CiCatalog.FindNextScope
    Wend
...
End Sub


Forcing a Master Merge

This code segment uses the GetCatalogByName method of the gCiAdmin AdminIndexServer object to create CiCatalog, a global CatAdm object. It then uses the ForceMasterMerge method of the CiCatalog CatAdm object to force a master merge of the catalog. The ForceMasterMergeMethod procedure is called whenever the option to force a master merge of the catalog is selected on the form.

Private Sub ForceMasterMergeMethod()
...
    Dim CiCatalog As Object

    Set CiCatalog = ISAdminForm.gCiAdmin.GetCatalogByName(Tag)

    CiCatalog.ForceMasterMerge
...
End Sub


Removing a Catalog

This code segment uses the RemoveCatalog method of the gCiAdmin AdminIndexServer object to remove the catalog.The RemoveCatalogMethod procedure is called whenever the option to remove the catalog is selected on the form.

Private Sub RemoveCatalogMethod()

    ISAdminForm.gCiAdmin.RemoveCatalog Tag, True

...
End Sub


AdminScopes

The AdminScopes form performs one of several actions on a selected scope of a catalog. This form appears when the name of a path in the scope tree view on the ISAdminForm form is right-clicked. The AdminScopes form contains the following controls.

  • An option button to remove the scope.
  • An option button to force a full rescan of the scope.
  • An option button to perform an incremental rescan of the scope.
  • A command button to perform the selected action.
  • A command button to cancel the action.

The following topics discuss selected code segments for the AdminScopes form that perform actions specific to Indexing Service.

  • Removing a Scope
  • Starting a Full Rescan
  • Starting an Incremental Rescan


Removing a Scope

This code segment uses the GetCatalogByName method of the gCiAdmin AdminIndexServer object to create CiCatalog, a CatAdm object. It then uses the RemoveScope method of the CiCatalog CatAdm object to remove the selected scope from the catalog.The RemoveScopeMethod procedure is called whenever the option to remove the scope is selected on the form.

Private Sub RemoveScopeMethod()
...
    Dim CiCatalog As Object

    Set CiCatalog = ISAdminForm.gCiAdmin.GetCatalogByName(CatName)

    CiCatalog.RemoveScope (ScopeName)
...
End Sub


Starting a Full Rescan

This code segment uses the GetCatalogByName method of the gCiAdmin AdminIndexServer object to create CiCatalog, a CatAdm object. It then uses the GetScopeByPath method of the CiCatalog CatAdm object to create CiScope, a ScopeAdm object for the selected scope. It then uses the Rescan method of the CiScope ScopeAdm object with True specified to perform a full rescan the selected scope. The StartFullRescan procedure is called whenever the option to force a full rescan of the scope is selected on the form.

Private Sub StartFullRescan()
...
    Dim CiCatalog As Object
    Dim CiScope As Object

    Set CiCatalog = ISAdminForm.gCiAdmin.GetCatalogByName(CatName)
    Set CiScope = CiCatalog.GetScopeByPath(ScopeName)

    CiScope.Rescan True
...
End Sub


Starting an Incremental Rescan

This code segment uses the GetCatalogByName method of the gCiAdmin AdminIndexServer object to create CiCatalog, a CatAdm object. It then uses the GetScopeByPath method of the CiCatalog CatAdm object to create CiScope, a ScopeAdm object for the selected scope. It then uses the Rescan method of the CiScope ScopeAdm object with False specified to perform an incremental rescan the selected scope. The StartIncRescan procedure is called whenever the option to perform an incremental rescan of the scope is selected on the form.

Private Sub StartIncRescan()
...
    Dim CiCatalog As Object
    Dim CiScope As Object

    Set CiCatalog = ISAdminForm.gCiAdmin.GetCatalogByName(CatName)
    Set CiScope = CiCatalog.GetScopeByPath(ScopeName)

    CiScope.Rescan False
...
End Sub


ScopeInfo

The ScopeInfo form specifies several scope properties for a new scope of a catalog. This form appears when creating a new directory using the AdminCatalog form. The ScopeInfo form contains the following controls.

  • A text box for the path of the scope.
  • A text box for the login name for the scope.
  • A text box for the password for the scope.
  • A check box that specifies excluding the path from the catalog.
  • A command button to set the specified properties.
  • A command button to cancel the action.

This code segment uses the GetCatalogByName method of the gCiAdmin AdminIndexServer object to create CiCatalog, a CatAdm object. It then uses the AddScope method of the CiCatalog CatAdm object to add the scope properties from the form to the catalog.

Private Sub Ok_Click()
...
    Dim CiCatalog As Object

    Set CiCatalog = ISAdminForm.gCiAdmin.GetCatalogByName(Tag)

    Dim vLogon As Variant
    Dim vPassword As Variant

    vLogon = strLogon.Text
    vPassword = strPassword.Text

    CiCatalog.AddScope strPath, fExcludeScope.Value, vLogon, vPassword
...
End Sub


Querying with Visual Basic

The VBQuery Sample illustrates several querying tasks for Indexing Service using the Query Helper, ActiveX Data Objects (ADO), and OLE DB Helper APIs. The VBQuery Sample has one primary form, Main, which contains the following controls.

  • A text box for the query text.
  • A text box for the selected scope of the query.
  • A command button for browsing to select the scope of the query.
  • A combo box for selecting the sort criteria. The default selection is "Rank[d]"
  • A combo box for selecting the query language. The possible selections are "Dialect 2", "SQL", and "Dialect 1". When either "Dialect" is selected, the query uses the Query Helper API. When "SQL" is selected, the query uses the ADO API.
  • A command button to begin execution of the query.
  • A command button to clear the current query settings.
  • A list view for displaying the results of the query.

The following topics discuss selected code segments from the Main form that perform actions specific to Indexing Service.

  • Locating the Catalog for the Selected Scope
  • Creating a Query Object with the Query Helper API
  • Creating a Recordset Object with the Query Helper API
  • Creating a Recordset Object with the ADO API
  • Using the Results from the Recordset Object


Locating the Catalog for the Selected Scope

This code segment uses the LocateCatalogs function of the OLE DB Helper API to locate the Indexing Service catalog for a specified scope. The first portion of the code segment declares a reference to the LocateCatalog function as an external procedure in query.dll.

...
Private Declare Function LocateCatalogs Lib "Query" Alias "LocateCatalogsA" _
      (ByVal Scope As String, _
       ByVal Bmk As Long, _
       ByVal Machine As String, _
       ByRef ccMachine As Long, _
       ByVal Catalog As String, _
       ByRef ccCatalog As Long) As Long
...

The next portion of the code segment uses the LocateCatalogs function to determine the machine and catalog given the scope.

    sc = LocateCatalogs(Scope.Text, 0, Machine, ccMachine, Catalog, ccCatalog)
    Machine = Left(Machine, ccMachine - 1)
    Catalog = Left(Catalog, ccCatalog - 1)

    If 0 = sc Then
        If ccMachine > 2 Then
            CatalogName.Text = "query://" + Machine + "/" + Catalog
        Else
            CatalogName.Text = Catalog
        End If
    Else
        CatalogName.Text = "<default>"
    End If
...

The final portion of the code segment declares the RS object variable as an Object, because it can be created in either of two ways.

...
    Dim RS As Object
...


Creating a Query Object with the Query Helper API

This code segment executes when the specified query language is either Dialect 1 or 2 of the Indexing Service query language. The first portion of the code segment uses the CreateObject function to create Q, a Query object, and to create Util, a Utility object, from the Query Helper API.

...
    If InStr(Dialect.Text, "Dialect") <> 0 Then

        ' Create the query and execute.
        Dim Q As Object
        Set Q = CreateObject("ixsso.Query")

        Dim Util As Object
        Set Util = CreateObject("ixsso.Util")
...

The next portion of the code segment sets several properties of the Q Query object, adds the scope to the query using the AddScopeToQuery method of the Utility object, and sets the selected Dialect for the query.

...
        Q.Query = QueryText.Text
        Q.Columns = "Filename, Path, Size, Write"
        If Sort.ListIndex = 2 Then
            Q.SortBy = "Rank[d]"
        Else
            Q.SortBy = Sort.Text
        End If
        Util.AddScopeToQuery Q, Scope.Text, "DEEP"

        If 0 = sc Then
            Q.Catalog = CatalogName.Text
        End If

        If StrComp(Dialect.Text, "Dialect 2") = 0 Then
            Q.Dialect = 2   ' Dialect 2.
        Else
            Q.Dialect = 1   ' Dialect 1.
        End If
...


Creating a Recordset Object with the Query Helper API

This code segment executes when the specified query language is either Dialect 1 or 2 of the Indexing Service query language. It uses the CreateRecordset method of the Query object, which creates RS — a Recordset object to represent the results of the query — and executes the query.

...
        Set RS = Q.CreateRecordset("sequential")
...


Creating a Recordset Object with the ADO API

This code segment executes when the specified query language is the SQL query language. It sets several parameters and then uses the CreateObject function to create RS, a Recordset object to represent the results of the query. It then executes the query using the Open method of the RS Recordset object.

...
        Const adOpenForwardOnly = 0
        Connect = "provider=msidxs"
        CommandText = "SELECT Filename, Path, Size, Write FROM Scope('" + Chr(34) + Scope.Text + Chr(34) + "') WHERE " + QueryText.Text + " ORDER BY " + Sort.Text
...
        Set RS = CreateObject("ADODB.Recordset")
        RS.Open CommandText, Connect, adOpenForwardOnly
...


Using the Results from the Recordset Object

The resulting RS Recordset object for the query, whether created with the Query Helper API or directly with the ActiveX Data Objects (ADO) API, provides the information in the list view of the results on the Main form. This code segment uses the MoveNext method of the RS Recordset object to read through the results and provide the selected properties to the list view control.

...
    Do Until RS.EOF
        Set mItem = ListView1.ListItems.Add()
        mItem.Text = RS("Filename")
        mItem.SubItems(1) = RS("Path")
        mItem.SubItems(2) = RS("Size")
        mItem.SubItems(3) = RS("Write")

        RS.MoveNext
    Loop
...


Programming with Visual C++

Visual C++ is the most powerful development language for Windows. With Visual C++ and the OLE DB Provider API or the OLE DB Helper API, you can build high-performance applications that manage and query Indexing Service. This section describes the use of Visual C++ with Indexing Service and includes Visual C++ code examples. The topics include the following.

  • Using Visual C++ with Indexing Service APIs
  • Managing with Visual C++
  • Querying with Visual C++


Using Visual C++ with Indexing Service APIs

When you use Indexing Service APIs with Visual C++, you typically have a choice of using the OLE DB Provider API or the OLE DB Helper API. For the fastest execution, you usually will use the OLE DB Provider API. For information about using it with Indexing Service, see Using OLE DB Provider for Indexing Service.

For easier programming, you usually use the OLE DB Helper API or a combination of that API and the OLE DB Provider API. With the OLE DB Helper API, you need to include the header file ntquery.h in any source files in which you use the Helper functions. You also need to link the ntquery.lib library with your application.

When you use any programming elements from the OLE DB Provider API, you may also need to include the following header files.

  • oledberr.h
  • oledb.h
  • cmdtree.h


Managing with Visual C++

With Visual C++ and the OLE DB Helper API, you can locate the appropriate computer and catalog for a specified scope, query the state of a selected catalog, and control the state of a selected catalog.

The ChgState Sample illustrates using the OLE DB Helper API to manage Indexing Service. The following code segment uses the CICAT_* constants and the SetCatalogState function to get or set the catalog state as specified by the input arguments to the application.

...
    if ( !wcscmp( pwcsAction, L"RO" ) )          // ReadOnly
        dwNewState = CICAT_READONLY;
    else if ( !wcscmp( pwcsAction, L"RW" ) )     // ReadWrite
        dwNewState = CICAT_WRITABLE;
    else if ( !wcscmp( pwcsAction, L"Stop" ) )   // Stop
        dwNewState = CICAT_STOPPED;
    else if ( !wcscmp( pwcsAction, L"GetState" ) ) // Get the current state
        dwNewState = CICAT_GET_STATE;
    else
    {
        fprintf( stderr, "Action undefined!\n" );
        exit(-1);
    }

    // call the API
    sc = SetCatalogState ( pwcsCatalog,
                           pwcsMachine,
                           dwNewState,
                           &dwOldState );
...


Querying with Visual C++

With Visual C++, the OLE DB Helper API, and optionally the OLE DB Provider API, you can construct, execute, and retrieve the results of queries.

The Simple Sample (QSample) illustrates use of the OLE DB Helper API and the OLE DB Provider API to construct and execute a query with Indexing Service. Using the OLE DB Helper API simplifies construction of a command tree for a query. The Simple Sample uses the CIMakeICommand, CITextToFullTreeEx, LocateCatalogs, and CIState functions in addition to the ICommandTree, ICommand, IAccessor, and IRowset interfaces. For more complex examples that use the OLE DB Provider exclusively and that require using a data source object and a session object to construct a command tree, see the AdvQuery Sample and the CatQ Sample.

The following topics discuss selected code segments for the Simple Sample (from the QSample.cxx file) that perform actions specific to Indexing Service. For instructions about how to install the complete code of the Simple Sample, refer to Installing the Samples.

  • Defining a Template for Managing Ownership of Interfaces
  • Creating and Executing a Query
  • Getting the Query Results for Display
  • Looking Up a Machine and Catalog for a Scope
  • Displaying the Status of a Catalog


Defining a Template for Managing Ownership of Interfaces

The following code segment defines a template to aid in the management of interface ownership. The sample uses this template with the ICommand, ICommandTree, IRowset , IAccessor, and other interfaces.

template<class T> class XInterface
{
public:
    XInterface( T * p = 0 ) : _p( p ) {}
    ~XInterface() { if ( 0 != _p ) _p->Release(); }
    T * operator->() { return _p; }
    T * GetPointer() const { return _p; }
    IUnknown ** GetIUPointer() { return (IUnknown **) &_p; }
    T ** GetPPointer() { return &_p; }
    void ** GetQIPointer() { return (void **) &_p; }
    T * Acquire() { T * p = _p; _p = 0; return p; }
    BOOL IsNull() { return ( 0 == _p ); }

private:
    T * _p;
};


Creating and Executing a Query

The following code segments from the IssueQuery function of the sample create and execute a query. The function first declares an ICommand interface and uses the CIMakeICommand function of the OLE DB Helper API to get a pointer to an ICommand interface for the specified scope, catalog, and machine properties.

...
    XInterface<ICommand> xICommand;
    HRESULT hr = CIMakeICommand( xICommand.GetPPointer(),  // result
                                 1,                        // 1 scope
                                 &dwScopeFlags,            // scope flags
                                 &pwcQueryScope,           // scope path
                                 &pwcQueryCatalog,         // catalog
                                 &pwcQueryMachine );       // machine
...

The function next declares an ICommandTree interface and queries the ICommand interface for a pointer to an ICommandTree interface.

...
    XInterface<ICommandTree> xICommandTree;
    hr = xICommand->QueryInterface( IID_ICommandTree,
                                    xICommandTree.GetQIPointer() );
...

Then the function declares a DBCOMMANDTREE structure for the command tree of the query and uses the CITextToFullTreeEx function to create the command tree structure using previously set query properties.

...
    DBCOMMANDTREE * pTree;
    hr = CITextToFullTreeEx( pwcQueryRestriction, // the query itself
                             ulDialect,           // query dialect
                             pwcColumns,          // columns to return
                             pwcSort,             // sort order, may be 0
                             0,                   // reserved
                             &pTree,              // resulting tree
                             0,                   // no custom properties
                             0,                   // no custom properties
                             lcid );              // default locale
...

The function next uses the SetCommandTree method of the ICommandTree interface to set the command tree in the ICommandTree interface.

...
    hr = xICommandTree->SetCommandTree( &pTree,
                                        DBCOMMANDREUSE_NONE,
                                        FALSE );
...

The function finally declares an IRowset interface to represent the results of the query and uses it with the Execute method of the ICommand interface to execute the query.

...
    XInterface<IRowset> xIRowset;
    hr = xICommand->Execute( 0,            // no aggregating IUnknown
                             IID_IRowset,  // IID for interface to return
                             0,            // no DBPARAMs
                             0,            // no rows affected
                             xIRowset.GetIUPointer() ); // result
...


Getting the Query Results for Display

The following code segments from the IssueQuery function of the sample get the results of the query for subsequent display. The function first declares an IAccessor interface and uses the QueryInterface method of the IRowset interface to get a pointer to an IAccessor interface for the query's rowset.

...
    XInterface<IAccessor> xIAccessor;
    hr = xIRowset->QueryInterface( IID_IAccessor,
                                   xIAccessor.GetQIPointer() );
...

After determining the number of columns in the result and binding each column with the appropriate buffer information, the function declares a handle to an accessor and uses the CreateAccessor method of the IAccessor interface to create the accessor from the bindings.

...
    HACCESSOR hAccessor;
    hr = xIAccessor->CreateAccessor( DBACCESSOR_ROWDATA, // rowdata accessor
                                     cColumns,           // # of columns
                                     xBindings.Get(),    // columns
                                     0,                  // ignored
                                     &hAccessor,         // result
                                     0 );                // no status
...

The function finally uses the GetData method of the IRowset interface to get the data for subsequent display.

...
            for ( DBCOUNTITEM iRow = 0; iRow < cRowsReturned; iRow++ )
            {
                HRESULT hr2 = xIRowset->GetData( aHRow[iRow],   // hrow being accessed
                                                 hAccessor,     // accessor to use
                                                 xData.Get() ); // resulting data
...
            }
...


Looking Up a Machine and Catalog for a Scope

The following code segment from the LookupCatalog function of the sample uses the LocateCatalogs function of the OLE DB Helper API to find a catalog and machine matching the specified scope.

...
    HRESULT hr = LocateCatalogs( pwcScope,       // scope to lookup
                                 0,              // go with the first match
                                 pwcMachine,     // returns the machine
                                 &cwcMachine,    // buffer size in/out
                                 pwcCatalog,     // returns the catalog
                                 &cwcCatalog );  // buffer size in/out
...


Displaying the Status of a Catalog

The following code segment is the DisplayStatus function of the sample, which uses the CISTATE structure, the CI_STATE_* constants, and the CIState function of the OLE DB Helper API to determine the status of the specified catalog. It outputs the status using the sample's DisplayStat function and the IDS_* strings defined in QSample.rc.

HRESULT DisplayStatus(
    WCHAR const * pwcCatalog,
    WCHAR const * pwcMachine,
    LCID          lcid )
{
    CI_STATE state;
    state.cbStruct = sizeof state;

    DisplayStat( pwcMachine, IDS_STAT_MACHINE );
    DisplayStat( pwcCatalog, IDS_STAT_CATALOG );

    HRESULT hr = CIState( pwcCatalog, pwcMachine, &state );

    if ( SUCCEEDED( hr ) )
    {
        DisplayStat( state.cTotalDocuments, IDS_STAT_TOTALDOCUMENTS );
        DisplayStat( state.cFreshTest, IDS_STAT_FRESHTEST );
        DisplayStat( state.cFilteredDocuments, IDS_STAT_FILTEREDDOCUMENTS );
        DisplayStat( state.cDocuments, IDS_STAT_DOCUMENTS );
        DisplayStat( state.cSecQDocuments, IDS_STAT_SECQDOCUMENTS );
        DisplayStat( state.cUniqueKeys, IDS_STAT_UNIQUEKEYS );
        DisplayStat( state.cWordList, IDS_STAT_WORDLIST );
        DisplayStat( state.cPersistentIndex, IDS_STAT_PERSISTENTINDEX );
        DisplayStat( state.cQueries, IDS_STAT_QUERIES );
        DisplayStat( state.dwIndexSize, IDS_STAT_INDEXSIZE );
        DisplayStat( state.dwPropCacheSize / 1024, IDS_STAT_PROPCACHESIZE );

        DisplayStat( ( state.eState & CI_STATE_SCANNING ) ?
                     state.cPendingScans : 0,
                     IDS_STAT_SCANS );

        const DWORD ALL_CI_MERGE = ( CI_STATE_SHADOW_MERGE |
                                     CI_STATE_ANNEALING_MERGE |
                                     CI_STATE_INDEX_MIGRATION_MERGE |
                                     CI_STATE_MASTER_MERGE |
                                     CI_STATE_MASTER_MERGE_PAUSED );

        if ( 0 != ( ALL_CI_MERGE & state.eState ) )
        {
            UINT idStr;
            if ( state.eState & CI_STATE_SHADOW_MERGE )
                idStr = IDS_STAT_MERGE_SHADOW;
            else if ( state.eState & CI_STATE_ANNEALING_MERGE )
                idStr = IDS_STAT_MERGE_ANNEALING;
            else if ( state.eState & CI_STATE_INDEX_MIGRATION_MERGE )
                idStr = IDS_STAT_MERGE_INDEX_MIGRATION;
            else if ( state.eState & CI_STATE_MASTER_MERGE )
                idStr = IDS_STAT_MERGE_MASTER;
            else
                idStr = IDS_STAT_MERGE_MASTER_PAUSED;

            DisplayStat( state.dwMergeProgress, idStr );
        }

        if ( CI_STATE_READ_ONLY & state.eState )
            DisplayStat( IDS_STAT_READ_ONLY );
        if ( CI_STATE_RECOVERING & state.eState )
            DisplayStat( IDS_STAT_RECOVERING );
        if ( CI_STATE_LOW_MEMORY & state.eState )
            DisplayStat( IDS_STAT_LOW_MEMORY );
        if ( CI_STATE_HIGH_IO & state.eState )
            DisplayStat( IDS_STAT_HIGH_IO );
        if ( CI_STATE_BATTERY_POWER & state.eState )
            DisplayStat( IDS_STAT_BATTERY_POWER );
        if ( CI_STATE_USER_ACTIVE & state.eState )
            DisplayStat( IDS_STAT_USER_ACTIVE );
        if ( CI_STATE_STARTING & state.eState )
            DisplayStat( IDS_STAT_STARTING );
        if ( CI_STATE_READING_USNS & state.eState )
            DisplayStat( IDS_STAT_READING_USNS );
    }
    else
    {
        DisplayError( IDS_CANTDISPLAYSTATUS, pwcCatalog, hr, lcid );
    }

    return hr;
}


Programming with Visual J++

Visual J++ is Microsoft's implementation of the Java language. It can build console or Windows applications to manage and query Indexing Service. This section discusses several aspects of using Visual J++ with Indexing Service and includes code examples that use the ActiveX Data Objects API. The topics include the following.

  • Using Visual J++ with Indexing Service APIs
  • Querying with Visual J++
  • Running a Visual J++ Query


Using Visual J++ with Indexing Service APIs

To use the ActiveX Data Objects (ADO) API with Visual J++, you need to import the appropriate Windows Foundation Classes (WFC) for Java packages. The WFC packages provide the following.

  • Base classes that encapsulate Windows application operations
  • Base classes for the core component model.
  • ADO Java classes that enable data access and data binding.
  • Core Windows native API support classes in WFC.

To import these packages, you include the following statements in your application.

import com.ms.wfc.*;
import com.ms.wfc.core.*;
import com.ms.wfc.data.*;
import com.ms.com.*;

To use the ADO API, you must specify "provider=MSIDXS" when creating an ADO Recordset object.


Querying with Visual J++

The VJQuery Sample executes an Indexing Service query using the SQL language and the ActiveX Data Objects API. Depending on the parameters specified on the command line when the sample is run, it executes one of three different SQL queries.

  • If the command line doesn't specify a query, it executes the following default query.
    SELECT Filename, Size, Write, Path
  FROM SCOPE('DEEP TRAVERSAL OF "\"')
  WHERE CONTAINS('"Indexing Service"')
  • If the command line doesn't contain the -s parameter, but includes query text for a WHERE clause, it executes the following query.
    SELECT Filename, Size, Write, Path
  FROM SCOPE('DEEP TRAVERSAL OF "\"')
  WHERE where-clause-text
  • If the command line contains the -s parameter, it executes whatever complete SQL statement the command line contains.

The Query.java module defines the public class Query, which encapsulates setting up, executing, and displaying a query. The following topics discuss the methods of the Query class that involve Indexing Service in the sample.

  • Query.Execute in Query.java
  • Query.Display in Query.java


Query.Execute in Query.java

This code segment defines the Execute method of the Query class.

    void Execute()
    {
        m_RS = new Recordset();
        m_RS.Open( m_SqlText,
                   "provider=MSIDXS",
                   AdoEnums.CursorType.STATIC,
                   AdoEnums.LockType.BATCHOPTIMISTIC,
                   AdoEnums.CommandType.TEXT );
    }

The first executable line of the method creates a new ADO Recordset object, m_RS. The next line executes the query in the m_SqlText member with the Open method of the m_RS Recordset object. The first parameter of the Open method is the text of the SQL query. The second parameter sets the data provider to Indexing Service. The subsequent parameters, which are ADO enumerated constants, define the properties of the query.


Query.Display in Query.java

This code segment displays the results of the query. It gets the count of the number of fields in the m_RS Recordset object and then reads through the Recordset object, printing the values of the fields, until it encounters an end of file.

    void Display( PrintStream PS )
...
            int cFields = m_RS.getFields().getCount();

            while ( !m_RS.getEOF() )
            {
                for ( int j = 0; j < cFields; j++ )
                    PS.print( m_RS.getFields().getItem(j).getValue() + "\t" );

                PS.print( "\n" );

                m_RS.moveNext();
            }
...


Running a Visual J++ Query

You can run a Visual J++ application to submit a query in several ways, which include the following.

To execute a Visual J++ query for a command-prompt application

  1. Set the PATH environment variable to include "D:\mssdk\Bin", where D: is the drive on which you installed the Platform SDK.
  2. Open a command window and change the directory to the path of the Visual J++ application.
  3. Submit a query by entering, at the command-line prompt,
    jview /p /cp:p "<JAVAPACKAGES>" query-application-command

    where query-application-command is the command line for the application. For appropriate values of query-application-command for the VJQuery Sample, see the User's Guide for that sample.

    The output of the script appears in the command window in which you run Jview.

To execute a Visual J++ query for a Windows application

  1. Select Start, Run... from the Windows toolbar.
  2. Submit the query by entering
    wjview /p /cp:p "<JAVAPACKAGES>" query-application-command

    where query-application-command is the command line for the application.

    Wjview spawns a separate window process for windows-based applications, and is inappropriate for Visual J++ command applications (like VJQuery) that require input from or output to a command window.


File System Samples

The file system samples illustrate application programming and script writing using the OLE DB Provider for Indexing Service API, OLE DB Helper API, Microsoft® ActiveX® Data Objects (ADO) API, Admin Helper API, and Query Helper API. The following samples are included in the Platform SDK.

  • AdvQuery Sample. A complex example of querying using the OLE DB Provider API.
  • CatQ Sample. An example of querying using the OLE DB Provider API.
  • ChgState Sample. An example of managing the status of Indexing Service using the OLE DB Helper API.
  • Simple Sample. A simple example of querying using the OLE DB Helper API.
  • SQuery Sample. A set of three scripts that are examples of managing and querying using the Helper APIs.
  • VBAdmin Sample. An example of managing Indexing Service using the Admin Helper API.
  • VBQuery Sample. An example of querying using the ADO and Query Helper APIs and the Indexing Service query languages.
  • VJQuery Sample. An example of querying using the ADO API and SQL.

The section on Web server samples contains additional samples of scripting that are Web server-oriented.


AdvQuery Sample

AdvQuery is an example of a command-line application written in C++ that executes a query using OLE DB Provider interfaces such as ICommand and ICommandTree. It shows how to specify a catalog, machine name, and scope. It can also display the OLE DB command tree for the query.

Path

Source: mssdk\samples\winbase\indexing\AdvQuery\

User's Guide

To build the sample

  1. Set the Lib environment variable to "D:\mssdk\Lib;%Lib%" and the Include environment variable to "D:\mssdk\Include;%Include%", where D: is the drive on which you installed the Platform SDK.
  2. Correctly set the CPU environment variable to, for example, "i386".
  3. Open a command window and change the directory to the source path of the sample.
  4. Build the sample by entering, at the command-line prompt, "nmake".

To issue a query to Indexing Service using the sample

  1. Open a command window and change the directory to the path of the built sample.
  2. Formulate a query that you know will succeed. You need to know the machine, catalog, scope, and query text.
  3. Submit the query by entering, at the command-line prompt,
    advquery <query> [/c:<catalog>] [/m:<machine>] [/s:<scope>] [/d]

    where the values of the command-line parameters are the following.
    Value | Meaning
    <query> | is a query in an Indexing Service query language
    <catalog> | is the name of the catalog (default is "system")
    <machine> | is the name of the machine (default is ".")
    <scope> | is the root path (default is entire catalog)
    /d | displays the DBCOMMANDTREE (default is don't display)

Programming Notes

The sample prints the rank, size, and path of each file that matches the query. The query results are sorted by rank (how well the file matches the query).

This sample is more complex than the Simple (QSample) sample because it creates a command tree and use the low-level ICommandTree interface instead of using the OLE DB Helper functions CICreateCommand and CITextToFullTree.

Parameters

The <query> parameter can be a word or a phrase. Files that contain the word or phrase are listed in the result. To include a space in a query, enclose the query in quotes.

The <catalog> parameter is the name of the catalog to be queried. The default is "system", which is the default catalog installed with Windows® 2000. Additional catalogs can be created with the Indexing Service snap-in of the Microsoft Management Console (MMC).

The <machine> parameter is the name of the machine on which the query will be executed. The default is ".", which is the local machine. Machine names should not be preceded by two backslashes.

The <scope> parameter is the file path where files must be located in order to be included in the results. The default is "\", which includes all scopes in the catalog.

The "/d" parameter displays the DBCOMMANDTREE structure built to execute the query.

Examples

advquery foo
Finds all files in the "system" catalog on the local computer that contain the word "foo".
advquery "foo bar" "/s:c:\my directory"
Finds all files in the "system" catalog on the local computer that contain the phrase "foo bar" that are in the specified directory or any subdirectory.
advquery foo /m:SERVERNAME
Finds all files in the "system" catalog on computer "servername" that contain the word "foo".


CatQ Sample

The CatQ sample is an example Windows application written in C++ that executes queries using the OLE DB Provider API. The queries are on the catalog of the local computer and restrict the scope to text files in the Platform SDK by using the MSSDK environment variable.

Path

Source: mssdk\samples\winbase\indexing\CatQ\

User's Guide

To build the sample

  1. Set the Lib environment variable to "D:\mssdk\Lib;%Lib%" and the Include environment variable to "D:\mssdk\Include;%Include%", where D: is the drive on which you installed the Platform SDK.
  2. Correctly set the CPU environment variable to, for example, "i386".
  3. Open a command window and change the directory to the source path of the sample.
  4. Build the sample by entering, at the command-line prompt, "nmake".

To execute queries using the sample

  1. On the Windows toolbar, select Start, Run, and either enter the path to the executable file that you built in the Open text box of the Run dialog box or select Browse to find the path.
  2. Select OK in the Run dialog box. This starts the sample and opens its window.
  3. Enter a value for the Text to search for and new values for the Machine, Catalog, and Scope in the text boxes, or accept the default values.
  4. Click Find Now to execute the query. The resulting matches appear in the list in the lower part of the window.

Programming Notes

When the CatQ sample starts, it checks the status of Indexing Service and starts it if it is not running.

In the status bar at the bottom of the CatQ sample window, the progress of indexing is displayed as a fraction and as a blue "progress bar." The numerator and denominator of this fraction are read as performance registry counters, which are written out by the CiSvc.exe process.

The denominator in the progress display is the total number of files that Indexing Service must index in order for the catalog to be up to date. Unfortunately, this value is not known instantly at the startup of Indexing Service. Moreover, it typically grows over time as the numerator grows. For this reason, the progress percentage can decrease even as Indexing Service makes progress. That is, Indexing Service finds new files to index as fast as it indexes files that are in its existing list.


ChgState Sample

The ChgState example is a command-line application written in C++ that can either report the current state of a catalog or change the state of the catalog using the SetCatalogState function of the OLE DB Helper API.

Path

Source: mssdk\samples\winbase\indexing\ChgState\

User's Guide

To build the sample

  1. Set the Lib environment variable to "D:\mssdk\Lib;%Lib%" and the Include environment variable to "D:\mssdk\Include;%Include%", where D: is the drive on which you installed the Platform SDK.
  2. Correctly set the CPU environment variable to, for example, "i386".
  3. Open a command window and change the directory to the source path of the sample.
  4. Build the sample by entering, at the command-line prompt, "nmake".

To find or change the catalog state using the sample

  1. Open a command window and change the directory to the path of the built sample.
  2. Submit a catalog state command by entering, at the command-line prompt,
    chgstate /a:<action> [/c:<catalog>] [/m:<machine>]

    where the values of the command-line parameters are the following.
    Value | Meaning
    <action> is a catalog state action; one of the following:

    RO sets read-only (queries only)
    RW sets read/write (queries and indexing)
    Stop sets stopped (no queries or indexing)
    GetState gets current state only
    <catalog> | is the name of the catalog (default is "system")
    <machine> | is the name of the machine (default is ".")

Programming Notes

The previous state of the specified catalog is always returned in the dwOldState parameter of the SetCatalogState function and printed by the sample.

The state of the catalog will change to the new, specified state if that state does not violate read-only rules for the catalog. If the catalog resides on a read-only medium, the catalog is specified as read-only in the registry, or if the file cicat.hsh is set to read-only, the catalog is set to read-only even when the read/write state is requested.

Parameters

The <action> parameter is the action desired. Four actions are possible:

  • RO (Read-only): Queries are allowed, but no indexing occurs.
  • RW (Read/write): Queries are allowed and indexing occurs.
  • Stop (Stopped): Stops catalog completely (no queries, no indexing).
  • GetState (Get state): Gets the current state of a catalog only. The catalog state prior to any specified action is always returned.

The <catalog> parameter is the name of the catalog on which to perform the action. The default value of the <catalog> parameter is "system", which is the default catalog installed with Windows 2000. Additional catalogs can be created with the Indexing Service snap-in of the Microsoft Management Console (MMC).

The <machine> parameter is the name of the computer on which the request is executed. The default is ".", which is the local computer. Computer names should not be preceded by two backslashes.

Examples

chgstate /a:RW /c:system
Change the "system" catalog on the local computer to the Read/write state.
chgstate /a:GetState /m:SERVERNAME
Get the current state of the "system" catalog on machine SERVERNAME.
chgstate /a:RO /c:CATALOGNAME /m:SERVERNAME
Set the catalog CATALOGNAME on machine SERVERNAME to the Read-only state. (The catalog can be queried, but indexing is stopped.)


Simple Sample

The Simple sample (QSample) is an example command-line application written in C++ that executes a query using the OLE DB Helper API functions CICreateCommand and CITextToFullTree to simplify the coding needed to create a query to an Indexing Service catalog.

Path

Source: mssdk\samples\winbase\indexing\Simple\

User's Guide

To build the sample

  1. Set the Lib environment variable to "D:\mssdk\Lib;%Lib%" and the Include environment variable to "D:\mssdk\Include;%Include%", where D: is the drive on which you installed the Platform SDK.
  2. Correctly set the CPU environment variable to, for example, "i386".
  3. Open a command window and change the directory to the source path of the sample.
  4. Build the sample by entering, at the command-line prompt, "nmake".

To execute queries using the sample

  1. Open a command window and change the directory to the path of the built sample.
  2. Formulate a query that you know will succeed. You need to know the query text and, optionally, values for the machine, catalog, scope, columns, query language dialect, locale, sort order, and other arguments (see the following list).
  3. Submit the query by entering, at the command-line prompt,
    qsample <query> [arguments]

    where the value of the command-line parameter <query> is an Indexing Service query, and the arguments can include the following.
    Value | Meaning
    /c:<catalog> | is the name of the catalog. Default is SYSTEM.
    /d | displays the DBCOMMANDTREE structure for the command tree. Default is don't display.
    /e:<locale> | is the ISO locale identifier; for example, EN-US. Default is system locale.
    /f:(+|-) | + or - specifies forcing use of the index. Default is "+" to force use of the index.
    /g | specifies forcing a master merge.
    /i:<inputfile> | specifies an input file to read with queries, one per line.
    /j | specifies to return just files in the scope path, and not subdirectories.
    /l:<dialect> | specifies the query language dialect, 1 or 2. Default is 1.
    /m:<machine> | is the name of the computer. Default is the local computer.
    /o:<columns> | is the output column list. Default is path.
    /p:<scope> | is the scope path of the query, absolute or relative.
    /q | specifies to execute quietly. Display only query results.
    /r:# | is the number of times to repeat the command.
    /s:<sort> | is the sort column list. Default is none. For example: write[d]. Append [a] for ascending (default) or [d] for descending.
    /t | specifies to display catalog statistics.
    /u | specifies to check if the catalog is up to date.
    /x:<maxhits> | is the maximum number of hits to retrieve. Default is no limit.

Programming Notes

This sample is simpler than the AdvQuery sample because it uses the OLE DB Helper functions CICreateCommand and CITextToFullTree instead of creating a command tree and using the low-level ICommandTree interface.

Arguments

You can specify the following columns with the /o argument.

  • attrib
  • create
  • directory
  • docauthor
  • dockeywords
  • doclastauthor
  • docsubject
  • doctitle
  • fileindex
  • filename
  • hitcount
  • path
  • rank
  • size
  • vpath
  • workid
  • write

You can specify the following locales with the /e argument.

  • af
  • ar ar-ae ar-bh ar-dz ar-eg ar-iq ar-jo ar-kw ar-lb

    ar-ly ar-ma ar-om ar-qa ar-sa ar-sy ar-tn ar-ye

  • be bg ca cs da
  • de de-at de-ch de-li de-lu
  • en en-au en-bz en-ca en-gb en-ie en-jm en-nz en-tt

    en-us en-za

  • es es-ar es-bo es-c es-co es-cr es-do es-ec es-gt

    es-hn es-mx es-ni es-pa es-pe es-pr es-py es-sv

    es-uy es-ve

  • et eu fa fi fo
  • fr fr-be fr-ca fr-ch fr-lu
  • gd gd-ie
  • he hi hr hu in is
  • it it-ch
  • ja ji ko ko lt lv mk ms mt n neutr
  • nl-be
  • no p
  • pt pt-br
  • rm
  • ro ro-mo
  • ru ru-mo
  • s sb sk sq sr
  • sv sv-fi
  • sx sz th tn tr ts uk ur ve vi xh
  • zh-cn zh-hk zh-sg zh-tw
  • zu

Example Queries

qsample mango /o:size,path
Finds all files in the "system" catalog on the local computer that contain the word "mango" and outputs the size and path values.
qsample "peach and not apple" /s:rank[d] /p:.
Finds all files in the "system" catalog on the local computer with the relative path "." that contain the word "peach" but not the word "apple" and outputs the path value sorted in order of increasing rank.
qsample "@size > 1000000" /o:size,path /s:size[a] /m:dogfood
Finds all files in the "system" catalog on the computer "dogfood" whose size is greater than 1000000 bytes and outputs the size and path values sorted in order of increasing size.
qsample "@docauthor joe" /o:docauthor,path /s:docauthor,path
Finds all files in the "system" catalog on the local computer whose docauthor property is "joe" and outputs the docauthor and path values sorted in order of ascending docauthor and then ascending path.
qsample apricot /p:c:\\files
Finds all files in the "system" catalog on the local computer with an absolute scope of c:\files and outputs the path in unsorted order.
qsample /m:index1 /c:sources pear
Finds all files in the "sources" catalog on the computer "index1" containing the word "pear" and outputs the path value in unsorted order.


SQuery Sample

The SQuery sample consists of three scripts that execute using Windows Script Host. VBSQuery is written in VBScript and performs a simple query. JSQuery is a translation of VBSQuery to JScript. QSample is written in VBScript and functions similarly to the C++ Simple sample with managing and querying functionality.

Path

Source: mssdk\samples\winbase\indexing\SQuery\

User's Guide

To execute queries using the VBSQuery.vbs or JSQuery.js scripts

  1. Open a command window and change the directory to the path of the sample scripts.
  2. Submit a fixed query by entering, at the command-line prompt,
    cscript vbsquery.vbs

    or

    cscript jsquery.js

To execute queries using the QSample.vbs script

  1. Open a command window and change the directory to the path of the sample scripts.
  2. Formulate a query that you know will succeed. You need to know the query text and, optionally, values for the machine, catalog, scope, columns, query language dialect, locale, sort order, and other arguments (see the following list).
  3. Submit a query by entering, at the command-line prompt,
    cscript qsample.vbs <query> [arguments]

    where the value of the command-line parameter <query> is an Indexing Service query, and the arguments can include the following.
    Value | Meaning
    /c:<catalog> | is the name of the catalog. Default is SYSTEM.
    /e:<locale> | is ISO locale identifier; for example, EN-US. Default is system locale.
    /f:(+|-) | + or - specifies forcing use of the index. Default is +.
    /g | specifies forcing a master merge.
    /i:<inputfile> | specifies an input file to read with queries, one per line.
    /j | specifies to return just files in the scope path, and not subdirectories.
    /l:<dialect> | specifies the query language dialect, 1 or 2. Default is 1.
    /m:<machine> | is the name of the computer. Default is the local computer.
    /o:<columns> | is the output column list. Default is path.
    /p:<scope> | is the scope path of the query, absolute or relative.
    /q | specifies to execute quietly. Display only query results.
    /r:# | is the number of times to repeat the command.
    /s:<sort> | is the sort column list. Default is none. For example: write[d]. Append [a] for ascending (default) or [d] for descending.
    /t | specifies to display catalog statistics.
    /u | specifies to check if the catalog is up to date.
    /x:<maxhits> | is the maximum number of hits to retrieve. Default is no limit.

Programming Notes

VBSQuery and JSQuery

The query executed by these scripts is embedded in the script. The query uses the Query Helper API and consists of the following:

  • Columns = file name, directory, size, write
  • Query = #filename *.asp
  • GroupBy = directory[a]
  • Catalog = system
  • CiScope = \
  • CiFlags = DEEP
  • OptimizeFor = recall,hitcount
  • AllowEnumeration = TRUE
  • MaxRecords = 20000

The JSQuery script is a direct translation of the VBSQuery script to JScript. Its output is identical to that of VBSQuery except for a difference in the way dates and times are represented.

QSample

QSample uses the Query Helper API and is much more general and flexible than the VBSQuery and JSQuery scripts. It also uses the Admin Helper API to perform some managing tasks.

Arguments

You can specify the following columns with the /o argument.

  • attrib
  • create
  • directory
  • docauthor
  • dockeywords
  • doclastauthor
  • docsubject
  • doctitle
  • fileindex
  • filename
  • hitcount
  • path
  • rank
  • size
  • vpath
  • workid
  • write

You can specify the following locales with the /e argument.

  • af
  • ar ar-ae ar-bh ar-dz ar-eg ar-iq ar-jo ar-kw ar-lb

    ar-ly ar-ma ar-om ar-qa ar-sa ar-sy ar-tn ar-ye

  • be bg ca cs da
  • de de-at de-ch de-li de-lu
  • en en-au en-bz en-ca en-gb en-ie en-jm en-nz en-tt

    en-us en-za

  • es es-ar es-bo es-c es-co es-cr es-do es-ec es-gt

    es-hn es-mx es-ni es-pa es-pe es-pr es-py es-sv

    es-uy es-ve

  • et eu fa fi fo
  • fr fr-be fr-ca fr-ch fr-lu
  • gd gd-ie
  • he hi hr hu in is
  • it it-ch
  • ja ji ko ko lt lv mk ms mt n neutr
  • nl-be
  • no p
  • pt pt-br
  • rm
  • ro ro-mo
  • ru ru-mo
  • s sb sk sq sr
  • sv sv-fi
  • sx sz th tn tr ts uk ur ve vi xh
  • zh-cn zh-hk zh-sg zh-tw
  • zu

Example Queries

cscript qsample.vbs mango /o:size,path
Finds all files in the "system" catalog on the local computer that contain the word "mango" and outputs the size and path values.
cscript qsample.vbs "peach and not apple"" /s:rank[d] /p:.
Finds all files in the "system" catalog on the local computer with the relative path "." that contain the word "peach" but not the word "apple" and outputs the path value sorted in order of increasing rank.
cscript qsample.vbs "@size > 1000000"" /o:size,path /s:size[a] /m:dogfood
Finds all files in the "system" catalog on the computer "dogfood" whose size is greater than 1000000 bytes and outputs the size and path values sorted in order of increasing size.
cscript qsample.vbs "@docauthor joe"" /o:docauthor,path /s:docauthor,path
Finds all files in the "system" catalog on the local computer whose docauthor property is "joe" and outputs the docauthor and path values sorted in order of ascending docauthor and then ascending path.
cscript qsample.vbs apricot /p:c:\\files
Finds all files in the "system" catalog on the local computer with an absolute scope of c:\files and outputs the path in unsorted order.
cscript qsample.vbs /m:index1 /c:sources pear
Finds all files in the "sources" catalog on the computer "index1" containing the word "pear" and outputs the path value in unsorted order.


VBAdmin Sample

The VBAdmin sample is an example Windows application written in Visual Basic that illustrates how to administer Indexing Service using the AdminIndexServer, CatAdm, and ScopeAdm automation objects of the Admin Helper API.

Path

Source: mssdk\samples\winbase\indexing\VBAdmin\

User's Guide

To build and run the sample

  1. In the Visual Basic development environment, open the VBAdmin.vbp project in the source path of the sample.
  2. In the File menu, click Make VBAdmin.exe.
  3. In the Make Project dialog box, click OK.
  4. In the Run menu, click Start.

To start or stop Indexing Service using the sample

  • Click Start to start Indexing Service if it isn't running.
  • Click Stop to stop Indexing Service if it is running.

To create a new catalog using the sample

  1. In the tree view of the catalog structure, right-click Catalogs.
  2. In the Create New Catalog dialog box, enter the name and location of the new catalog.
  3. Click OK.

To delete a catalog using the sample

  1. In the tree view of the catalog structure, right-click the catalog you want to delete.
  2. In the Catalog Administration dialog box, select Remove Catalog.
  3. Click OK.

Programming Notes

The VBAdmin sample illustrates how you can use the AdminIndexServer, CatAdm, and ScopeAdm automation objects of the Admin Helper API to administer catalogs and scopes.


VBQuery Sample

The VBQuery sample is an example Windows application written in Visual Basic that illustrates how to query Indexing Service using the Indexing Service query languages and the ActiveX Data Objects (ADO) and Query Helper APIs.

Path

Source: mssdk\samples\winbase\indexing\VBQuery\

User's Guide

To build and run the sample

  1. In the Visual Basic development environment, open the VBQuery.vbp project in the source path of the sample.
  2. In the File menu, select Make VBQuery.exe.
  3. In the Make Project dialog box, click OK.
  4. In the Run menu, click Start.

To execute queries using the sample

  1. Make sure that Indexing Service is started.
  2. In the Query text box, enter the query text.
  3. In the Scope text box, enter the folder where you want to start the search. You can click the "..." button to display a dialog box to find a folder for the scope of the search.
  4. In the Sort list, select the way you want the application to sort the search hits.
  5. In the list next to the Sort list, select the Indexing Service query language used to specify the query.
  6. Click Go to run the specified query or Clear to specify a new query.

Programming Notes

The VBQuery sample illustrates how you can use the Query and Utility automation objects of the Query Helper API to build applications that query a catalog. The sample can process queries specified in any of the following three query languages.

  • Indexing Service Query Language, Dialect 1 or Dialect 2
  • SQL Query Language

In addition, the sample uses ADO objects to handle the recordsets returned by the Query Helper Automation objects.

This sample also demonstrates making a dynamic-link library (DLL) call to the LocateCatalogs function of the OLE DB Helper API. The application uses this function to locate catalogs suitable for the scope specified by the user.


VJQuery Sample

The VJQuery sample is an example command-line application written in Microsoft® Visual J++® that illustrates how to query Indexing Service using a SQL query language and the ActiveX Data Objects (ADO) API .

Path

Source: mssdk\samples\winbase\indexing\VJQuery\

User's Guide

To build the sample

  1. In the Visual J++ development environment, open the VJQuery.vjp project from the source path of the sample.
  2. In the Build menu, select Build.

To execute a default query using the sample

  1. Make sure that Indexing Service is started.
  2. In the Debug menu, select Start.
  3. In the JView window, read the results of the default SQL query
    SELECT Filename, Size, Write, Path
  FROM SCOPE('DEEP TRAVERSAL OF "\"')
  WHERE CONTAINS('"Indexing Service"')

To specify a complete SQL statement for a query using the sample

  1. Make sure that Indexing Service is started.
  2. Set the PATH environment variable to include "D:\mssdk\Bin", where D: is the drive on which you installed the Platform SDK.
  3. Open a command window and change the directory to the path of the built sample.
  4. Formulate a query that you know will succeed. You need to know the machine, catalog, scope, and query text.
  5. Submit a complete SQL statement by entering, at the command-line prompt,
    jview /p /cp:p "<JAVAPACKAGES>" VJQuery -s <Statement>

    where <Statement> is a complete SQL statement such as the default SQL query in the preceding section. You must escape any double-quote characters in the text of the <Statement> parameter.

To specify only a WHERE clause for a query using the sample

  1. Make sure that Indexing Service is started.
  2. Set the PATH environment variable to include "D:\mssdk\Bin", where D: is the drive on which you installed the Platform SDK.
  3. Open a command window and change the directory to the path of the built sample.
  4. Formulate a query that you know will succeed. You need to know values for the machine, catalog, scope, and query text.
  5. Submit text for a WHERE clause that is concatenated to the following incomplete, fixed SQL statement
    SELECT Filename, Size, Write, Path
  FROM SCOPE('DEEP TRAVERSAL OF "\"')
  WHERE

    by entering, at the command-line prompt,

    jview /p /cp:p "<JAVAPACKAGES>" VJQuery <Where_Text>

    where <Where_Text> is the desired text to follow the WHERE keyword. You must escape any double quotes in the text of the <Where_Text> parameter. For example, to duplicate the default SQL query, enter

    jview /p /cp:p "<JAVAPACKAGES>" VJQuery CONTAINS('\"Indexing Service\"')

Programming Notes

The Query class of the sample has methods that set the text of the query, execute the query, and display the results of the query.

  • Either the SetRawSql method or the SetSqlWhere method sets the m_SqlText variable to the specified SQL statement.
  • The Execute method executes the query. It creates an ADO Recordset object and executes the query by opening the object with the SQL text and the OLE DB Provider for Indexing Service.
  • The Display method enumerates the resulting values of the fields from the Recordset object and prints them.


Using Indexing Service with Web Servers

This section consists of the following topics.

  • Indexing with Internet Information Services
  • Creating Query Forms
  • Creating Administration Forms
  • Highlighting Search Hits
  • Error Messages and Error Pages
  • Web Server Samples

Indexing Service is well-suited for querying and indexing Web content. It integrates with Internet Information Services (IIS) to provide low-maintenance indexing and querying of sites hosted on the Web server.

To provide search features on a Web server, you must first configure Indexing Service to identify the searchable Web content. Then you develop a search page, either as an Active Server Page or as a static query form. After developing the query form, you must develop a Web page for displaying query results. This results page could be the same ASP used for the query form, an .htx file, or another Web page. Indexing Service then returns the search results in a Web page you create. You can also provide hit-highlighting so that readers can see the location of the text they are searching for in the pages found by the query.

In addition to querying, you can develop Web pages to administer the content index on the Web server. These administration forms make it possible to create a custom, Web-based administration interface for Indexing Service.


Indexing with Internet Information Services

Indexing Service provides search capabilities to Web sites hosted with Internet Information Services (IIS). With Indexing Service, you can provide searchable access to both intranet and Internet Web sites. You can index remote computers and multiple Web servers.

The default set of filters provided with Indexing Services includes a filter for HTML documents. But you can also provide Web-based searches of any documents that Indexing Service is able to filter, including Microsoft Office documents. Indexing Service supports a set of document properties for Web pages, making it possible to search for Web pages by date of creation or author, or by their content.

Indexing with IIS involves these main tasks, which are described in this section:

  • Setting up a Web catalog
  • Creating a query page
  • Processing an index query from a query page
  • Formatting and displaying query results
  • Administering the index

Setting Up a Web Catalog

Before you can index content on the Web server, you must create a Web catalog for Indexing Service. Use the Microsoft Management Console (MMC) in Windows® 2000 to carry out this task. You will find Indexing Service under the Server Applications and Services node in the Computer Management tree in Windows 2000.

There are various tasks specific to setting up a Web catalog on IIS:

  • Listing Virtual Roots
  • Setting Up a Remote Virtual Root
  • Indexing Remote Computers
  • Logging Queries
  • Putting Security Features to Work
  • List of Property Names for a Web Catalog

Creating a Query Page

You must also provide a user interface to submit search requests for those who browse your Web site. Indexing Service supports several ways to create query pages, including Internet Data Query (.idq) files and Active Server Pages (.asp). For more information, see Creating Query Forms.

Processing Index Queries

After users of your Web site submit their search requests through your query page, your site must process the queries. This involves taking the information supplied to the query page and constructing an Indexing Service query to run. For more information, see Query Languages for Indexing Service.

Formatting Query Results

After Indexing Service returns the results of the query, your Web site must format the data and display it in a Web page. Indexing Service supports various ways to display query results, including HTML extension (.htx) files and Active Server Pages (.asp) files. For more information, see HTML Extension Files and Formatting Results in an Active Server Pages File.

In addition to listing Web pages that match a query, Indexing Service can also highlight the search text when showing a Web page found by the query. For more information, see Highlighting Search Hits.

Administering the Index

You can administer your Web site index with the MMC or create your own administration interface. You can develop Active Server Pages (.asp) or Internet Data Administration (.ida) files. These kinds of administration front ends are very easy to customize and accessible through any computer that can browse the Web site. For more information, see Creating Administration Forms.


Listing Virtual Roots

Using Indexing Service with IIS, you can specify a list of virtual roots that are indexed for the Web catalog.

To retrieve a list of virtual roots and their indexed state, you need only execute a special query. The results are returned in the same manner as a standard query results page, and can be formatted using standard .htx templates. To retrieve the list of virtual roots, set the CiScope parameter in an .idq file to be the string: VIRTUAL_ROOTS. The .idq syntax requires that CiRestriction be set to a non-null value, but a restriction such as #vpath * can be used to retrieve all roots.

The properties that can be retrieved from this query are all the standard file properties (path, virtual path, and so on) of the directory to which the virtual root maps: metavrootused. This Boolean value is set to TRUE if the root is indexed, FALSE if it is not.

You can determine the type of a virtual root while making the VIRTUAL_ROOTS query. Look at the value of the special property StorageType—(DBTYPE_UI4) = b725f130-47ef-101a-a5f1-02608c9eebac 4. The value zero identifies a Web root. The value one identifies a news root.


Setting Up a Remote Virtual Root

When specifying the logon ID for a remote virtual root, type both the domain name and the user name, separated by a backslash (\):

domain\username

If you do not give the domain name, Indexing Service will not index the remote virtual roots. Note that the domain name may actually be the name of the computer, if the account is local to that computer.

User IDs associated with remote virtual-root setup must have interactive logon permission on the computer running Indexing Service. For example, if /Vroot1 on index_server points to \\Computername\Share\Folder1\Folder2 and the user ID is domain\user, then domain\user must have interactive logon privilege on index_server. The simplest way to achieve this is to add domain\user to the Guests group on index_server.


Indexing Remote Computers

This topic contains the following sections to help you index remote computers:

  • Indexing Multiple Web Servers: Describes how to set up a site to index content on multiple Web servers.
  • Supporting Multiple Security Domains: Describes how to set up a site to index content on servers in different security domains.
  • Indexing a Novell NetWare File Share: Explains how to index content on servers running Novell NetWare.


Indexing Multiple Web Servers

Many sites use Indexing Service to index multiple Web servers, especially in a corporate intranet environment. This is done simply by sharing a folder on the remote volume and creating a virtual directory on the indexing server. However, in some cases, especially if the remote system is a Web server, links can break because the share was not made at the correct point in the hierarchy. Consider the following example.

Local Computer: Local

Remote Computer: Remote

Remote Web Root: \\Remote\InetPub\Wwwroot

Remote Web 1 Directory: \\Remote\InetPub\Wwwroot\Web1

Remote Share: \\Remote\Web1

Remote Share Mounted Locally: http://local/specs

In the preceding example, the shared directory that is indexed is D:\InetPub\Wwwroot\Web1. In the Indexing Service default .htx file, links are returned as <%server%><%vpath%>, so on the local computer remote files are returned through the reference http://local/specs. This usually breaks links because the Web pages with physical directories ending in Web1 (such as \Remote\InetPub\Wwwroot\Web1) probably contain links to virtual roots beginning with http://remote (such as http://remote/web1).

To solve this problem you can share out the Web root directories and modify your .htx file as follows.

Local Computer: Local

Remote Computer: Remote

Remote Web Root: \\Remote\InetPub\Wwwroot

Remote Web 1 Directory: \\Remote\InetPub\Wwwroot\Web1

Remote Share: \\Remote\Wwwroot

Remote Share Mounted Locally: /Remote

Note that the remote share is now the Wwwroot directory, and its virtual directory on the indexing computer (local) is /remote. The last step modifies the .htx file to return hyperlinks as "http:/<%vpath%>". This setting returns the correct hyperlink for all documents stored on the remote computer.

For example, if a document on the remote computer was referenced as http://remote/web1/sample.doc, it would normally be served by the indexing computer (local) as http://local/remote/web1/sample.doc, because its virtual path is /remote/web1/sample.doc. However the .htx modification inserts an http:/ reference before the virtual path, so the URL that is actually returned is now http://remote/web1/sample.doc, which is the correct URL.

This configuration allows the remote servers to do all the file serving, leaving the indexing server free to do all the serving.


Supporting Multiple Security Domains

Windows NT®/Windows 2000 supports multiple security domains. This section describes how to set up Indexing Service to index computers in different system domains. The following diagram shows a site with three domains.

In this site, IIS and Indexing Service are running on Server A, which is in Domain A. Server A is connected to the Web. Domain A must be trusted by Domain B and Domain C.

For this example, assume you want to set up virtual roots on Server A for the following Uniform Naming Convention (UNC) paths:

  • \\B1\Share1
  • \\B2\Share2
  • \\C1\Share1
  • \\C2\Share2

Assume a single user ID, Domain\WebUser, has permission to connect to the four shares.

To configure Indexing Service for these assumptions

  1. On Domain A, create the WebUser account. Open User Manager for Domains, and add WebUser as a new user on the domain controller for Domain A.
  2. Add DomainA\WebUser to the list of accounts having interactive logon privileges on Server A. User Manager for Domains can check to see whether a user has Interactive logon privileges.
  3. Stop the Content Index Service, which also stops Indexing Service.
  4. Restart the Content Index Service, which also starts Indexing Service and starts indexing the documents on all the virtual roots.
  5. Start Internet Service Manager, and add the virtual roots to the UNC shares listed under the first assumption in the previous section. In the User Name text box, you must specify the full user ID in the form domain\user-id (DomainA\WebUser, in the example). The backslash is important.
  6. Repeat step 3 for all the UNC shares you want to add.

If you have had problems with remote virtual roots before starting this procedure, you should delete the contents of your Catalog.wci directory after step 3. Removing the contents of this directory starts Indexing Service with a clean set of data.

Note This procedure can also configure multiple accounts.


Indexing a Novell NetWare File Share

If you have Novell NetWare file servers, Indexing Service can index their contents as well. To do this, install and run Microsoft Gateway Service for NetWare. For details about installing Gateway Service for NetWare, see the documentation for that service.

Install Gateway Service for NetWare on the computer running Indexing Service. For details refer to the Gateway Service documentation. Indexing Service indexes the files on Novell NetWare file shares in one of two ways:

  • Through gateway redirection.
  • Through a UNC share.

To index files using gateway redirection

  1. Create a gateway to the NetWare share. Assume, for example, that the gateway assigns the drive letter Z to the remote NetWare share.
  2. Add a virtual root in IIS pointing to drive Z. All documents on the remote NetWare share will be indexed by Indexing Service.

You can also index files on NetWare volumes by using a UNC share. You can create this UNC share whether the server is part of a domain or not, as shown in the following examples.

For these examples, assume the following:

  • The UNC name for the share is \\NovellServer\Share1.
  • Indexing Service is running on a computer named Server A.
  • Server A is on Domain A when the server is part of a domain.
  • The user ID is WebUser, which can be any valid Windows NT®/Windows 2000 user ID.

If Server A is part of a domain, follow these steps:

  1. Create an account called WebUser on Domain A. This account should have the form DomainA\WebUser.
  2. Give to the DomainA\WebUser account on Server A.
  3. Make sure that DomainA\WebUser has Read permission on \\NovellServer\Share1.
  4. Create a virtual root in IIS pointing to \\NovellServer\Share1. Specify DomainA\WebUser for the user name, and assign an appropriate password. Be sure to specify Domain A followed by a backslash (\) and then the actual user ID.

If Server A is not part of a domain, follow these steps:

  1. Create an account called WebUser on ServerA. This account should have the form ServerA\WebUser.
  2. Give to the ServerA\WebUser account on Server A.
  3. Make sure that ServerA\WebUser has Read permission on \\NovellServer\Share1.
  4. Create a virtual root in IIS pointing to \\NovellServer\Share1. Specify ServerA\WebUser for the user name, and assign an appropriate password. Be sure to specify Server A followed by a backslash (\) and then the actual user ID.

Indexing Service then indexes the remote UNC \\NovellServer\Share1. If you want to index more remote NetWare files shares, repeat steps 3 and 4 for each of the shares.


Logging Queries

Queries are logged by means of the standard IIS logging mechanism.


Putting Security Features to Work

Indexing Service uses the security system built into Windows NT/Windows 2000 to check whether users have permission to view query results. NTFS file system supports access control lists (ACLs) on directories and files. Indexing Service will check these ACLs before returning a query result file by file.


Security Summary

Note that the standard security system is used, so Windows NT Server/Windows 2000 Server and IIS must be configured for secure access. Also, the documents themselves must be protected with ACLs.

Indexing Service checks ACLs before returning query results to the browser. A user must have Read privilege on a document for Indexing Service to return a hit. The query is first executed in the system security context so all hits are returned. Then documents the user cannot see are removed from the result set, and the remaining documents are returned to the user.

Indexing Service by default always checks security; therefore, all queries are performed with ACL checking activated.

If a user is not allowed to read a document, Indexing Service gives that user no reference to the document — he or she does not even know the document exists. Many other systems will return a reference to the document and then prohibit actual access to the document. Removing prohibited documents from the result set is important because Indexing Service can generate document abstracts derived from the content of a document. To return a reference and abstract for a secure document would violate security because some of the contents would be displayed. Even if abstracts are not generated, returning hits to a prohibited document allows an intruder to find documents with sensitive words and phrases, and determine the location of these documents. This information could easily breach security.


List of Property Names for a Web Catalog

These properties are always available for queries. Additional properties may also be available depending on the configuration of the Web server.

This section contains the following topics:

  • Default Property Names for a Web Catalog
  • Defining New Property Names for a Web Catalog


Default Property Names for a Web Catalog

This list of properties includes all properties in the property store exposed by system IFilter implementations. Additional properties can be indexed by using custom property features, if available, documented in each IFilter implementation or by installing additional IFilter implementations that expose additional properties.

Friendly Name | Datatype | Property
A_HRef | DBTYPE_WSTR | DBTYPE_BYREF | Text of HTML HREF. This property name was created for Microsoft Site Server and corresponds to the Indexing Service property name HtmlHRef. Can be queried but not retrieved.
Access | VT_FILETIME | Last time file was accessed.
All | (not applicable) | Searches every property for a string. Can be queried but not retrieved.
AllocSize | DBTYPE_I8 | Size of disk allocation for file.
Attrib | DBTYPE_UI4 | File attributes. Documented in Microsoft Win32®.
ClassId | DBTYPE_GUID | Class ID of object; for example, Corel WordPerfect, Microsoft Word, and so on.
Characterization | DBTYPE_WSTR | DBTYPE_BYREF | Characterization, or abstract, of document. Computed by Indexing Service.
Contents | (not applicable) | Main contents of file. Can be queried but not retrieved.
Create | VT_FILETIME | Time file was created.
Directory | DBTYPE_WSTR | DBTYPE_BYREF | Physical path to the file, not including the file name.
DocAppName | DBTYPE_WSTR | DBTYPE_BYREF | Name of application that created the file.
DocAuthor | DBTYPE_WSTR | DBTYPE_BYREF | Author of document.
DocByteCount | DBTYPE_14 | Number of bytes in a document.
DocCategory | DBTYPE_STR | DBTYPE_BYREF | Type of document such as a memo, schedule, or white paper.
DocCharCount | DBTYPE_I4 | Number of characters in document.
DocComments | DBTYPE_WSTR | DBTYPE_BYREF | Comments about document.
DocCompany | DBTYPE_STR | DBTYPE_BYREF | Name of the company for which the document was written.
DocCreatedTm | VT_FILETIME | Time document was created.
DocEditTime | VT_FILETIME | Total time spent editing document.
DocHiddenCount | DBTYPE_14 | Number of hidden slides in a Microsoft PowerPoint® document.
DocKeywords | DBTYPE_WSTR | DBTYPE_BYREF | Document keywords.
DocLastAuthor | DBTYPE_WSTR | DBTYPE_BYREF | Most recent user to edit document.
DocLastPrinted | VT_FILETIME | Time document was last printed.
DocLastSavedTm | VT_FILETIME | Time document was last saved.
DocLineCount | DBTYPE_14 | Number of lines contained in a document.
DocManager | DBTYPE_STR | DBTYPE_BYREF | Name of the manager of the document's author.
DocNoteCount | DBTYPE_14 | Number of pages with notes in a PowerPoint document.
DocPageCount | DBTYPE_I4 | Number of pages in document.
DocParaCount | DBTYPE_14 | Number of paragraphs in a document.
DocPartTitles | DBTYPE_STR | DBTYPE_VECTOR | Names of document parts. For example, in Microsoft Excel, part titles are the names of spreadsheets; in PowerPoint, slide titles; and in Word, the names of the documents in the master document.
DocPresentationTarget | DBTYPE_STR|DBTYPE_BYREF | Target format (35mm, printer, video, and so on) for a presentation in PowerPoint.
DocRevNumber | DBTYPE_WSTR | DBTYPE_BYREF | Current version number of document.
DocSecurity | DBTYPE_14 | Control permissions.
DocSlideCount | DBTYPE_14 | Number of slides in a PowerPoint document.
DocSubject | DBTYPE_WSTR | DBTYPE_BYREF | Subject of document.
DocTemplate | DBTYPE_WSTR | DBTYPE_BYREF | Name of template for document.
DocThumbnail | VT_CF | Thumbnail
DocTitle | DBTYPE_WSTR | DBTYPE_BYREF | Title of document.
DocWordCount | DBTYPE_I4 | Number of words in document.
FileIndex | DBTYPE_I8 | Unique ID of file.
FileName | DBTYPE_WSTR | DBTYPE_BYREF | Name of file.
HtmlHeading1 | DBTYPE_WSTR | DBTYPE_BYREF | Text of HTML document in style H1. Can be queried but not retrieved.
HtmlHeading2 | DBTYPE_WSTR | DBTYPE_BYREF | Text of HTML document in style H2. Can be queried but not retrieved.
HtmlHeading3 | DBTYPE_WSTR | DBTYPE_BYREF | Text of HTML document in style H3. Can be queried but not retrieved.
HtmlHeading4 | DBTYPE_WSTR | DBTYPE_BYREF | Text of HTML document in style H4. Can be queried but not retrieved.
HtmlHeading5 | DBTYPE_WSTR | DBTYPE_BYREF | Text of HTML document in style H5. Can be queried but not retrieved.
HtmlHeading6 | DBTYPE_WSTR | DBTYPE_BYREF | Text of HTML document in style H5. Can be queried but not retrieved.
HtmlHRef | DBTYPE_WSTR | DBTYPE_BYREF | Text of HTML HREF. Can be queried but not retrieved.
Img_Alt | DBTYPE_WSTR | DBTYPE_BYREF | Alternate text for <IMG> tags. Can be queried but not retrieved.
Path | DBTYPE_WSTR | DBTYPE_BYREF | Full physical path to file, including file name.
ShortFileName | DBTYPE_WSTR | DBTYPE_BYREF | Short (8.3) file name.
Size | DBTYPE_I8 | Size of file, in bytes.
USN | DBTYPE_I8 | Update Sequence Number (USN). NTFS file system drives only.
Write | VT_FILETIME | Last time file was written.


Defining New Property Names for a Web Catalog

To define properties that are not in the previous list, in the Default Property Names for a Web Catalog section, you must list them in a [Names] section in the .idq file. To use these properties in a restriction, sort specification, or as a retrieved column, you must define them in the .idq file, using the following format:

[Names]
#Properties that are not in the standard list
Propertyname ( Datatype ) = GUID ["Name" | propid]

In the syntax, "Name" is the property name ("Sales" in the following example), and propid is the property ID in hexadecimal. Note that you need to surround the friendly name with quotation marks, but that the property ID does not take quotation marks.

For example, suppose you want to define an HTML meta tag as a property name that somebody can search for. The property you want to define is Sales.

To define the Sales property

  1. In the .idq file, under the [Names] section, add the following line.

    MetaDescription(DBTYPE_WSTR) = d1b5d3f0-c0b3-11cf-9a92-00a0c908dbf1 "Sales"

    The GUID number comes from the MetaTagClsid parameter in the registry, at the following location:

    HKEY_LOCAL_MACHINE
\SYSTEM
 \CurrentControlSet
  \Control
   \HtmlFilter
    \MetaTagClsid
  2. Then, in the HTML files where you want the tag to appear, define the meta description.

    For example, suppose that you want to search for all files that give sales projections for the future:

    In File1.htm:

    <META NAME="Sales" CONTENT="Projections for 1999">

    In File2.htm:

    <META NAME="Sales" CONTENT="Projections for 2000">

    In File3.htm:

    <META NAME="Sales" CONTENT="Sales in 1998">

Note Be sure to add your META NAME tags between the <head> and </head> HTML tags at the beginning of the file.

You can now search for all files that show sales projections. Send the following query:

@metadescription projections

This query returns all the files with the word projections in the CONTENT field of the meta tag. In this example, File1.htm and File2.htm are returned.

But suppose you want to search for sales by year, for example a list of sales in 1998. Send the following query:

@metadescription 1998

File3.htm is returned.


Creating Query Forms

With Internet Information Services (IIS) installed on Windows® 2000 Server, you can customize the query forms that an end user fills in to initiate a search on the Web catalog.

Processing any Indexing Service query involves three steps:

  • Presenting the Query: Designing the HTML page or form to request a search string from a Web client, usually an end user.
  • Controlling the Query: Allowing the user to enter qualifications that determine how the search is controlled. You may set up defaults that are reasonable for your Web catalog and not give the novice end user control, or you may give advanced users more control over how the search is performed.
  • Presenting the Query Results: Format the resulting hits and allow the user to scroll through them.

Query forms for server-side scripting may be created in two ways:

  • Active Server Pages (ASP) Query Form: Use ASP when you do not anticipate a large number of queries against a Web catalog. Active Server Pages are easier to program and easier to change but they take more time to process by the server. All three of the above-mentioned query steps are combined into one .asp file. The Query and Utility objects are Indexing Service Server-Side Objects (IXSSO) that allow you to control the query and results through properties and methods on the Query object.
  • Internet Server Application Programming Interface (ISAPI) Internet Data Query (.idq file) Query Form: Use an .idq file when you have a large number of queries against a catalog. With this process, the three query steps are performed by separate files. The .idq files initially take longer to set up, but they execute faster on the server. Use .idq files to set up the query form and HTML Extension (.htx) files to format the results.
  • This section contains detailed information in the following topics:
  • Creating an Active Server Pages Query Form
  • Creating a Static Query Form
  • Support for Multiple Languages
  • Variables in .Idq and .Htx Files
  • Variables within Query Strings


Creating an Active Server Pages Query Form

This section walks you through the creation of a basic Active Server Page (.asp) file, demonstrating how to create a sample query form, how to control the search, and how to format the results. Although an .asp file is different from .htm, .idq, and .htx files, you will see similar elements in all of them. With Active Server Pages, instead of creating three separate files, you can combine all the information into one .asp file. Regardless of whether you create one file or multiple files, the processing that corresponds to .htm, .idq and .htx processing takes place in the .asp file.

This section contains the following topics:

  • Setting up an Active Server Pages Form
  • Controlling an Active Server Pages Search
  • Formatting Results in an Active Server Pages File

When you install Indexing Service, Ixtrasp.asp is installed with the sample files. This sample file shows the query form and query processing combined into one file, which this test drive annotates.

To use the Ixtrasp.asp sample file

  1. Copy the Ixtrasp.asp file to a virtual directory with the execute or script permission set.
  2. Change the AddScopeToQuery directory to the directory or directories you want to search. This example uses a hypothetical directory called Myfiles

To create a basic .asp query form

  1. Type your scripts and HTML code into a file.
  2. Save the file in HTML format. (Some lines are shown in bold for emphasis only.)


Setting up an Active Server Pages Form

When setting up a query form for an Active Server Pages (ASP) page, you set up the header and also create the form.


Setting Up the Header

The <SCRIPT LANGUAGE> and </SCRIPT> tags turn scripting on and off. This example turns on a Microsoft Visual Basic® Scripting Edition (VBScript) command, option explicit.

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN" "html.dtd">
<HTML>
<HEAD>

    <SCRIPT LANGUAGE="VBScript" RUNAT="Server">
    <!--
        option explicit
      -->
    </SCRIPT>

    <TITLE>Index Server Search Form</TITLE>

    <META NAME="DESCRIPTION" CONTENT="Sample ASP query form for
                Microsoft Index Server">
    <META NAME="KEYWORDS"    CONTENT="query, content, hit, asp">
    <META NAME="MS.LOCALE"   CONTENT="EN-US">
    <META HTTP-EQUIV="Content-Type" CONTENT="text/html;
                charset=Windows-1252">

In the preceding HTML code, the bold type contains a sampling of meta tags:

Description
Sets the abstract that a client sees in the query results.
Keywords
Lists keywords a client can search for in a query.
MS.Locale
Sets the language code for this form. EN-US stands for American English. For a complete list of supported language codes, see Valid Locale Identifiers.
Content-Type
Determines the character set (charset) that is used; for example, the Latin alphabet or the Hebrew alphabet. For a complete set of supported tags, see Recognized Character Set Tags.

The next section turns form variables into server-side VBScript variables. The actual query form appears later in the file. Positioning the form data here allows the form fields to be pre-initialized, which causes the text of your query to reappear in the form field after the query results are displayed.

<%
    NewQuery = FALSE
    UseSavedQuery = FALSE
    QueryForm = Request.ServerVariables( "PATH_INFO" )
    SearchString = ""
    if Request.ServerVariables("REQUEST_METHOD") = "POST" then
        SearchString = Request.Form("SearchString")
        pg = Request.Form("pg")

        if pg <> "" then
           NextPageNumber = pg
           NewQuery = FALSE
           UseSavedQuery = TRUE
        else
            NewQuery = SearchString <> ""
        end if
     end if

 %>
</HEAD>

Also, the line in bold type defines the query form as the current file. From that point on, the file is referred to as QueryForm. This line allows you to change the name of the file without having to change the name anywhere within the file.


Creating the Form

Once you have set up the header, you are ready to create the .asp search form.

<TABLE>
    <TR>
        <TD><H1>Sample ASP Search Form</H1></TD>
    </TR>
</TABLE>

<HR WIDTH=75% ALIGN=center SIZE=3>
<p>

<TABLE>
  <TR>
    <TD ALIGN=LEFT>Enter your query below:</TD>
  </TR>
  <TR>
    <TD>
      <FORM ACTION="<%= QueryForm%>" METHOD=POST>

        <TABLE>
          <TR>
            <TD><INPUT TYPE="TEXT" NAME="SearchString" SIZE="60"
                         MAXLENGTH="100" VALUE="<%=SearchString%>"></TD>
            <TD><INPUT TYPE="SUBMIT" NAME="Action" VALUE="New Query"></TD>
          </TR>
        </TABLE>

      </FORM>
    </TD>
  </TR>
</TABLE>

The two most important lines are the FORM ACTION and the INPUT TYPE lines.

<FORM ACTION. . .>
This line names the current file, where the processing code is located.
<INPUT TYPE="TEXT". . .>
Here the variable SearchString is preset to accept whatever text is typed in the "Enter your query below" field. For example, if you type "cache" in this field, SearchString holds the text "cache".
<INPUT TYPE="SUBMIT". . .>
This line creates the button that executes your query. In this example, the button is called New Query.


Controlling an Active Server Pages Search

This section shows how to control searches with an ASP page. The code displayed here is equivalent in function to an .idq file.

<BR>

<%

if SearchString <> "" then
  if NewQuery then
    set Session("Query") = nothing
    set Session("Recordset") = nothing
    NextRecordNumber = 1

    set Q = Server.CreateObject("ixsso.Query")
    set util = Server.CreateObject("ixsso.util")
    Q.Query = SearchString
    Q.SortBy = "rank[d]"
    Q.Columns = "DocTitle, vpath, path, filename, size, write, characterization"
    util.AddScopeToQuery Q, "/Myfiles", "deep"

    set RS = Q.CreateRecordSet("nonsequential")

    RS.PageSize = 10
    ActiveQuery = TRUE

  elseif UseSavedQuery then
    if IsObject( Session("Query") ) And IsObject( Session("RecordSet") ) then
      set Q = Session("Query")
      set RS = Session("RecordSet")

      if RS.RecordCount <> -1 and NextPageNumber <> -1 then
        RS.AbsolutePage = NextPageNumber
        NextRecordNumber = RS.AbsolutePosition
      end if

      ActiveQuery = TRUE
    else
      Response.Write "ERROR - No saved query"
    end if
  end if
%>

This section is executed only if the SearchString variable has been set (that is, only if you have typed a query into the form and clicked the New Query button). This section contains many of the same elements as the sample .idq file in Controlling the Search (.Idq File). Notice the differences in syntax.

set Q = Server.CreateObject("ixsso.Query") and set util = Server.CreateObject("ixsso.util")
These lines define the server-side Query and Utility objects. The rest of the commands in this group can then refer to these objects.
Q.Query = SearchString
Sets the query string (restriction) used to search all virtual directories on the server.
Q.SortBy = "rank[d]"
Sorts the results of searches in rank-descending order (highest rank first).
Q.Columns = "DocTitle, vpath, path, filename, size, write, characterization"
Indicates the kind of information returned in the results.
util.AddScopeToQuery Q, "/Myfiles", "deep"
Restricts the scope to the listed virtual directories. In this example, Indexing Service searches documents in the directory Myfiles, as well as all its subdirectories ("deep").


Formatting Results in an Active Server Pages File

The last part of this example shows how to format your query results. This portion of an .asp file contains variables that determine the information displayed in the results of a search; this is equivalent in function to an .htx file.

%<
  if ActiveQuery then
    if not RS.EOF then
 %>
<p>
<HR width="80%" ALIGN=center SIZE=3>
<p>

<%
     LastRecordOnPage = NextRecordNumber + RS.PageSize - 1
     CurrentPage = RS.AbsolutePage
     if RS.RecordCount <> -1 AND RS.RecordCount < LastRecordOnPage then
         LastRecordOnPage = RS.RecordCount
     end if

     Response.Write "Documents " & NextRecordNumber & " to " & LastRecordOnPage
     if RS.RecordCount <> -1 then
         Response.Write " of " & RS.RecordCount
     end if
     Response.Write " matching the query " & chr(34) & "<I>"
     Response.Write SearchString & "</I>" & chr(34) & ".<P>"
 %>

The following section is equivalent to the <%Begindetail%> <%Enddetail%> section in an .htx file.

<dl>

<!-- BEGIN first row of query results table -->
<% Do While Not RS.EOF and NextRecordNumber <= LastRecordOnPage %>

<%
    ' This is the detail portion for Title, Abstract, URL, Size, and
    ' Modification Date.

    ' If there is a title, display it, otherwise display the virtual path.
%>
    <p>
    <dt><%= NextRecordNumber%>.
        <%if VarType(RS("DocTitle")) = 1 or RS("DocTitle") = "" then%>
            <b><a href="<%=RS("vpath")%>"><%= Server.HTMLEncode( RS("filename") )%></a></b>
        <%else%>
            <b><a href="<%=RS("vpath")%>"><%= Server.HTMLEncode(RS("DocTitle"))%></a></b>
        <%end if%>
    <dd>
        <%if VarType(RS("characterization")) = 8 and RS("characterization") <> "" then%>
            <b><i>Abstract:  </I></b><%= Server.HTMLEncode(RS("characterization"))%>
            <br>
        <%end if%>
        <cite>
            <a href="<%=RS("vpath")%>">http://<%=Request("server_name")%><%=RS("vpath")%></a>
            <font size=-1> - <%if RS("size") = "" then%>(size and time unknown)<%else%>size <%=RS("size")%> bytes - <%=RS("write")%> GMT<%end if%></font>
        </cite>

<%
          RS.MoveNext
          NextRecordNumber = NextRecordNumber+1
      Loop
%>

</dl>

The section equivalent to the <%BeginDetail%><%EndDetail%> section in an .htx file ends here. The following section displays information about the query.

<P><BR>

<%
  else   ' NOT RS.EOF
      if NextRecordNumber = 1 then
          Response.Write "No documents matched the query<P>"
      else
          Response.Write "No more documents in the query<P>"
      end if

  end if ' NOT RS.EOF
 %>

<!-- If the index is out of date, display the fact -->

<%if Q.OutOfDate then%>
    <P>
    <I><B>The index is out of date.</B></I><BR>
<%end if%>

<!--
    If the query was not executed because it needed to enumerate to
    resolve the query instead of using the index, but AllowEnumeration
    was FALSE, let the user know
-->

<%if Q.QueryIncomplete then%>
    <P>
    <I><B>The query is too expensive to complete.</B></I><BR>
<%end if%>

<!--
    If the query took too long to execute (for example, if too much work
    was required to resolve the query), let the user know
-->

<%if Q.QueryTimedOut then%>
    <P>
    <I><B>The query took too long to complete.</B></I><BR>
<%end if%>

The next portion sets the Previous and Next navigation buttons when a query returns more results than called for per page. Comments within the code explain each section.

<TABLE>

<!--
    This is the "previous" button.
    This retrieves the previous page of documents for the query.
-->

<%SaveQuery = FALSE%>
<%if CurrentPage > 1 and RS.RecordCount <> -1 then
    <td align=left>
        <form action="<%= QueryForm%>" method="POST">
            <INPUT TYPE="HIDDEN" NAME="SearchString" VALUE="<%=SearchString%>">
            <INPUT TYPE="HIDDEN" name="pg" VALUE="<%=CurrentPage-1%>" >

            <input type="submit" value="Previous <%=RS.PageSize%> documents">
        </form>
    </td>
    <%SaveQuery = TRUE%>
<%end if%>

<!--
    This is the "next" button.
    This button retrieves the next page of documents for the query.
    If the RS.RecordCount is available, the number of
    documents on the next page will be displayed.
-->

<%if Not RS.EOF then%>
    <td align=right>
        <form action="<%= QueryForm%>" method="POST">
            <INPUT TYPE="HIDDEN" NAME="SearchString" VALUE="<%=SearchString%>">
            <INPUT TYPE="HIDDEN" name="pg" VALUE="<%=CurrentPage+1%>" >

            <% NextString = "Next "
               if RS.RecordCount <> -1 then
                   NextSet = (RS.RecordCount - NextRecordNumber) + 1
                   if NextSet > RS.PageSize then
                       NextSet = RS.PageSize
                   end if
                   NextString = NextString & NextSet & " documents"
               else
                   NextString = NextString & " page of documents"
               end if
             %>
            <input type="submit" value="<%=NextString%>">
        </form>
    </td>
    <%SaveQuery = TRUE%>
<%end if%>

</TABLE>

<!-- Display the page number -->

Page <%=CurrentPage%>
<%if RS.PageCount <> -1 then
     Response.Write " of " & RS.PageCount
  end if %>

The next section tells where the RS and Q variables are stored in the ASP session variables. Storing these variables is convenient for navigation. As an alternative, you can re-execute the query when the user displays another page.

<%
    ' If either of the previous or back buttons were displayed, save the query
    ' and the recordset in session variables.
    if SaveQuery then
        set Session("Query") = Q
        set Session("RecordSet") = RS
    else
        RS.close
        Set RS = Nothing
        Set Q = Nothing
        set Session("Query") = Nothing
        set Session("RecordSet") = Nothing
    end if
 %>
<% end if

elseif not NewQuery then
    Response.Write ""
else
    Response.Write "Please enter a word or phrase to search for."
end if

%>


Creating a Static Query Form

Three files — an HTML file, an Internet Data Query (.idq) file, and an Extended HTML (.htx) file — interact to create a static query with Indexing Service. The HTML file creates the form, which posts user input as a query to the .idq file. The .idq file then sends the results of the query to the .htx file, which formats the results that are returned to the Web browser.

All three of these files must be in a virtual directory defined in Internet Service Manager. The .idq and .htx files must be in the /IisSamples/IsSamples virtual directory, which is physically located in C:\InetPub\IisSamples\IsSamples, or in another virtual directory with both Read and Execute (or Script) permissions set.

This section contains the following topics:

  • Internet Data Query Files
  • Setting up the Form (.Htm File)
  • Controlling the Search (.Idq File)


Internet Data Query Files

Internet Data Query files (files with an .idq extension) for Indexing Service, together with the form parameters, specify the query that Indexing Service will run. The .idq file is divided into two sections: the names section (which is optional and need not be supplied for standard queries) and the query section.

This part of the documentation contains the following topics:

  • Names Section of .Idq Files: Defines nonstandard column names in an .idq file that can be referred to in a query.
  • Defining Friendly Names: Examples of defining friendly names for properties.
  • Defining Custom Properties: Examples of custom properties from various IFilter implementations, including Microsoft Office and HTML.
  • Query Section of .Idq Files: Explains the parameters that can be used in a query.
  • Effect of Parameters on Query Performance: Tells how to set parameters for the best performance.
  • Sequential vs. Nonsequential Execution: Describes the two ways to execute a query.
  • Enumerated vs. Indexed Resolution. Describes conditions under which queries are enumerated against the system disk rather than the Content Index.
  • Deferring Nonindexed Trimming. Describes how to defer the trimming of records returned from certain queries.

Note All paths to .idq files must be the full path name from a virtual root, not a relative path or a physical path. In other words, all paths must start with a forward slash and cannot contain "." or ".." components. See the following examples:

Valid Paths
/scripts/myquery.idq
/iissamples/issamples/query.idq

Invalid Paths
c:\iissrv\scripts\myquery.idq
scripts/query.idq
/samples/../scripts/example.idq

You must put the .idq files into a virtual directory with Execute or Script permission. You cannot put .idq files into a virtual directory pointing to a remote Universal Naming Convention (UNC) share.

Note Indexing Service does not support physical paths longer than the Windows 2000 shell limit (260 characters).


Names Section of .Idq Files

The names section of the Internet Data Query (.idq) file defines nonstandard column names that can be referred to in the query. The columns refer to properties stored in the property cache, standard file system properties, or Microsoft ActiveX® properties that have been created in document files with IPropertyStorage, or in the Microsoft Office summary and custom properties. The globally unique identifier (GUID) for Office is 0xF29F85E0,0x4FF9,0x1068,0xAB9108002B27B3D9. The following sample defines a few of the ActiveX Summary Information properties:

[Names]
#Property set for ActiveX document properties
DocTitle                                  = F29F85E0-4FF9-1068-AB91-08002B27B3D9 2
DocSubject( DBTYPE_WSTR|DBTYPE_BYREF )     = F29F85E0-4FF9-1068-AB91-08002B27B3D9 3
DocAuthor( DBTYPE_WSTR|DBTYPE_BYREF )      = F29F85E0-4FF9-1068-AB91-08002B27B3D9 4
DocEditTime( VT_FILETIME )                 = F29F85E0-4FF9-1068-AB91-08002B27B3D9 0xa
DocLastPrinted( VT_FILETIME )              = F29F85E0-4FF9-1068-AB91-08002B27B3D9 0xb
DocPageCount( DBTYPE_I4 )                 = F29F85E0-4FF9-1068-AB91-08002B27B3D9 0xe
DocWordCount( DBTYPE_I4 )                 = F29F85E0-4FF9-1068-AB91-08002B27B3D9 0xf
SalesRegion( DBTYPE_WSTR | DBTYPE_BYREF ) = D5CDD505-2E9C-101B-9397-08002B2CF9AE "SalesRegion"

Within the section, any blank line, or a line beginning with a number sign (#) is ignored. Other lines consist of a friendly name, optionally followed by a data type in parentheses, followed by an equal sign (=), then a GUID identifying the property set for the column, followed by either a number or a string giving the PROPID or the property name, respectively. If no other data type is provided, DBTYPE_WSTR|DBTYPE_BYREF is assumed.

The friendly name is the token in query restrictions, sort specifications, and so on. Multiple friendly names can point to the same property. For example, the friendly name Author might be replaced by Auteur if an author property is to be shown to a French audience. Friendly names cannot contain spaces or special characters such as angle brackets, equal signs, exclamation points, commas, periods, or asterisks (>=<!,.*).

The GUID and PROPID/property name is the name of the property within the ActiveX property name space. See the Microsoft Win32® API for more information on ActiveX properties. The PROPID may be specified as a decimal (base 10) or a hexadecimal (base 16) number. In the latter case, the number must be preceded by 0x. Property names must be enclosed in quotation marks. For example, "10" is not the same as 10.


Defining Friendly Names

The friendly names of known properties listed in the property names for a Web catalog are always available, even if they are not explicitly defined in the names section. See List of Property Names for a Web Catalog. For example, a friendly name such as MetaDescription for the HTML meta property can be defined as

MetaDescription(DBTYPE_WSTR|DBTYPE_BYREF) = D1B5D3F0-C0B3-11CF-9A92-00A0C908DBF1 description


Defining Custom Properties

The following data types are for custom properties:

  • String: DBTYPE_LPSTR|DBTYPE_BYREF, DBTYPE_WSTR|DBTYPE_BYREF, DBTYPE_STR|DBTYPE_BYREF
  • Date: VT_FILETIME
  • Number: DBTYPE_I4
  • Yes or No (TRUE or FALSE): DBTYPE_BOOL

Microsoft Office document properties take the following GUIDs:

  • Custom properties: D5CDD505-2E9C-101B-9397-08002B2CF9AE
  • Properties such as company name: D5CDD502-2E9C-101B-9397-08002B2CF9AE
  • Built-in properties, like DocTitle: F29F85E0-4FF9-1068-AB91-08002B27B3D9
  • A_HRef (and HTMLHRef): c82bf597-b831-11d0-b733-00aa00a1ebd2\A.HREF
  • Img_Alt: 70eb7a10-55d9-11cf-b75b-00aa0051fe20\IMG.ALT

The following example shows you how to name a custom property for Office by adding a GUID to the Names section of the .idq file:

Custom_Text ( DBTYPE_STR|DBTYPE_BYREF ) = D5CDD505-2E9C-101B-9397-08002B2CF9AE "Custom_Text"

In this example, Custom_Text can be any string. The value of Custom_Text does not have to be the same at the beginning and end of the line. The one at the beginning is the friendly name, and the one at the end (in quotation marks) is the Microsoft Office property name.

If defining a custom date, you must use the VT_FILETIME data type. For example:

DocDateCompleted( VT_FILETIME,20 ) = D5CDD505-2E9C-101B-9397-08002B2CF9AE "Date completed"

For other Office properties, see the Microsoft Office Software Developer's Kit (SDK). For properties available with other products, see the documentation for each independent software vendor that supplies an IFilter implementation.


Query Section of .Idq Files

The query section of the .idq file specifies parameters that are used in the query. It can refer to form variables and can include conditional expressions to set a variable to alternative values depending upon some condition.

This topic contains the following topics:

  • Sample Query Section
  • Conditional Expressions
  • Security Considerations


Sample Query Section

Begin by writing a [Query] tag, and then add a set of parameters. The following example assumes that you have taken these steps:

  • Created a virtual directory called Scripts.
  • Given this directory Script permission.
  • Put Simple.idq and Template.htx into the Scripts directory.

Here is a simple .idq file:

[Query]
CiScope=/
CiColumns=FileName
CiRestriction=#filename *
CiTemplate=/Scripts/Template.htx

The preceding four parameters are required. In many cases, one or more parameters will be passed down from a form. Here is a very simple form:

<FORM ACTION="/scripts/simple.idq" METHOD="GET">
Query : <INPUT TYPE="TEXT" NAME="Restriction" SIZE="60" MAXLENGTH="100" VALUE="">
<INPUT TYPE="SUBMIT" VALUE="Execute Query">
</FORM>

This form can work with the following .idq file to pass parameters from the user:

[Query]
CiScope=/
CiColumns=FileName
CiRestriction=%Restriction%
CiTemplate=/Scripts/Template.htx

The CiRestriction parameter specifies the query string. In addition to the four required parameters, there are many optional parameters you can add, such as CiSort and CiForceUseCi. For details, see the full list of parameters in Variables in Forms and in .Idq Files.


Conditional Expressions

You can add if-then-else conditional logic to control the substitution of variables and parameters. The syntax is similar to conditional expressions in .htx files, but not exactly the same.

Syntax

The following rules apply to conditional expressions in .idq files:

  • Lines in your .idq file must start with the variable name you're trying to set.
  • Only one line can set a particular variable in an .idq file.
  • Make sure variable references and statements are surrounded by percent signs (%).

The following example shows how to set the CiRestriction variable:

CiRestriction=%if Restriction ISEMPTY%Index Server Help%else%%Restriction%%endif%

This example stops users from running empty searches.

The following list shows the possible operators in If statements for .idq files:

EQ
if value1 equals value2
NE
if value1 does not equal value2
LT
if value1 is less than value2
LE
if value1 is less than or equal to value2
GT
if value1 is greater than value2
GE
if value1 is greater than or equal to value2
CONTAINS
if any part of value1 contains the string value2
ISEMPTY
TRUE if value1 is a Null string. This is a unary postfix operator.


Security Considerations

Be careful when substituting parameters for the CiTemplate parameter because you could unintentionally allow files in scripts directories with only Execute permission to be sent over the network. For example, if an .idq file contained the line

CiTemplate=%CiTemplate%

a client could send a Uniform Resource Locator (URL) that contained the following line in the query string:

CiTemplate=/scripts/mysecretfile.pl

With this string, an unauthorized user could read the contents of a confidential file.

It is better to switch among different .htx files by just using the base name of the file and adding the script directory and file name extension in the parameter substitution. The following file, Sample.idq, shows how to do this:

[Query]
CiRestriction=%q%
CiTemplate=/scripts/%t%.htx
CiSort=%s%
CiScope=/

The query can be executed with a URL like the following:

http://computername/scripts/sample.idq?q=ActiveX&t=form1

Note A URL or a form-based query can send up to 4 kilobytes (KB) of data. If a query larger than 4 KB is sent, the behavior is unpredictable. The query size includes all variables sent from the browser to the .idq file.


Effect of Parameters on Query Performance

The fastest query is a sequential query that uses the content index. Certain parameter settings will force the query engine to use a less-efficient method to resolve the query. To guarantee fast queries, set CiSort to nothing (or descending by rank) set CiForceUseCi to TRUE, and do not reference CiMatchedRecordCount, CiRecordsNextPage, or CiTotalNumberPages in the .htx template.


Sequential vs. Nonsequential Execution

A query can be executed sequentially (results fetched as needed) or it can be executed nonsequentially (results cached on the server). A sequential query requires fewer server resources, but also has some limitations. Backward scrolling (CiBookmarkSkipCount< 0) will re-execute the query and scroll forward to the specified position. Sequential queries cannot refer to the following variables: CiMatchedRecordCount, CiRecordsNextPage, and CiTotalNumberPages.

Either of the following actions will force a query to be nonsequential:

  • Referring to the CiMatchedRecordCount, CiRecordsNextPage or CiTotalNumberPages variables in the .htx page.
  • Setting the CiSort parameter to sort of query results other than the native order of the result. CiSort can safely be set to sort ascending on WorkId (CiSort=WorkId[a]) or descending on Rank (CiSort=Rank[d]).


Enumerated vs. Indexed Resolution

Executing queries that must be enumerated can also slow down performance. Most queries are resolved by using the Content Index, but certain conditions force the query engine to search the disk to locate matching files. These queries include:

  • Regular expressions on properties other than FileName which begin with any special regular expression character.
  • Regular expressions on FileName which both begin and end with any special regular expression character.
  • Property value queries when the CiForceUseCi parameter is set to FALSE and the index is not up to date.
  • Property value queries involving regular expressions that start and end with any special regular-expression characters (for example, #filename *sample*).
  • Certain property value queries involving OR (such as @write > -1d OR @create > -1d).

Queries can be forced to use the Content Index by setting CiForceUseCi to TRUE in the .idq file. The query engine will always use the Content Index, but query results may be out of date for recently modified files. If the Content Index was used for a query, and some files on disk have been modified more recently than their contents have been filtered, the built-in variable CiOutOfDate will be set to the value 1. In some cases, a query is simply too complex to be resolved solely through use of the Content Index. In these cases, the built-in variable CiQueryIncomplete will be set to 1. Content queries can always be out of date and can use the Content Index anytime.


Deferring Nonindexed Trimming

Special support has been added to Indexing Service to optimize content queries that are sorted by descending rank (CiSort = Rank[d]). For such queries, minimal information can be retrieved from the index, before additional property and security tests are performed. However, if the total number of results matching the query is greater than CiMaxRecordsInResultSet then additional testing must be performed during index retrieval to remove items from this set that fail additional property and security tests. This frees space in the result set for items matching the full query. This processing uses up resources, and can be deferred by setting CiDeferNonIndexedTrimming to TRUE. The query will then pick CiMaxRecordsInResultSet items first, and trim them. The end result may be a number of matching items that is less than CiMaxRecordsInResultSet. For queries with the scope set to the entire corpus, on a server with little or no security, you can consider setting CiDeferNonIndexedTrimming to TRUE to improve performance.


Setting Up the Form (.Htm File)

The following example shows a basic query form:

To create a basic query form as in the example

  1. Type the following HTML code in a file.
  2. Save the file in HTML format.
    <HTML>
<HEAD>
    <TITLE>Indexing Service Search Form</TITLE>
</HEAD>
<BODY>
<FORM ACTION="ixtourqy.idq" METHOD="GET">
Search for:
<INPUT TYPE="TEXT" NAME="CiRestriction" SIZE="30" MAXLENGTH="100" VALUE="">
<INPUT TYPE="SUBMIT" VALUE="Execute Query">
<INPUT TYPE="RESET" VALUE="Clear">
</FORM>
</BODY>
</HTML>

The two most important lines of HTML code are:

<FORM ACTION. . .>
Tells where to find the .idq file that goes with this form. Because an .idq file helps process an Indexing Service query form, every Indexing Service query form must specify a corresponding .idq file.
<INPUT TYPE="TEXT". . .>
Defines a variable called CiRestriction. This variable is preset to accept whatever text is typed into the query field (the Search for field, in the example). For example, if you type cache in this field, CiRestriction holds the text cache.

When the Execute Query button is clicked, the data in the text field is sent to IIS and processed. IIS finds the specified .idq file and passes the query data and the .idq file to Indexing Service. To learn how to construct complex queries, see Query Languages for Indexing Service.


Controlling the Search (.Idq File)

The Internet Data Query (.idq) file defines query parameters such as the scope of your search, any restrictions, and query results sets. The following example shows a basic .idq file:

[Query]
# CiCatalog=d:\ <= COMMENTED OUT - default registry value used
CiColumns=filename,size,rank,characterization,vpath,DocTitle,write
CiRestriction=%CiRestriction%
CiMaxRecordsInResultSet=300
CiMaxRecordsPerPage=10
CiScope=/
CiFlags=DEEP
CiTemplate=/iissamples/issamples/ixtourqy.htx
CiSort=rank[d]
CiForceUseCi=true

The following list explains each line of the sample .idq file:

[Query]
Identifies the following information as a query restriction.
CiCatalog=d: \
Points to the index to use. In this case, the statement is commented out, so a default is used.
CiColumns=filename,size,rank,characterization, vpath,DocTitle,write
Indicates the kind of information to return in the result set.
CiRestriction=%CiRestriction%
Indicates the query terms to search for. In this case, the CiRestriction form parameter is used.
CiMaxRecordsInResultSet=300
Sets the maximum number of results to be returned; in this example, 300.
CiMaxRecordsPerPage=10
Determines how many results are shown on each Web page returned. In this case, 10 results will be shown per Web page.
CiScope=/
Tells where to start the query. In this example, the query starts at the root of the virtual directory space. You can list more than one virtual directory in your scope by separating the directories with a comma (,). For example: CiScope=/docs,/work,/school
CiFlags=DEEP
Instructs the query to search all subdirectories within the scope.
CiTemplate=/iissamples/issamples/ixtourqy.htx
Indicates which file to use to format the results; in this case, Ixtourqy.htx.
CiSort=rank[d]
Tells how to sort the results. This example calls for results to be listed in descending [d] rank order; that is, the results are listed in order from the file with the most hits to the file with the least hits.
CiForceUseCi=true
This is an optional variable that, when set to TRUE, forces Indexing Service to search the content index even if it is out of date.

When the results are returned in raw format, Indexing Service formats the results according to the .htx file specified in the CiTemplate parameter.

For details about the .idq file and how to format it, see Internet Data Query Files.


HTML Extension Files

HTML extension (.htx) files for Indexing Service are similar to HTML extension files for the Internet Database Connector (IDC). There are some slight differences, however. For example, for Indexing Service, .idq files will reference .htx files, but for the IDC, .idc files will reference .htx files.

This section explains the features of Indexing Service extension files.

  • Query Result Pages: Describes the query results page, which is formatted in the .htx file.
  • Syntax in HTML Extension Files: Discusses the syntax in .htx files.
  • Query Execution Parameters: Describes built-in variables available to the .htx file to flag any unexpected query results.
  • Formatting the Results (.Htx File): Describes the format of the HTML extension (.htx) file.
  • Record Numbers and Counts: Discusses record-number and count built-in variables.
  • Parameters from Internet Data Query Files: Explains predefined parameters that can be set in .idq files.
  • Navigating Between Pages in Query Results: Tells how to add navigational aids to your results pages.
  • HTTP Variables: Lists and explains default HTML variables.
  • Variables Affecting the Formatting of Results: Describes variables that control how a results page will look.
  • Error Pages: Describes error types that can cause an error page to be displayed.

Note All path names to .htx files must be either full virtual paths or full physical paths with no "." or ".." components. This applies to .htx files referenced in CiTemplate or as include files.

Do not put these files on a virtual root pointing to a remote Uniform Naming Convention (UNC) share.


Query Result Pages

Indexing Service uses the .htx file mainly to format the results of a query. Query results are split into pages based upon the parameter CiMaxRecordsPerPage. The total number of query result records is governed by the parameter CiMaxRecordsInResultSet. The current page number in the result set is given in the variable CiCurrentPageNumber. For a nonsequential query, the CiTotalNumberPages variable gives the total number of pages in the result and CiRecordsNextPage gives the number of records on the next page. The variables CiContainsFirstRecord and CiContainsLastRecord indicate if the current page is the first or last in the result set. For an example of how to navigate between pages See Navigating Between Pages in Query Results.


Syntax in HTML Extension Files

This section discusses the syntax in .htx files. The syntax is divided into these areas:

  • <% begindetail %>, <% enddetail %>
  • <% if %>, . <% else %>, . <% endif %>
  • <%EscapeHTML%>, <%EscapeURL%>, <%EscapeRAW%>

<% begindetail %>, <% enddetail %>

The <%begindetail%> and <%enddetail%> tags surround a section of the HTML extension file in which the results of the search will be merged. The section will be interpreted once for each record matching the query on the page. Within the section, the column names delimited with <% and %> are used to mark the position of the returned data from the query. There can be only one detail section in the HTML extension file.

For example:

<dl>
<%begindetail%><p>
<dt>
<%CiCurrentRecordNumber%>.
<b><a href="<%vpath%>"><%filename%></a></b>
<dd>
<b><i>Abstract: </i></b><%characterization%><br>
<font size=-1> - size <%size%> bytes - <%write%> GMT</font>
<%enddetail%></dl>

This query does the following:

  • Shows the name of the file where the search string originates.
  • Gives a brief abstract of the file.
  • Shows the size of the file in bytes.
  • Shows when the file was last modified.

Note If there are no records returned from the query, the <%begindetail%> section will be skipped.

<% if %>.. <% else %>.. <% endif %>

HTML extension files can contain conditional logic with an if-then-else statement to control how the Web page is constructed. For example, one common usage is to insert a condition to display a header for the query on the first row within a <%begindetail%> section. If there are no records returned by the query, the HTML extension file displays the text "Sorry, no authors had YTD sales greater than" %sales%. By using the <%if%> statement and a built-in variable called CiLastRecordNumber, you can tailor the output so that the error message is printed when no records are returned. Here is an example showing the use of the <%if%> statement.

  <%begindetail%>
      <%if CiCurrentRecordNumber EQ 1%>
        Query results:
        <B>Author YTD Sales<BR></B>
      <%endif%>
      <%au_lname%>$<%ytd_sales%>
    <%enddetail%>
    <P>
    <%if CiLastRecordNumber EQ 0%>
      <I><B>Sorry, no authors had YTD sales greater than </I><%sales%>.</B>
      <P>
    <%else%>
    <HR>
      <I>
      The Web page you see here was created by merging the results
      of the Content query with the template file Sample.htx.
      <P>
      The merge was done by Indexing Service and
      the results were returned to this Web browser by
      Internet Information Services (IIS).
      </I>
    <%endif%>
    </BODY>
    </HTML>

The general syntax is:

   <%if condition%>
    HTML text
    [ <%else%>
      HTML text ]
    <%endif%>

where the condition is of the form value1 operator value2 and operator can be one of the following:

EQ
if value1 equals value2
NE
if value1 does not equal value2
LT
if value1 is less than value2
LE
if value1 is less than or equal to value2
GT
if value1 is greater than value2
GE
if value1 is greater than or equal to value2
CONTAINS
if any part of value1 contains the string value2
ISTYPEEQ
allows the .htx file to determine the VT_TYPE of a particular variable.

value1 IsTypeEq value2 value1 IsTypeEq const1 const1 IsTypeEq value1

For example, if a variable is of type currency (VT_CY), its type is 6. Type numbers are defined in the ActiveX specification. A valid .htx comparison would be:

<%if propName IsTypeEq 6%>Variable is of type currency
<%else%>Variable is NOT type currency
<%endif%>

This operator is especially useful to check for type VT_EMPTY, an empty property.

ISEMPTY
TRUE if value1 is of type VT_EMPTY, or of type VT_NULL, or is of a textual type (VT_LPSTR, VT_LPWSTR, VT_BSTR, or vectors of the preceding types) and contains only "empty" characters (space, tab, and so on.)

The operands value1 and value2 can be column names, one of the built-in variables, an HTTP variable name (see HTTP Variables), or a constant. When used in an <%if%> statement, values are not delimited with <% and %>. For example, to do special processing on author name "Green," use the condition:

    <FORM ACTION="<%HTTP_SCRIPT_NAME%>?" METHOD="POST">
      <%if au_lname EQ "Green"%>
        this guy is green!
      <%endif%>
    <%enddetail%>

The <%if%> statement can also be used to do special processing based on information from HTTP variables. For example, to format a page differently for a different type of client Web browser (in this case, Netscape Navigator), you could include the following in the HTML extension file.

    <%if HTTP_USER_AGENT contains "Mozilla"%>
      client supports advanced HTML features
    <%else%>
      client is <%HTTP_USER_AGENT%>
    <%endif%>

Property types VT_FILETIME and VT_DATE can be compared within <%if%> statements. Use the following format:

<%if fileTime eq "yyyy/mm/dd hh:mm:ss:iii"%>File times are identical
<%endif%>

The time must be enclosed in quotes. The year must be a four-digit number (for example, 1996, not 96), and slashes and colons are required.

yyyy = year

mm = month ( 1=January, 12=December, and so on)

dd = day of month ( 1 - 31)

hh = hour of the day in 24-hour format (optional)

mm = minutes (optional)

ss = seconds (optional)

iii = milliseconds (optional)

For example:

<%if write le "1996/07/21 17:22:11:333"%>File times are identical
<%endif%>

<%EscapeHTML%>, <%EscapeURL%>, <%EscapeRAW%>

The <%EscapeHTML%>, <%EscapeURL%>, and <%EscapeRAW%> keywords can be used to affect the formatting of output strings. These are typically used with variables such as CiRestriction or with CiScope when used in a form or in an anchor.

The output of variables is normally suitable for HTML format. The preceding keywords affect the output format so that the variable can be used correctly in different contexts. The form of the construct is:

<%EscapeHTML variable%>     or
<%EscapeURL variable%>      or
<%EscapeRAW variable%>

where variable is any parameter or variable that could be used in the HTTP Extension file. Constant values can also be used, as in, <%EscapeURL /scripts/query.idq%>.

<%EscapeHTML%> (the default formatting) is used to escape characters that are meaningful in HTML. For example, the symbol > will appear as &gt;.

<%EscapeURL%> is used to do standard escaping for strings that will be URLs (as in the HREF tag of an anchor). For example, the string @size > 10000; will appear as %40size+%3E+10000.

<%EscapeRAW%> is used when no escaping should be done. This might be the case for a variable that is being used as the value of a form variable, or to have the value of a variable that contains HTML code to be interpreted correctly.

File Inclusion

The <%include%> keyword can interpolate the contents of a file into the .htx file. The syntax of the construct is

<%include filename%>

where filename is the name of the file to be included. The file is named with a full virtual path name, and HTML extension constructs are interpreted if found in the file. File includes can be nested, but the total number of include files cannot exceed 31.


Query Execution Parameters

A number of situations leading to unexpected query results are flagged by using built-in variables available in the .htx file. Most .htx pages should include a <%if...%> test on these variables.

CiOutOfDate will be set to the value 1 if the content index has files to filter or scans to complete. Missing results are possible because information about particular documents is either from an old version of the document or missing. When this variable is set, it is possible to get results including deleted files, and files whose current version does not match the query.

CiQueryTimedOut will be set to the value 1 when the amount of CPU time spent executing the query exceeds the limit specified in the MaxQueryExecutionTime parameter in the registry. The variable will be valid for all pages in the result for nonsequentially executed queries. For sequentially executed queries, the CiQueryTimedOut variable is valid only after all available results for the query have been displayed.

CiQueryIncomplete will be set to the value 1 if some portion of the query restriction was ignored. This can occur when a query is forced to use the Content Index.


Formatting the Results (.Htx File)

The HTML extension (.htx) file is an HTML file containing variables that refer to data in a query results set. The following example defines a page header that displays the query restriction and the documents displayed on the page that the user sees. This file is written to work with the variables in the sample .idq file.

<H4>
<%if CiMatchedRecordCount eq 0%>
No documents matched the query "<%EscapeHTMLCiRestriction%>".</H4>
<%else%>
<H4>Documents <%CiFirstRecordNumber%> to <%CiLastRecordNumber%> of
<%if CiMatchedRecordCount eq CiMaxRecordsInResultSet%>
the first
<%endif%>
<%CiMatchedRecordCount%> matching the query
"<%EscapeHTMLCiRestriction%>".
<%endif%>
</H4>

The text in the sample .htx file produces the following:

Documents 1 to 10 of the first 150 matching the query "cache".

This example shows that the .htx file is a template that formats how results are returned and displayed to the user. The file is written in HTML format with some extensions supplied by IIS and Indexing Service. These extensions include variable names and other codes for processing results. For details about the .htx file and how to format it, see HTML Extension Files.


Record Numbers and Counts

The CiCurrentRecordNumber built-in variable contains the record number of the current record (1-based). The record number starts at [(page-number - 1) * records-per-page] + 1 for any page. Each time through the <%begindetail%> section, the value of CiCurrentRecordNumber increases by one.

The CiMatchedRecordCount built-in variable contains the value of the total number of records matched in the query (limited to CiMaxRecordsInResultSet). The CiRecordsNextPage built-in variable contains the number of records that will appear on the next page. Referring to either CiMatchedRecordCount or CiRecordsNextPage will cause the query to be nonsequential.


Parameters from Internet Data Query Files

A number of predefined parameters are supplied, which can be set in the Internet Data Query (.idq) files. See Variables in .htx and .idq Files.

In addition, any Common Gateway Interface (CGI) variable, form parameter, or variable defined in an .idq file can be referred to in the HTML extension file by enclosing the variable name in <% and %>. If a variable is referred to that has not been assigned a value, the variable reference will be sent unchanged.


Navigating Between Pages in Query Results

The first record on a page is identified in the variable CiBookmark, which can be used in a form to get to the next page or the previous page. The form variable CiBookmarkSkipCount should be used with CiBookmark to specify the relative offset from the current page. CiBookmarkSkipCount is typically set to either <%CiMaxRecordsPerPage%> or <%CiMaxRecordsPerPage%>, although it could be set to other multiples of CiMaxRecordsPerPage.

Here is an example of a form that will skip to the next page for a sequential query:

     <FORM ACTION="<%HTTP_SCRIPT_NAME%>?" METHOD="POST">
      <INPUT TYPE="HIDDEN"
             NAME="CiBookmark"
             VALUE="<%CiBookmark%>" >
      <INPUT TYPE="HIDDEN"
             NAME="CiBookmarkSkipCount"
             VALUE="<%CiMaxRecordsPerPage%>" >
      <INPUT TYPE="HIDDEN"
             NAME="CiMaxRecordsPerPage"
             VALUE="<%CiMaxRecordsPerPage%>" >
      <INPUT TYPE="HIDDEN"
             NAME="CiRestriction"
             VALUE="<%CiRestriction%>" >
      <INPUT TYPE="HIDDEN"
             NAME="CiScope"
             VALUE="<%CiScope%>" >
      <INPUT TYPE="SUBMIT" VALUE="Next page">
    </FORM>

The following example shows how the buttons for going to adjacent pages can be generated conditionally depending upon the variables CiContainsFirstRecord and CiContainsLastRecord. It also shows how the number of hits on the next page can be displayed for a nonsequential query.

<TABLE> <TR>
    <TD> <%if CiContainsFirstRecord eq 0%>
     <FORM ACTION="<%HTTP_SCRIPT_NAME%>?" METHOD="POST">
        <INPUT TYPE="HIDDEN"
               NAME="CiBookmark"
               VALUE="<%CiBookmark%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiBookmarkSkipCount"
               VALUE="-<%CiMaxRecordsPerPage%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiMaxRecordsPerPage"
               VALUE="<%CiMaxRecordsPerPage%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiRestriction"
               VALUE="<%CiRestriction%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiScope"
               VALUE="<%CiScope%>" >
        <INPUT TYPE="SUBMIT" VALUE="Previous <%CiMaxRecordsPerPage%> Hits">
      </FORM>
    <%endif%> </TD>
    <TD> <%if CiContainsLastRecord eq 0%>
     <FORM ACTION="<%HTTP_SCRIPT_NAME%>?" METHOD="POST">
        <INPUT TYPE="HIDDEN"
               NAME="CiBookmark"
               VALUE="<CiBookmark%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiBookmarkSkipCount"
               VALUE="<%CiMaxRecordsPerPage%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiMaxRecordsPerPage"
               VALUE="<%CiMaxRecordsPerPage%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiRestriction"
               VALUE="<%CiRestriction%>" >
        <INPUT TYPE="HIDDEN"
               NAME="CiScope"
               VALUE="<%CiScope%>" >
        <INPUT TYPE="SUBMIT" VALUE="Next <%CiRecordsOnNextPage%> Hits">
      </FORM>
    <%endif%> </TD>
    </TR> </TABLE>


HTTP Variables

Several variables in HTML extension files can give a lot of information about the environment and Web client connected to the server. In addition, all headers sent by the client are available. For Indexing Service to access these headers, you must convert them:

  1. Add HTTP_ to the beginning.
  2. Convert all hyphens to underscores.
  3. Convert all letters to uppercase.

The following list gives a listing of default variables.

ALL_HTTP
All HTTP headers that were not already parsed into one of the listed variables. These variables are of the form HTTP_header field name with successive variables separated by a new line character, for example:

HTTP_ACCEPT: */*, q=0.300, audio/x-aiff, audio/basic, image/jpeg, image/gif, text/plain, text/html

HTTP_USER_AGENT: Microsoft Internet Explorer/0.1 (Win32)

HTTP_REFERER: http://webserver/samples/dbsamp/dbsamp3.htm

HTTP_CONTENT_TYPE: application/x-www-form-urlenPRE: 10

HTTP_EXTENSION: Security/Digest

AUTH_TYPE
The type of authorization in use. If the user name has been authenticated by the server, this will contain Basic. NTLM returns the value Negotiate. Otherwise, it will not be present.
CONTENT_LENGTH
The number of bytes that the script can expect to receive from the client.
CONTENT_TYPE
The content type of the information supplied in the body of a request by a POST variable.
GATEWAY_INTERFACE
The revision of the CGI specification with which this server complies. The current version is Common Gateway Interface 1.1.
HTTP_ACCEPT
Special-case HTTP header. Values of the Accept: fields are concatenated, separated by ", "; for example, if the following lines are part of the HTTP header: accept: */*; q=0.1 accept: text/html accept: image/jpeg then the HTTP_ACCEPT variable will have a value of: */*; q=0.1, text/html, image/jpeg.
PATH_INFO
Additional path information, as given by the client. This comprises the trailing part of the URL after the script name but before the query string (if any).
PATH_TRANSLATED
This is the value of PATH_INFO, but with any virtual path name expanded into a directory specification.
QUERY_STRING
The information that follows the question mark (?) in the URL that referenced this script.
REMOTE_ADDR
The IP address of the client.
REMOTE_HOST
The host name of the client.
REMOTE_USER
This contains the user name supplied by the client and authenticated by the server.
REQUEST_METHOD
The HTTP request method.
SCRIPT_NAME
The name of the script program being run.
SERVER_NAME
The server's host name (or IP address) as it should appear in self-referencing URLs.
SERVER_PORT
The TCP/IP port on which the request was received.
SERVER_PROTOCOL
The name and version of the information-retrieval protocol relating to this request, usually HTTP 1.0.
SERVER_SOFTWARE
The name and version of the Web server under which the Internet Server Extension is running.


Variables Affecting the Formatting of Results

Some variables that can be set in the .idq file affect the formatting of data in the .htx file. The variable CiLocale can be set to affect the formatting of dates, times, currency values, and floating-point numbers according to NLS conventions. If CiLocale is not set, the locale is set from the client's browser or the server's default locale, in order of priority.

To change the formatting of data types, modify format settings as needed in the Regional Settings in the system Control Panel.

A set of variables taken from the .idq file will be used to enclose and separate elements of column values that are vectors. Unlike all other variables set in the .idq file, these variables cannot be referred to explicitly in the .htx file:

  • CiCurrencyVectorPrefix
  • CiCurrencyVectorSeparator
  • CiCurrencyVectorSuffix
  • CiDateVectorPrefix
  • CiDateVectorSeparator
  • CiDateVectorSuffix
  • CiNumberVectorPrefix
  • CiNumberVectorSeparator
  • CiNumberVectorSuffix
  • CiStringVectorPrefix
  • CiStringVectorSeparator
  • CiStringVectorSuffix


Error Pages

Through settings in the Windows 2000 registry, it is possible to configure .htx files that are displayed in case errors ar encountered while executing a search. Any of the file's error types can cause an error page to be displayed:

Query error
An error in a query specification (CiRestriction). This is most likely a user error.
Error in HTML extension file
An error was found while formatting the .htx file. This is probably a configuration error.
Error in Internet Data Query (.idq) file
An error was found in the query parameter file. This is probably a configuration error, although it might also occur due to unexpected data input from a form.
Some other error
An unspecified error occurred.

Error pages have access to some of the variables available to .htx files. In addition, there is a variable CiErrorMessage, which gives a message describing the error. See .Idq File Errors and .Htx File Errors for a list of the possible values of CiErrorMessage, and Error Messages and Error Pages for details on Indexing Service error messages.


Support for Multiple Languages

Many Web pages today are written in English, but others are not. Because IIS can serve documents in many languages, multilingual indexing and querying features are a standard feature of Indexing Service. The query system was built with localization in mind. It is completely modular and can dynamically load and unload language-specific utilities. These utilities include word breakers, stemmers, and normalizers. These linguistic components are available for several languages.

Indexing Service can index multilingual documents and switch between languages as required (for example, index an English paragraph, index a French paragraph, and switch back to English). All index information is stored as Unicode characters, and all queries are converted to Unicode before they are processed.

Indexing Service does not distinguish between language once the words have been entered into the index. It is possible to return documents written in a language different from the language posted in the query. In many cases this is appropriate. For example a query for Windows 95 will return a French document that contains the English phrase Windows 95. In some cases languages contain words known as homologues — words that are spelled the same in two or more languages but have very different meanings. Indexing Service does not distinguish these cases because Indexing Service does not perform any language translation.

Finally, you should know that mixing languages can yield unpredictable results. For example, if you set the multilanguage form to German and query for English words, the results likely will not be the same if the identical query were posted with the language set to English. This is because Indexing Service is using the German linguistics modules to analyze the query field to determine which words and phrases to search for (that is, it is trying to perform German word breaking on English text). The German word breaker assumes German grammar when it breaks textual characters into words, so it often generates wrong word-break results when breaking non-German text.

This section contains:

  • Querying a Site Without Language Resources: Lists the languages shipped with Indexing Service and describes the effect of issuing queries to sites without language resources.
  • Setting Language Codes in HTML Files: Tells how to use the MS.Locale property in HTML files.
  • Getting Browsers to Recognize Different Languages: Explains the effects of the HTTP_ACCEPT_LANGUAGE variable on CiLocale variable settings.
  • Displaying Results Correctly: Tells how to get browsers to display correct results in the correct language through the variable CiCodepage.


Querying a Site Without Language Resources

Indexing Service ships with several languages, which you can install on your site during setup. For a list of these languages, see the Indexing Service Web page. For instructions about setting up Indexing Service and choosing the languages you want to install, see Getting Started.

If a site does not have a particular language resource installed, Indexing Service sends you results in the format for the locale set for the system. But if you query the same site and specify CiLocale for the document, the results are returned with the CiLocale setting Neutral.

For example, suppose a site in the United States has some documents in Russian. The site has a CiLocale value of US, for American English. If you query that site for all documents in Russian and you specify the CiLocale value as RU, Indexing Service displays the documents in Russian. If you sent your query without specifying CiLocale, Indexing Service borrows the system CiLocale (US), and you would not be able to read the results.


Setting Language Codes in HTML Files

If you had a Web site containing documents in different languages, you could set the MS.Locale property in each document for queries on documents in a certain language, and set the Content-Type variable so that the proper character set is displayed in the results. You should set both of these variables if your HTML pages are written in different languages.


Setting MS.Locale

The MS.Locale meta tag specifies the language in which the document is written. This property also tells Indexing Service to use the correct locale-specific resources when processing the HTML page. You should set this variable when the HTML pages being indexed are on sites in different locales. If all the HTML pages being indexed are in the same locale as the server where Indexing Service is installed, then you do not have to include this property in your HTML files.

For example, to designate a locale of Japanese, set your MS.Locale meta tag as follows:

<META NAME="MS.LOCALE"   CONTENT="JA">

When you have included MS.Locale in your HTML files, clients can query for that property, as with any other meta tag property. For example, to see all the files in Japanese, send the following query:

@Locale JA

Locale is not a default property in Indexing Service. For the query @Locale JA to work, you must first define the Locale meta property. To define the meta property, see Defining New Property Names for a Web Catalog. To find a list of recognized locale codes, see Valid Locale Identifiers.


Setting Charset

The Charset attribute is the part of the HTTP-EQUIV meta tag that specifies the character set of an HTML page. Indexing Service uses this character set to display the text in the HTML page in the proper characters. In a file written in Japanese, you would set the Charset to shift_jis as shown in the following example:

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=shift_jis">

To find a list of recognized character set codes, see Recognized Character Set Tags.


Getting Browsers to Recognize Different Languages

If you set CiLocale in your .idq files, you can override the locale sent from a browser. The Web browser sends its locale through the HTTP_ACCEPT_LANGUAGE variable. To find a list of recognized locale codes, see Valid Locale Identifiers.

Instead of overriding the locale sent by a browser, you may want to use the locale sent by a browser that is querying text in variety of languages. For example, given a single HTML page, one query could be for German text (CiLocale=De) and another could be for Spanish text (CiLocale=Es). If CiLocale is not found in the .idq file the locale sent by the Web browser is used. If no locale is sent by the browser, Indexing Service uses the locale of the Web server.

The following table show examples of three types of settings. Each setting specifies a different source from which the value of CiLocale is taken:

CiLocale Setting in .Idq | Value Source
CiLocale=En-US | Web site (set in the .idq file)
CiLocale=%CiLocale% | HTML page (set in the query form)
CiLocale= | Web browser (from HTTP_ACCEPT_LANGUAGE)


Displaying Results Correctly

This section tells how you can make sure query results are displayed correctly both as a Web site administrator who expects queries from different locales and as a client querying a locale different from the HTTP_ACCEPT_LANGUAGE setting in your browser.

This section contains:

  • Returning Results to a Different Locale
  • Querying a Site in a Different Locale


Returning Results to a Different Locale

If you are expecting queries from sites in different locales, you can set CiCodepage in the .htm file .htx (and .htw) file to make sure results are displayed correctly when returned to the client.

You can set the value of CiCodepage to CiCodepage=<%CiCodepage%> through the URL. Indexing Service takes the value sent by the browser to parse the query with the proper character set. If the CiCodepage variable is set with the same CiCodepage value that is in the .idq file, the CiCodepage variable can be referenced in the .htx or .htw file to display the result in the proper character set.


Querying a Site in a Different Locale

When querying a site for documents in different languages, you can send a CiCodepage variable in the URL to override the codepage character setting on the server and in the HTTP_ACCEPT_LANGUAGE variable in your browser. For example, suppose a client by the name of Yukio from Japan wants to query a site in the United States that contains documents in American English. Yukio wants a list of all documents containing the word cache. By appending the CiCodepage variable to his query, he can override the HTTP_ACCEPT_LANGUAGE setting in his browser, making sure the query results will be returned in English.

In the following example, Yukio is querying a server called Example, located at example.microsoft.com, and a virtual directory called Software.

http://example.microsoft.com/software/[form.htm]

In the search form, Yukio then types:

Cache&CiLocale=EN&CiCodepage=Windows-1252


Variables in .Idq and .Htx Files

This topic contains a description of variables that are used in Indexing Service's ISAPI implementation.

  • Read-Only Variables Available in .Htx Files: Lists and describes read-only variables for .htx files.
  • Variables in Forms and in .Idq Files: Lists and explains variables that can be set in forms, in .idq files, or as CGI variables.
  • String Variables Useful for Formatting Displayed Columns: Lists and gives the meanings for variables that you can set in the .idq file but cannot use to refer to other parameters.
  • Parameter for Use with Bookmarks: Explains how the CiBookmarkSkipCount variable, in conjunction with CiBookmark, sets an offset from the previous page of the query.
  • Standard Common Gateway Interface Variables Available: Lists the variables that are normally set by CGI program execution and that can be referred to in the .idq or .htx files.
  • Valid Locale Identifiers: Shows valid locale identifiers (LCIDs) for use in CiLocale.
  • Recognized Character Set Tags: Lists the ISO codes currently recognized by Indexing Service and the HTML filter, for use in CiCodepage.


Read-Only Variables Available in .Htx Files

The following variables are available for use in .htx files. These are set based upon the results of the search. In addition, the other .idq variables mentioned below can be used in the .htx file. In the detail section of the .htx file, any output columns mentioned in the CiColumns parameter can also be used.

Variable Name | Meaning
CiBookmark | Reference to the first row on the page.
CiContainsFirstRecord | Set to 1 if this page contains the first record of the query results; 0 otherwise.
CiContainsLastRecord | Set to 1 if this page contain the last record of the query results; 0 otherwise. For a sequential query, this will not be accurate until after the <%enddetail%>section in the .htx file.
CiCurrentPageNumber | Current page number of query results (that is, page number x of y pages).
CiCurrentRecordNumber | Number displayed for current record.
CiErrorMessage | Error message. Available only for error pages. See Error Messages and Error Pages for possible error messages.
CiErrorNumber | Error number. Available only for error pages.
CiFirstRecordNumber | Record number of first record on a page.
CiLastRecordNumber | Last record number on a page. For a sequential query, this will not be accurate until after the <%enddetail%> section in the .htx file.
CiMatchedRecordCount | Total number of records matching a query. Referring to this variable from the .htx file will force the search to use a nonsequential query.
CiOutOfDate | Set to 1 if the content index is out of date; 0 otherwise.
CiQueryIncomplete | Set to 1 if the query could not be resolved using the content index and CiForceUseCI was set; 0 otherwise.
CiQueryTimedOut | Set to 1 if the query exceeded the time limit for execution; 0 otherwise.
CiQueryDate | Date (at the Web server) the query was executed.
CiQueryTime | Time (at the Web server) the query was executed.
CiQueryTimeZone | Time zone of the Web server.
CiRecordsNextPage | Number of records on the next page. Referring to this variable from the .htx file will force the search to use a nonsequential query.
CiTotalNumberPages | Total number of pages used to contain query results. Referring to this variable from the .htx file will force the search to use a nonsequential query.
CiVersionMajor | The major version of Indexing Service.
CiVersionMinor | The minor version of Indexing Service.


Variables in Forms and in .Idq Files

The following table lists the variables that can be set in .idq files or set as CGI variables and referred to in .htx files. You can also set these variables in forms, or you can give them as parameters to a direct execution of the .idq file.

Variable Name | Meaning
CiCatalog | Override for the location of the catalog; defaults to the IsapiDefaultCatalogDirectory registry entry if it is set.
CiCodepage If CiCodepage is sent in a Uniform Resource Locator (URL) to generate hit-highlighting, Indexing Service uses the setting in CiCodepage, overriding the HTTP_ACCEPT_LANGUAGE setting in the browser and overriding the server's code page setting. If CiCodepage is not specified in a query, the server uses the default code page in the browser's HTTP_ACCEPT_LANGUAGE setting. If CiCodepage and HTTP_ACCEPT_LANGUAGE are not set, Indexing Service uses the system's code page.

In your request, specify either a number (to imply a Win32 code page) or a string, which is interpreted as International Organization for Standardization (ISO) code. For a list of codes accepted by Indexing Service and the HTML filter, see Recognized Character Set Tags.

You can also build the CiCodepage tag into an .htx file if it was sent in a URL to generate hit highlighting. For example:

<HEAD>
<TITLE>Query results</TITLE>
<META HTTP-EQUIV="Content-Type" CONTENT="test/html; charset=<%CiCodepage%>">
</HEAD>
CiColumns | List of output columns available in the .htx file. The format is a series of columns named by friendly names (see List of Property Names for a Web Catalog) and separated by commas. Up to 50 output columns can be referred to in a single query. Properties cannot be duplicated. Different friendly names for the same property are considered duplicates. Columns can be displayed only if the property value is available either in an ActiveX property set, in the property cache, or as a basic file property. HTML meta properties are available only if they have been added to the property cache.
CiDeferNonIndexedTrimming Some trimming of query results may be performed on individual objects after using the index to locate potential matches. Common post-processing includes trimming to match scope, and security. When a query sorted in descending order by rank is run, the full set of objects is examined to locate the CiMaxRecordsInResultSet top records. Because the top records cannot include items that fail post-index trimming, many thousands of items may have to be examined and thrown out to find the top results of a particular query, which can be very resource-intensive. Setting CiDeferNonIndexedTrimming to TRUE will first find the CiMaxRecordsInResultSet top records in the entire index, and then trim only that set. When this variable is set to TRUE, the number of results returned to the user may be less than CiMaxRecordsInResultSet, even if that many records match the query. The missing results will always be of lower rank than those returned. Although fewer results may be returned than expected, the best results will always be returned.

This flag should be set only when the scope of a query is set to the virtual root (CiScope = /) and there is a reasonable expectation that queries are pure content queries (no property-value clause) and most results are accessible to the user. On a public Web site, this will be a common scenario.
CiDialect | Defines the query-language dialect used for processing queries.
CiFlags | Query flags specifying the depth of search. DEEP means the directory given in CiScope and all directories below it, SHALLOW means only the directory specified in CiScope.
CiForceUseCi | If TRUE, query will be forced to use the content index, even if the content index is out of date.
CiLocale | Defines the locale used to issue the query. Standard HTML locale encoding is supported.
CiMaxRecordsInResultSet | Maximum number of query results to return from a query. This value represents the best n hits, not just a random set of n hits as in Index Server 1.0 and 2.0.
CiMaxRecordsPerPage | Maximum number of records to display on a page.
CiRestriction | Query restriction, a description of what to search for. To display this on a page, or to use this in a URL with a query expression, see Syntax in HTML Extension Files.
CiScope | Scope, the starting directory (or directories) for the search as either a virtual or physical path name. Separate multiple scopes with a comma (,). The scope / (forward slash) will match every page in all virtual directories and the scope \ (backslash) will match every page on every physical path. To incorporate CiScope into a URL with a query expression, see Syntax in HTML Extension Files.
CiSort | Sort specification. The format is a series of columns named by friendly names (see List of Property Names for a Web Catalog) and followed by either [a] for ascending order (optional) or [d] for descending order. The primary sort column is listed first, for example, CiSort=Rank[d], FileName[a]. Setting this variable may force the search to use a nonsequential query.
CiTemplate | Output template (.htx) file path name (as a virtual path name). This path name must be a complete path name from the virtual root with no "." or ".." components.


String Variables Useful for Formatting Displayed Columns

The variables in the following table, like those in the table in Variables in Forms and in .Idq Files, can be set in the .idq file. They cannot be referred to in the .htx file and can format only those columns whose type is vector or safe array.

Variable Name | Meaning
CiBoolVectorPrefix | String printed prior to vectors of Boolean values.
CiBoolVectorSeparator | String printed between elements of vectors of Boolean values.
CiBoolVectorSuffix | String printed after vectors of Boolean values.
CiCurrencyVectorPrefix | String printed prior to vectors of currency values.
CiCurrencyVectorSeparator | String printed between elements of vectors of currency values.
CiCurrencyVectorSuffix | String printed after vectors of currency values.
CiDateVectorPrefix | String printed prior to vectors of dates.
CiDateVectorSeparator | String printed between elements of vectors of dates.
CiDateVectorSuffix | String printed after vectors of dates.
CiNumberVectorPrefix | String printed prior to vectors of numbers.
CiNumberVectorSeparator | String printed between elements of vectors of numbers.
CiNumberVectorSuffix | String printed after vectors of numbers.
CiStringVectorPrefix | String printed prior to vectors of strings.
CiStringVectorSeparator | String printed between elements of vectors of strings.
CiStringVectorSuffix | String printed after vectors of strings.


Parameter for Use with Bookmarks

The CiBookmarkSkipCount variable (described in the following table) is used in conjunction with CiBookmark to set an offset from the previous page of the query. It cannot be set in the .idq file; it should be set as a form variable. See HTML Extension Files for examples.

The following variable can be set as a CGI variable, for navigating between pages:

Variable Name | Meaning
CiBookmarkSkipCount | Signed number of rows to skip for the next page. Negative means "skip backward," positive means "skip forward."


Standard Common Gateway Interface Variables Available

The variables below are normally set by Common Gateway Interface (CGI) program execution and can be referred to in the .idq or .htx files.

HTTP Variable | Meaning
ALL_HTTP All HTTP headers that were not already parsed into one of the listed variables. These variables are of the form HTTP_header field name with each variable separated by \r\n; for example:
HTTP_ACCEPT: */*, q=0.300, audio/x-aiff, audio/basic, image/jpeg, image/gif, text/plain, text/html HTTP_USER_AGENT: Microsoft Internet Explorer/0.1 (Win32) HTTP_REFERER: http://webserver/samples/dbsamp/dbsamp3.htm HTTP_CONTENT_TYPE: application/x-www-form-urlenPRE: 10 HTTP_EXTENSION: Security/Digest
AUTH_TYPE | The type of authorization in use. If the user name has been authenticated by the server, this will contain Basic. Otherwise, it will not be present.
CONTENT_LENGTH | The number of bytes that the script can expect to receive from the client.
CONTENT_TYPE | The content type of the information supplied in the body of a POST request.
GATEWAY_INTERFACE | The revision of the Common Gateway Interface (CGI) specification with which this server complies. The current version is 1.1.
HTTP_ACCEPT | Special-case HTTP header. Values of the Accept: fields are concatenated, separated by ","; for example, if the following lines are part of the HTTP header: accept: */*; q=0.1 accept: text/html accept: image/jpeg then the HTTP_ACCEPT variable will have a value of: */*; q=0.1, text/html, image/jpeg.
PATH_INFO | Additional path information, as given by the client. This comprises the trailing part of the URL after the script name but before the query string (if any).
PATH_TRANSLATED | This is the value of PATH_INFO, but with any virtual path name expanded into a directory specification.
QUERY_STRING | The information which follows the question mark (?) in the URL that referenced this script.
REMOTE_ADDR | The IP address of the client.
REMOTE_HOST | The host name of the client.
REMOTE_USER | This contains the user name supplied by the client and authenticated by the server.
REQUEST_METHOD | The HTTP request method.
SCRIPT_NAME | The name of the script program that is being run.
SERVER_NAME | The server's host name (or IP address) as it should appear in self-referencing URLs.
SERVER_PORT | The TCP/IP port on which the request was received.
SERVER_PROTOCOL | The name and version of the information-retrieval protocol relating to this request, usually HTTP 1.0.
SERVER_SOFTWARE | The name and version of the Web server under which the Internet Server Extension is running.


Valid Locale Identifiers

The following table shows the International Organization of Standards (ISO) language identifiers recognized by Indexing Service in CiLocale:

Language | CiLocale String | Win32 Equivalent
Afrikaans | AF | LANG_AFRIKAANS | SUBLANG_DEFAULT
Arabic | AR | LANG_ARABIC | SUBLANG_DEFAULT
Basque | EU | LANG_BASQUE | SUBLANG_DEFAULT
Belarusian | BE | LANG_BELARUSIAN | SUBLANG_DEFAULT
Bulgarian | BG | LANG_BULGARIAN | SUBLANG_DEFAULT
Catalan | CA | LANG_CATALAN | SUBLANG_DEFAULT
Chinese (China) | ZH, ZH-CN | LANG_CHINESE | SUBLANG_CHINESE_SIMPLIFIED
Chinese (Taiwan) | ZH-TW | LANG_CHINESE | SUBLANG_CHINESE_TRADITIONAL
Croatian | HR | LANG_CROATIAN | SUBLANG_DEFAULT
Czech | CS | LANG_CZECH | SUBLANG_DEFAULT
Danish | DA | LANG_DANISH | SUBLANG_DEFAULT
Dutch | NL | LANG_DUTCH | SUBLANG_DUTCH
English (United Kingdom) | EN-GB | LANG_ENGLISH | SUBLANG_ENGLISH_UK
English (United States) | EN, EN-US | LANG_ENGLISH | SUBLANG_ENGLISH_US
Estonian | ET | LANG_ESTONIAN | SUBLANG_DEFAULT
Faeroese | FO | LANG_FAEROESE | SUBLANG_DEFAULT
Finnish | FI | LANG_FINNISH | SUBLANG_DEFAULT
French | FR, FR-FR | LANG_FRENCH | SUBLANG_FRENCH
French (Canadian) | FR-CA | LANG_FRENCH | SUBLANG_FRENCH_CANADIAN
German | DE | LANG_GERMAN | SUBLANG_GERMAN
Greek | EL | LANG_GREEK | SUBLANG_DEFAULT
Hebrew | HE, IW | LANG_HEBREW | SUBLANG_DEFAULT
Hungarian | HU | LANG_HUNGARIAN | SUBLANG_DEFAULT
Icelandic | IS | LANG_ICELANDIC | SUBLANG_DEFAULT
Indonesian | ID, IN | LANG_INDONESIAN | SUBLANG_DEFAULT
Italian | IT | LANG_ITALIAN | SUBLANG_ITALIAN
Japanese | JA | LANG_JAPANESE | SUBLANG_DEFAULT
Korean | KO | LANG_KOREAN | SUBLANG_DEFAULT
Latvian | LV | LANG_LATVIAN | SUBLANG_DEFAULT
Lithuanian | LT | LANG_LITHUANIAN | SUBLANG_DEFAULT
Neutral (use built-in word breaking) | NEUTRAL | LANG_NEUTRAL | SUBLANG_NEUTRAL
Norwegian | NO | LANG_NORWEGIAN | SUBLANG_DEFAULT
Polish | PL | LANG_POLISH | SUBLANG_DEFAULT
Portuguese | PT | LANG_PORTUGUESE | SUBLANG_DEFAULT
Portuguese (Brazilian) | PT-BR | LANG_PORTUGUESE | SUBLANG_PORTUGUESE_BRAZILIAN
Romanian | RO | LANG_ROMANIAN | SUBLANG_DEFAULT
Russian | RU | LANG_RUSSIAN | SUBLANG_DEFAULT
Serbian | SR | LANG_SERBIAN | SUBLANG_DEFAULT
Slovak | SK | LANG_SLOVAK | SUBLANG_DEFAULT
Slovenian | SL | LANG_SLOVENIAN | SUBLANG_DEFAULT
Spanish | ES, ES-ES | LANG_SPANISH | SUBLANG_SPANISH
Swedish | SV | LANG_SWEDISH | SUBLANG_DEFAULT
Thai | TH | LANG_THAI | SUBLANG_DEFAULT
Turkish | TR | LANG_TURKISH | SUBLANG_DEFAULT
Ukrainian | UK | LANG_UKRAINIAN | SUBLANG_DEFAULT
Vietnamese | VI | LANG_VIETNAMESE | SUBLANG_DEFAULT

CiLocale can be specified in the .idq or .ida file. It can also be specified by the browser as the HTTP_ACCEPT_LANGUAGE variable. Values entered in the .idq and .ida files supersede those sent in HTTP_ACCEPT_LANGUAGE. If no value is found in the .idq or .ida file, the value of HTTP_ACCEPT_LANGUAGE is read from left to right to find a supported language.

For example:

HTTP_ACCEPT_LANGUAGE=EN, FR, CZ

Note Values are separated by commas.


Recognized Character Set Tags

This section lists the International Organization for Standards (ISO) codes currently recognized by Indexing Service and the HTML filter. Use these codes in the CiCodepage tag in a form variable to override a system's default code page.

Charset | Win32 Codepage | Comment
us-ascii | 1252 |
iso8859-1 | 1252 |
ascii | 1252 |
iso_8859-1 | 1252 |
iso-8859-1 | 1252 |
ANSI_X3.4-1968 | 1252 |
iso-ir-6 | 1252 |
ANSI_X3.4-1986 | 1252 |
ISO_646.irv:1991 | 1252 |
ISO646-US | 1252 |
us | 1252 |
IBM367 | 1252 |
cp367 | 1252 |
csASCII | 1252 |
latin1 | 1252 |
iso_8859-1:1987 | 1252 |
iso-ir-100 | 1252 |
ibm819 | 1252 |
cp819 | 1252 |
Windows-1252 | 1252 |
iso8859-2 | 28592 |
iso-8859-2 | 28592 |
iso_8859-2 | 28592 |
latin2 | 28592 |
iso_8859-2:1987 | 28592 |
iso-ir-101 | 28592 |
l2 | 28592 |
csISOLatin2 | 28592 |
windows-1250 | 1250 |
x-cp1250 | 1250 |
windows-1251 | 1251 |
x-cp1251 | 1251 |
windows-1253 | 1253 |
windows-1254 | 1254 |
shift_jis | 932 |
shift-jis | 932 |
x-sjis | 932 |
ms_Kanji | 932 |
csShiftJIS | 932 |
Extended_UNIX_Code_Packed_Format_for_Japanese | CODE_JPN_EUC | Converted to CP 932
csEUCPkdFmtJapanese | CODE_JPN_EUC | Converted to CP 932
x-euc-jp | CODE_JPN_EUC | Converted to CP 932
x-euc | CODE_JPN_EUC | Converted to CP 932
csISO2022JP | CODE_JPN_JIS | Converted to CP 932
iso-2022-jp | CODE_JPN_JIS | Converted to CP 932
windows-1257 | 1257 |
big5 | 950 |
csbig5 | 950 |
x-x-big5 | 950 |
GB_2312-80 | 936 |
iso-ir-58 | 936 |
chinese | 936 |
csISO58GB231280 | 936 |
csGB2312 | 936 |
gb2312 | 936 |
csKOI8R | 20866 |
koi8-r | 20866 |
ks_c_5601 | 949 |
ksc_5601 | 949 |
ks_c_5601-1987 | 949 |
korean | 949 |
csKSC56011987 | 949 |
euc-kr | 949 |
csEUCKR | 949 |
ISO-2022-KR | 949 |
csISO2022KR | 949 |
ISO_8859-8:1988 | 1255 |
iso-ir-138 | 1255 |
ISO_8859-8 | 1255 |
ISO-8859-8 | 1255 |
hebrew | 1255 |
csISOLatinHebrew | 1255 |
Windows-1256 | 1256 |
Windows-874 | 874 |
Windows-1258 | 1258 |


Variables within Query Strings

Within a query string that is set by an end user or set programmatically, Indexing Service recognizes certain syntaxes that it converts back and forth from IXSSO Query object properties in the server-side scripting to conventional URL tags for the HTML client. See the following section, QUERY_STRING Variables, for more information.


QUERY_STRING Variables

The following table defines the conventional URL tags in the QUERY_STRING variable used by the SetQueryFromURL and QueryToURL methods defined on the IXSSO Query object.

Tag | Description
ae | Used by the AllowEnumeration property. If set to a nonzero digit, enumeration is allowed.
ct | Used by the Catalog property.
di | Used by the Dialect property.
gd | GroupBy descending. Used by the GroupBy property.
gr | Used by the GroupBy property.
mh | Used by the MaxRecords property.
qu | Full text of query. Used by the Query property.
so | Used by the SortBy property.
sd | Sort descending. Used by the SortBy property.


Tags for Creating Built-up Query Strings

The following tags create built-up query strings for the Query property on an IXSSO Query object. In each, n is a single digit in the range 0-9. The column, operator, and query for each numeric value make up a query term which is combined with the full-text query string and other query terms using the AND operator.

Tag | Description
cn | Column for a built-up query. Used by the Query property.
on | Operator for a built-up query. Used by the Query property.
qn | Query string for a built-up query. Used by the Query property.


Server Variables

The following example shows how the QUERY_STRING or form variables can be parsed from VBScript without the SetQueryFromURL method.

<%
    NewQuery = FALSE
    UseSavedQuery = FALSE
    SearchString = ""
    if Request.ServerVariables("REQUEST_METHOD") = "POST" then
        SearchString = Request.Form("SearchString")
        SortBy = Request.Form("SortBy")
        Colset = Request.Form("ColChoice")
        Catalog = Request.Form("Catalog")
        ' NOTE: this will be true only if the button is actually pushed.
        if Request.Form("Action") = "New Query" then
            NewQuery = TRUE
        end if
    end if
    if Request.ServerVariables("REQUEST_METHOD") = "GET" then
        SearchString = Request.QueryString("qu")
        SortBy = Request.QueryString("so")
        Colset = Request.QueryString("co")
        Catalog = Request.QueryString("ct")
        if Request.QueryString("pg") <> "" then
            NextPageNumber = Request.QueryString("pg")
            NewQuery = FALSE
            UseSavedQuery = TRUE
        else
            NewQuery = SearchString <> ""
        end if
    end if
 %>


Creating Administration Forms

New with Indexing Service 3.0 are the administration scripting objects that allow you to programmatically manage Indexing Service through the CatAdmin catalog administration object methods and properties.

Legacy administration can still be accomplished through the ISAPI custom Internet Data Administration (.ida) files.

Manual administration is supplied through the MMC snap-in for Indexing Service. Programmatic administration is available through the Indexing Service Administration Automation Objects.

This section contains the following topic:

  • Writing Internet Data Administration Scripts


Writing Internet Data Administration Scripts

Administrative requests are very similar to queries, except that the parameters are stored in an Internet Data Administration (.ida) file instead of an Internet Data Query (.idq) file. You can write your own IDA scripts with the following parameters:

Parameter | Description | Optional
CiCatalog | Specifies location of catalog. If not found, default specified in registry is used. | Yes
CiTemplate | Specifies template to use if administration operation is successful. Standard .idq error semantics apply. | No
CiLocale | Defines the locale used to issue the query. Indexing Service supports standard HTML locale encoding. | Yes

You can also add user-defined variables in the same manner as .idq files.

Note Some administrative operations can change the state of the index. Administrative operations are restricted based on an access control list (ACL).

Note Do not put .ida files on a virtual root pointing to a remote Uniform Naming Convention (UNC) share.


Highlighting Search Hits

When you query a document with Indexing Service, the hit-highlighting feature shows the exact portions (if any) of the document that satisfy your query. The hit-highlighting feature generates an HTML page containing a list of the hits, with those words making up the hit emphasized (by default, displayed in red and italics). Each hit is displayed together with some of the text that surrounds it in the document. Also, for each document in which a hit is found, Indexing Service gives you a link to the full text of that document.

This section contains:

  • Webhits.dll: Describes the difference between the new Webhits.dll and the previous Webhits.exe.
  • Hit-Highlighting Syntax: Tells how to start the hit-highlighting application.
  • Webhits Parameters Provides parameters to help you fine-tune a query with Webhits.
  • Formatting Considerations: Gives details about the placement of Webhits parameters.
  • Adding a Hit-Highlighting Link to a Results Page: Tells how to modify Query.htx file to add a link to Webhits in an existing page.
  • Hit-Highlighting Examples: Shows an example of how to set up hit-highlighting in queries and gives examples of acceptable path names.
  • Hit-Highlighting of SQL Content Search Results Describes how you can use hit-highlighting with SQL content search results.

This section does not contain information on:

  • Hit-highlighting errors; see Hit-Highlighting Errors.


Webhits.dll

With the release of Index Server 2.0, the Common Gateway Interface (CGI) application Webhits.exe has become the Internet Server API (ISAPI) application Webhits.dll. If you have any .htx files that incorporate hit-highlighting, you will need to modify them. If you create new .htx files that incorporate hit-highlighting, you need to follow the new syntax shown on this page. You should notice no other differences.

Example

The example in the following section, Index Server 1.1 and Earlier Versions, shows how syntax for hit-highlighting was written in previous versions of Indexing Service and contrasts it to the syntax for version 2.0. The differing sections of code are highlighted in bold.


Index Server 1.1 and Earlier Versions

The following example shows how syntax for hit-highlighting was written for Index Server 1.1 and earlier.

<a href="http://<%server_name%>/scripts/srchadm/webhits.exe<%escapeURL
vpath%>?CiRestriction=<%escapeURL
CiRestriction%>&CiTemplateFile=/scripts/srchadm/hquery.htw&CiQueryFile=/scripts/srchadm/hquery.idq&
CiBeginHilite=<%escapeURL <font color="#FF0000"><em>%>&CiEndHilite=<%escapeURL
</em></font>%>&CiUserParam3=<%EscapeURL
CiBookMark%>&CiUserParam4=<%EscapeURL DocTitle%>">Show Highlights</a>


Index Server 2.0

The following example shows how syntax for hit-highlighting was written for Index Server version 2.0.

<a href="http://<%server_name%>/vpath/template.htw?CiWebHitsFile=<%escapeURL
vpath%>&CiRestriction=<%escapeURL
CiRestriction%>&CiQueryFile=/scripts/srchadm/hquery.idq&
CiBeginHilite=<%escapeURL <font color="#FF0000"><em>%>&CiEndHilite=<%escapeURL
</em></font>%>&CiUserParam3=<%EscapeURL
CiBookMark%>&CiUserParam4=<%EscapeURL DocTitle%>">Show Highlights</a>


Hit-Highlighting Syntax

The hit highlighter (Webhits.dll) is an Internet Server API (ISAPI) application that you invoke from your browser by referring to an .htw template file.

If you want the minimum formatting to appear in your results set, choose the default formatting in Webhits.dll. To choose the default formatting, specify Null.htw as the template file. This file need not exist.

Sample template files for Webhits output formatting are included in the installed samples as:

/Iissamples/Issamples/Oop/Qfullhit.htw

/Iissamples/Issamples/Oop/Qsumrhit.htw


Webhits Parameters

This section lists and describes the parameters that can help you fine-tune a query with the hit-highlighter (Webhits.dll).

  • CiBeginHilite, CiEndHilite
  • CiBold
  • CiCodepage
  • CiHiliteColor
  • CiHiliteType
  • CiItalic
  • CiLocale
  • CiMaxLineLength
  • CiQueryFile
  • CiRestriction
  • CiUserParamNumber
  • CiWebhitsFile


CiBeginHilite, CiEndHilite

Format: CiBeginHilite=BeginTags & CiEndHilite=EndTags

Customizes highlighted words in the query results. If you specify these tags, Indexing Service ignores all other formatting parameters — CiBold, CiHiliteColor, CiItalic, and so on.

Important You must match the BeginTags and EndTags with correct HTML formatting. Failure to do so will produce unpredictable results. When you specify these parameters in the query template file (.htx file), you must properly escape the tags. For example:

CiBeginHilite=<%escapeURL <font color="#FF0000"><em>%>&CiEndHilite=<%escapeURL </em></font> %>

The two parameters together in the above example make the highlighted words in the search results appear in red italics.


CiBold

Format: CiBold=value, where value can be any non-null string.

Specifies that the highlighted text be displayed in bold. Any non-null value will turn bold on. This parameter is optional.


CiCodepage

Format: CiCodepage=charset

Determines the character set in which hit-highlighting results are displayed. This parameter is optional.


CiHiliteColor

Format1: CiHiliteColor=24-bit color mask

The mask takes the form 0xHHHHHH, where each H is a hexadecimal digit.

Format2: CiHiliteColor=color

where color is the name of any color {red, green, blue, yellow, black}. This parameter is optional. It specifies the color used to highlight the text matching the restriction. If it is not specified, or if the format used does not match either of the above, Webhits defaults to red.


CiHiliteType

Format: CiHiliteType=[Full|Summary]

This parameter is optional. If not specified, Summary is the default value.

Summary
When this parameter is set to Summary it generates small excerpts of a document around the words that match the query specification.
Full
When this parameter is set to Full it generates the full text of a document, highlighting the words that match the query. Mainly for documents that contain mostly text, this option does not do full-fidelity highlighting. Only the text part of the document is extracted and highlighted. In addition, this option tags the highlighted text (hits) with bookmarks, allowing navigation between the hits. The first hit is bookmarked as #CiTag0 and the top of the generated document is tagged as #CiTag-1. To help navigate, double-angle bracket tags (<< and >>) surround each hit. Click the << tag to go to the previous hit, and click the >> tag to go to the next hit.


CiItalic

Format: CiItalic=value, where value can be any non-null string.

Specifies that the highlighted text be displayed in italics. Any non-null value will turn italics on. This parameter is optional.


CiLocale

Format: CiLocale =LocaleString

Specifies the locale to interpret the CiRestriction string. The output will also be generated by this locale. Valid values for the CiLocale string are in Valid Locale Identifiers. This parameter is optional.


CiMaxLineLength

Format: CiMaxLineLength=Number

Pre-formats the text with the <pre> and </pre> HTML tags. If a line length exceeds the specified number, it is broken at the next word boundary. This option works best when full hit-highlighting is chosen. This parameter is optional.


CiQueryFile

Format: CiQueryFile=Virtual path

Specifies the virtual path of the .idq file containing the [Names] section describing the custom properties. You must pass this parameter for all queries involving custom properties. If you try to hit-highlight a document with a query that has a custom property and do not specify the appropriate .idq file, the error message "No such property" will be displayed. This parameter is optional.


CiRestriction

Format: CiRestriction=Query

Specifies the query for doing hit-highlighting. The query string must be in escaped form, which means that spaces and other special characters have been converted to their respective ASCII codes. In an .htx file, the restriction can be escaped by using the EscapeURL keyword, as demonstrated in Adding a Hit Highlighting Link to a Results Page. This parameter is required.


CiUserParamNumber

Format: CiUserParamNumber=value, where value can be any non-null string.

Specifies any parameter available for Webhits, where Number is any number from 1 to 10. For example, CiUserParam 1, CiUserParam 3, CiUserParam 5, and so on.


CiWebhitsFile

Format: CiWebhitsFile=virtual_path

Specifies the virtual path of the document to be hit highlighted. This parameter is required.

Note The Secure Sockets Layer (SSL) setting for the Webhits template (.htw file) and the setting for CiWebhitsFile must be the same, or else the CiWebhitsFile must have a setting of 0. If this is not the case, Webhits will fail with an appropriate error message.

If your site requires all documents to be accessed only with SSL, be sure to set the same SSL access on the .htw file. If your site has some documents with SSL access required and others with no SSL access required, set the SSL access on the .htw file to be the same as those that require SSL access. Alternatively, you can create two .htw files (one for each type of document).


Formatting Considerations

You can specify the Webhits parameters in any order, and you can include white space in any of the following places:

  • After the question mark (?) and before the name of the Webhits parameter.
  • Between the name of the Webhits parameter and the equal sign (=).
  • Between the equal sign and the escaped value of the Webhits parameter.
  • After the escaped value of the Webhits parameter and the ampersand (&) (if more than one Webhits parameter is passed).


Adding a Hit-Highlighting Link to a Results Page

The hit-highlighter (Webhits.dll) comes with a ready-made results page (Query.htx). This results page includes a link to Webhits for each document returned. To add a link to an existing page, modify the .htx file by inserting the following line where you want the link to appear:

<a href="http://<%server_name%<execute-permission vpath/Null.htw>?CiWebhitsFile=<%escapeURL vpath%>&
CiRestriction=<%escapeURL CiRestriction%>"><b>Highlight Hits</b></a><BR>

Here, server_name is a variable storing the name of the server on which the Web server is located, and CiRestriction is the variable storing the query. You escape the restriction through the EscapeURL keyword, as shown in the sample query.


Hit-Highlighting Examples

This topic contains examples of how to set up a query to take advantage of hit-highlighting and some sample files and path names.

  • Sample Query
  • Sample Files


Sample Query

Suppose, when putting together the information in the previous sections, that you want to search for the author of a document greater than 100 bytes in size, and the author's name is George. To do this, send the following query:

@DocAuthor = George AND @size > 100

You want to aim your query at this document:

/InetPub/Docs/Ideas.doc

To choose default formatting, refer to a virtual directory with Execute or Script permission:

/Path/null.htw?

Before the query string can be passed to Webhits, it must be escaped, resulting in:

@DocAuthor%20%3D%20George%20AND%20@size%20%3E%20100

Now, to hit-highlight the document, issue the following command:

http://MyServer/Path/Null.htw?CiWebhitsFile=\vpath\Docs\Ideas.doc &
CiRestriction=@DocAuthor%20%3D%20George%20AND%20@size%20%3E%20100

Note Neither @size nor @DocAuthor are custom properties, so you do not need to specify an .idq file in this case.


Sample Files

For examples of how to effectively use hit-highlighting, see the following files:

/Iissamples/Isamples/Query.htx

/Iissamples/Isamples/Query.idq

/Iissamples/Isamples/Oop/QSumrhit.htw

/Iissamples/Isamples/Oop/QFullhit.htw

/Iissamples/Isamples/Query.htm


Hit-Highlighting of SQL Content Search Results

Hit-highlighting is an Indexing Service feature that you can use when querying a document. Hit-highlighting generates an HTML page that contains a list of the hits showing the exact portions (if any) of the document that satisfy your query.

When using SQL to query for content, you can use the hit-highlighting feature by using ActiveX® Data Objects (ADO) to retrieve the Query Restriction property and using that property as the value for the CiRestriction parameter of Webhits.dll.

Note Hit-highlighting is available only for SQL content queries (CONTAINS predicate) and a vpath recordset field must be present in the Select_List statement. Get the Query Restriction property only after the command is executed.

The following example queries for documents containing the words "Index" and "Server" gets the Query Restriction property, and uses it to invoke the hit-highlighter (Webhits.dll):

<%
Set Conn = Server.CreateObject("ADODB.Connection")
Conn.ConnectionString =  "provider=msidxs;"
Conn.Open
Set AdoCommand = Server.CreateObject("ADODB.Command")
set AdoCommand.ActiveConnection = Conn
Set Recordset = Server.CreateObject("ADODB.RecordSet")
AdoCommand.Properties("Bookmarkable") = True
AdoCommand.CommandText = "select vpath, filename from scope() where contains('Index AND Server')>0"
Recordset.open AdoCommand
SearchString = AdoCommand.Properties("Query Restriction")
%>
<%if SearchString <> "" then%>
<BR>
  <%
  ' Construct the URL for hit highlighting
  WebHitsQuery = "CiWebHitsFile=" & Server.URLEncode( Recordset("vpath") )
  WebHitsQuery = WebHitsQuery & "&CiRestriction=" & Server.URLEncode( SearchString )
  WebHitsQuery = WebHitsQuery & "&CiBeginHilite=" & Server.URLEncode( "<font color=""#FF0000""><b><em>" )
  WebHitsQuery = WebHitsQuery & "&CiEndHilite=" & Server.URLEncode( "</em></b></font>" )
  WebHitsQuery = WebHitsQuery & "&CiUserParam3=" & QueryForm
  %>
  <a href="/iissamples/issamples/Oop/Qsumrhit.htw?<%= WebHitsQuery %>"><b>Show Highlights (condensed)</b></a> /
  <a href="/iissamples/issamples/Oop/Qfullhit.htw?<%= WebHitsQuery %>&CiHiliteType=Full"><b>Show Highlights (full
text)</b></a>
<BR>
<%end if%>


Error Messages and Error Pages

Indexing Service errors fall into several classes: query syntax errors, .idq syntax errors, .htx syntax errors, out-of-resource errors, and other system errors. HTML pages and the Microsoft® Windows NT®/Windows® 2000 event log also report Indexing Service errors. The only errors a user is likely to see are query-syntax errors, and even these can be minimized by using HTML forms.

This topic contains:

  • Hit-Highlighting Errors: Explains errors due to incorrect hit-highlighting syntax.
  • HTML Error Pages: Explains the three classes of errors that generate an HTML error page.
  • .Htx File Errors: Explains messages for .htx files for .idq processing only.
  • .Idq File Errors: Describes the messages that can be returned because of errors in .idq files.
  • Event Log Messages: Explains the meaning of messages recorded in the WindowsNT/Windows 2000 event log.
  • Query Syntax Errors: Lists and explains the errors that can be returned when executing a query through any method.
  • IXSSO Errors: Lists error messages that are generated by Active Server Pages (ASP).


Hit-Highlighting Errors

The following messages are generated by errors in hit-highlighting syntax in .htw files.

Message | Explanation
A <%BeginDetail%> section was found in the template file, without a matching <%EndDetail%> section. | In the .htw file, every <%BeginDetail%> must be followed by a matching <%EndDetail%> tag.
An <%EndDetail%> section was found in the template file before a <%BeginDetail%> section. | In the .htw file, a <%BeginDetail%> tag must precede an <%EndDetail%> tag.
An <%EndDetail%> section was found in the template file, without a matching <%BeginDetail%> section. | In the .htw file, an <%EndDetail%> tag must be preceded by a <%BeginDetail%> tag.
CONTENT_LENGTH is non-positive. | This message indicates a browser error or IIS error. Please try again with Microsoft Internet Explorer.
The file is too large to hit highlight. | The maximum size file that can be hit-highlighted is a little larger than 1 megabyte (MB).
The format of QUERY_STRING is invalid. The specification of Webhits parameters in QUERY_STRING does not conform to the format:
[ws][Name of Parameter][ws][=][ws][escaped value of parameter][ws][&]

where this is repeated for each command-line parameter, and [ws] (whitespace) is optional.
Hit-highlighting took too long to execute and was timed out. | Webhits has taken longer than the allotted time to process a document, and the server has timed out. The document may be too big or it may be corrupted. Ask the administrator to check the document. If you get this message, increase the setting for the MaxWebhitsCpuTime parameter in the registry.
The Internet Data Query (.idq) file specified cannot be found. | Check the path to the .idq file and make sure the file is in that path.
An invalid variable name was found in QUERY_STRING. | While parsing QUERY_STRING, Webhits.dll encountered a parameter whose name it did not recognize.
No such property. | The query involves a custom property, but does not specify an .idq file with a [Names] section describing this property, or the property name was not found in the [Names] section of the specified .idq file.
A parameter to Webhits.dll was specified more than once. | Check the Webhits parameters in the file where it is invoked, in the .htx file, for example.
The path specified is incorrect. | Webhits.dll failed to get one of the CGI variables PATH_TRANSLATED or PATH_INFO.
The query issued is invalid. | Webhits.dll failed to get the CGI variable QUERY_STRING, or CiRestriction is not specified in QUERY_STRING.
REQUEST_METHOD is neither a GET nor POST CGI variable. | This message indicates a browser error or IIS error. Please try again with Internet Explorer.
The template file specified in CiTemplate cannot be found. | Check the path to the .htw file and make sure the file is in that path.
There are too many copies of hit-highlighter running. Please try later. | There are more simultaneous instances of Webhits than the maximum number set in the MaxRunningWebhits registry key. Try executing your query later when the server is less busy.


HTML Error Pages

The first three classes of error (query syntax referring to .idq files only, .idq syntax, and .htx syntax) always generate an HTML error page. The page returned for each class of error is specified in the Language-Specific Registry Settings. Registry keys are under the following path:

HKEY_LOCAL_MACHINE\SYSTEM
 \SYSTEM
  \CurrentControlSet
   \Control
    \ContentIndex
     \Language
      \<language>

The keys are:

ISAPIHTXErrorFile, ISAPIIDQErrorFile, and ISAPIRestrictionErrorFile
Configures .htx errors, .idq (and .ida) errors, and query syntax errors.
ISAPIDefaultErrorFile
Reports other errors.

These pages are standard, completely customizable .htx pages. The variable CiErrorMessage contains a localized string describing the specific error, and CiErrorNumber contains the error code.


.Htx File Errors

These messages are for Internet Data Query (.idq) processing only and are returned by the CiErrorMessage variable, accessible from HTML extension file (.htx) error pages.

Message | Explanation
A <%BeginDetail%> section was found on line <number> in the .htx file <file>, without a matching <%EndDetail%> section. | The <%BeginDetail%> tag must be followed by a matching <%EndDetail%> tag.
An <%else%> or <%endif%> was found without a matching <%if...%>. | An <%else%> or <%endif%> tag was found without a matching <%if %> tag.
An <%EndDetail%> section was found on line <number> in the .htx file <file> before the <%BeginDetail%> section. | The <%BeginDetail%> tag must precede the <%EndDetail%> tag.
An <%EndDetail%> section was found on line <number> in the .htx file <file>, without a matching <%BeginDetail%> section. | The <%EndDetail%> tag must be preceded by a matching <%BeginDetail%> tag.
An <%if%> was found without a matching <%else%> or <%endif%>. | The <%if...%> tag must be followed by an <%endif%> tag, with an optional <%else%> tag in between.
Constants used in IsTypeEq-operator conditions must be unsigned integers, not floats, globally unique identifiers (GUIDs), and so on. | One or more of the constants in the IsTypeEq condition is a float, GUID, and so on, but should be an unsigned integer.
Expecting an operator in <%if%> statement. | The operator in an <%if...%> tag was missing. 'If' must be followed by one of EQ, NE, LT, LE, GT, GE, contains, or IsTypeEq HTX operators.
The .htx file <file> contains an ill-formed include statement on line <number>. | Usually caused by a <%include...%> tag without the closing %>.
The .htx file <file> uses too many includes on line <number>. | A maximum of 32 files can be included by use of the <%include...%> tag.
The .htx file specified could not be found in any virtual or physical path. | The .htx file specified in an <%include...%> tag could not be located.
The include file name is invalid in file <file> on line <number>. | Usually caused by a <%include...%> tag missing the closing %>.
One of the values in a IsTypeEq condition must be a variable. You used two constants. | One of the values in the IsTypeEq condition must be a variable.
An opening bracket "{" was found without a matching closing bracket. | A vector in an <%if...%> tag is missing the closing brace.
An opening quotation mark (") was found without a matching closing quotation mark ("). | A quoted phrase in an <%if...%> tag is missing the closing quote.


.Idq File Errors

These messages are returned by use of the CiErrorMessage variable, accessible from .htx error pages.

Message | Explanation
The catalog directory cannot be found in the location specified by 'CiCatalog=' in file <file>. | The catalog location specified by the CiCatalog parameter did not contain a valid content index catalog.
DBTYPE_BYREF must be used with DBTYPE_STR, DBTYPE_WSTR, DBTYPE_GUID or DBTYPE_UI1 types. | DBTYPE_BYREF must always be used in conjunction with an indirect type in the [Names] section.
DBTYPE_VECTOR or DBTYPE_BYREF used alone. | The VECTOR and BYREF property modifiers must always be used with a type. Example: DBTYPE_I4 | DBTYPE_VECTOR
Duplicate column, possibly by a column alias, found in the 'CiColumns=' specification in file <file>. | The same property was named more than once in the CiColumns variable line. It may have been mentioned with different friendly names that refer to the same property.
Duplicate property name. | The same property was defined twice in the [Names] section.
Expecting closing parenthesis. | Opening parenthesis in [Names] section is not followed by closing parenthesis in .idq file.
Expecting GUID. | Incorrectly formatted entry in the [Names] section of .idq file.
Expecting integer. | Incorrectly formatted entry in the [Names] section of .idq file.
Expecting property name. | Incorrectly formatted entry in the [Names] section of .idq file.
Expecting property specifier. | Invalid or missing property specifier in [Names] section. Property is named either by PROPID (integer) or string.
Expecting SHALLOW or DEEP in .idq file <file> on line 'CiFlags='. | The CiFlags parameter has a value other than a value of SHALLOW or DEEP.
Expecting TRUE or FALSE in .idq file <file> on line 'CiForceUseCi=' | The CiForceUseCi parameter has a value other than TRUE or FALSE.
Expecting type specifier. | Incorrectly formatted entry in the [Names] section of .idq file.
Failed to set property name. | A resource failure. Usually out of memory.
The file <file> is on a network share. The .idq, .ida, and .htx files cannot be placed on a network share. | You must put these files into a virtual root on the local computer.
The .htx file specified could not be found in any virtual or physical path. | The file specified in the CiTemplate parameter could not be located.
The .idq file <file> contains a duplicate entry on line <line>. | A parameter in the [query] section of the .idq file was given more than once.
The .idq file <file> could not be found. | Check the path to the .idq file and then make sure the .idq file is in that path.
An invalid 'CiScope=' or 'CiCatalog=' was specified in file <file>. | The .idq file cannot contain invalid parameters. Correct the condition and try again.
Invalid GUID. | A poorly formatted GUID was found in the [Names] section.
An invalid locale identifier (LCID) was specified on the 'CiLocale=' line in .idq file <file>. | The LCID specified by the CiLocale parameter was not recognized as valid.
Invalid property found in the 'CiColumns=' specification in file <file>. | A property specified in the CiColumns parameter is not a standard property and is not listed in the [Names] section of the .idq file.
Invalid property found in the 'CiSort=' specification in file <file>. | A property specified in the CiSort parameter is not a standard property and is not listed in the [Names] section of the .idq file.
An invalid sort order was specified on the 'CiSort=' line in file <file>. Only [a] and [d] are supported. | A sort-order specification following a property name in the CiSort parameter was unrecognized. Only [a] (for ascending) and [d] (for descending) are allowed.
One or more output columns must be specified in the .idq file <file>. | The CiColumns parameter is missing or empty. At least one output column must be specified for the query.
Operation on line number of .ida file <file>. is invalid. | An unrecognized keyword was found in the .ida file.
The query failed because the Web server is busy processing other requests. | The limit on the number of queries has been exceeded. To allow more queries to wait in the queue for processing, increase the value of the registry key IsapiRequestQueueSize, and to allow more queries to be processed simultaneously, increase the value for the registry key IsapiRequestThresholdFactor.
Read error in file <file>. | Input/output (I/O) error occurred reading the file. Generally caused by hardware failure.
A restriction must be specified in the .idq file <file>. | The CiRestriction parameter is missing or empty. Every query must have a restriction. A restriction such as #vpath *.* will match all pages.
A scope must be specified in the .idq file <file>. | The CiScope parameter is missing or empty. Every query must have a scope. The scope / (forward slash) will match every page in all virtual directories and the scope \ (backslash) will match every page on every physical path.
The template file cannot be found in the location specified by 'CiTemplate=' in file <file> | An attempt to open a .htx file at the location specified by the CiTemplate parameter failed. The path may be invalid, it may specify a directory, or it may resolve to NULL after parameter replacement.
A template file must be specified in the .idq file <file>. | The CiTemplate parameter is missing or empty. Every query must have a template (.htx) file.
Template for IDA file <file> cannot have detail section. | A <%BeginDetail%> was found in the .ida file. Please remove it and the entire detail section.
Unrecognized type. | Type specified is not one of the valid types (DBTYPE_I4, DBTYPE_GUID, and so on).
You must specify 'MaxRecordsPerPage' in the .idq file <file>. | The CiMaxRecordsPerPage parameter is missing or empty. Every query must specify the number of records per page.


Event Log Messages

Indexing Service system errors are reported in the application event log under the CiFilter service category. System errors reported here include page filtering (indexing) problems, out-of-resource conditions, index corruption, and so on. See also Virtual Roots Errors.

The following messages are written to the Windows NT/Windows 2000 application event log.

Message | Explanation
Account user ID does not have interactive logon privilege on this computer. You can give user ID interactive logon privilege on this computer using the user manager administrative tool. | The specified user ID does not have interactive logon privilege on the computer running Indexing Service. Give the user ID interactive logon privilege through the User Manager for Domains.
The Indexing Service filter daemon has prematurely stopped and will be and subsequently restarted. | The filter daemon (CiDaemon.exe) stopped unexpectedly. It will be automatically restarted. This can be caused by poorly written filters, or experimentation with the Task Manager.
CI has started on <catalog>. | An informational message logged when Indexing Service is started successfully.
Class for extension <extension> unknown. Sample file: <file> | This is a warning that files with the specified extension are being filtered with the default (text) filter. This can lead to the addition of unnecessary data in the index. Consider turning off filtering for this extension. The full physical path of a representative file is included in the message. Generation of this message can be disabled by turning on a special flag in ContentIndex registry key. See the FilterFilesWithUnknownExtensions registry entry for details.
Cleaning up corrupted content index metadata on <catalog>. Index will be automatically restored by refiltering all documents. | A catastrophic data corruption error was detected on the specified catalog. The catalog will be rebuilt. This is usually caused by hardware failure, but can also occur in rare circumstances because of abrupt shutdown or power failure. Recovery will occur automatically.
Content index on <catalog> could not be initialized. Error <number>. | Unknown, possibly catastrophic error. Please report the error number to Microsoft Technical Support. To recover, delete all files under <catalog> and re-index.
Content index on <catalog> is corrupted. Please shut down and restart Web server. | A catastrophic data corruption error was detected on the specified catalog. The catalog will be rebuilt. This is usually caused by hardware failure, but can also occur in rare circumstances because of abrupt shutdown or power failure. You must shut down and restart the Web server for recovery to occur.
Content index corruption detected in component <component>. Stack trace is <stack>. | The content index is corrupted. Delete the catalog and start over. If you keep getting this error, remove and reinstall Indexing Service.
Content index corruption detected in component <component> in catalog <catalog>. Stack trace is <stack>. | The content index is corrupt. Delete the catalog and start over. If you keep getting this error, remove and reinstall Indexing Service.
The content index could not filter file <file>. The filter operation was retried <number> times without success. | The specified document failed to successfully filter <number> times. This usually indicates a corrupted document or corrupted properties. In rare cases, filtering may fail because the document was in use for a long period of time.
Content index on drive is corrupted. Please shutdown and restart the Content Index service (cisvc). | In the system Control Panel under Services, stop the Content Index service, and then restart it.
The content index filter for file "<file>" generated content data more than <size> times the file's size. | Filtering of the specified document generated more than the allowed maximum amount of output. This is usually caused by a poorly written filter, a corrupted document, or both.
The content index filter stopped while filtering "<file>". The CI filter daemon was restarted. Please check the validity of the filter for objects of this class. | Filtering of the specified document was started, but did not finish before the time-out period expired. This is usually caused by a poorly written filter, a corrupted document, or both.
A content scan has completed on <catalog>. | A content scan of the catalog has been completed successfully.
An error has been detected on <catalog> that requires a full content scan. | The catalog lost a change notification, usually due to lack of resources (disk space) or hardware failure. The complete scope of the catalog will be scanned, and all documents will be refiltered. This action is deferred until a suitable time.
An error has been detected in content index on <catalog>. | The content index is corrupt. Delete the catalog and start over. If you keep getting this error, remove and reinstall Indexing Service.
An error has been detected on <catalog> that requires a partial content scan. | The catalog lost a change notification, usually due to lack of resources (disk space) or hardware failure. A partial scope of the catalog will be scanned, and some documents will be refiltered. This action is deferred until a suitable time.
Error <number> detected in content index on <catalog>. | Unknown, possibly catastrophic error. Please report error number to Microsoft Technical Support. To recover, delete all files under <catalog> and start over.
File change notifications are turned off for scope "<scope>" because of error <number>. This scope will be periodically rescanned. | An error prevented reestablishing automatic change notifications for the specified directory scope. To determine documents that changed in the scope, periodic incremental scans will be done by Indexing Service. The rescan interval is specified in the registry.
File change notifications for scope "<scope>" are not enabled because of error <number>. This scope will be periodically rescanned. | An error prevented establishment of automatic change notifications for the specified directory scope. This usually happens with virtual roots that point to remote shares on file servers that do not support automatic change notifications. To determine which documents changed in the scope, periodic incremental scans will be done by Indexing Service. The rescan interval is specified in the registry.
The filter service could not run since file <file> could not be found on your system. | An executable or DLL required for filtering cannot be found, usually because CiDaemon.exe is not on the path.
A full content scan has started on <catalog>. | A complete rescan of the catalog has been initiated.
<number> inconsistencies were detected in the PropertyStore cache of property values during recovery of catalog <catalog>. | Corruption was detected in the property cache during startup. Recovery is automatically scheduled. Usually the result of hardware failure or abrupt shutdown.
Master merge cannot be restarted on <catalog> due to error <number>. | A master merge cannot be restarted on the specified catalog. The error code gives the reason.
Master merge cannot be started on <catalog> due to error <number>. | A master merge cannot be started on the specified catalog. The error code gives the reason.
Master merge has been paused on <catalog>. It will be rescheduled later. | A master merge has been temporarily halted on the specified catalog. Often occurs when a merge runs out of system resources (disk space, memory, and so on).
Master merge has completed on <catalog>. | A master merge has been completed on the specified catalog. This is an informational message.
Master merge has restarted on <catalog>. | A paused master merge has been restarted.
Master merge has started on <catalog>. | A master merge has been initiated on the specified catalog. This is an informational message.
Master merge was started on <catalog> because the amount of remaining disk space was less than <number>%. | A master merge was started because the amount of free space on the catalog volume dropped below a minimum threshold. The total free disk space should be increased after the master merge completes.
Master merge was started on <catalog> because more than <number> documents have changed since the last master merge. | A master merge was started because the number of documents changed since the last master merge exceeded the maximum threshold.
Master merge was started on <catalog> because the size of the shadow indexes is more than <number>% the disk. | A master merge was started because the amount of data in shadow indexes exceeded the maximum threshold.
Notifications are not enabled on <pathname> because this is a distributed file system (DFS)-aware share. This scope will be periodically scanned. | If a virtual root points to a DFS share, notifications are disabled for the entire DFS share because DFS does not support notifications.
One or more embeddings in file <file> could not be filtered. | The specified file was filtered correctly, but several of the embedded objects could not be filtered. This is usually caused by embedded objects without a registered filter. Text within unfiltered embedded objects is not searchable. Generation of this message can be disabled by turning on a special flag in key registry. See Registry Entries for details.
The path <pathname> is too long for Content Index. | The Indexing Service detected a path that was longer than the maximum number of characters allowed for a pathname as determined by the constant MAX_PATH (260 characters). As a result, no documents from that path will be returned or indexed.
Please check your system time. It might be set to an invalid value. | This event is generated when the system time is invalid, for example, when set to a date before January 1, 1980. When the system time is invalid, the date may appear as 2096.
<Process-Name> failed to logon <UserId> because of error <number>. | The specified process (Indexing Service SearchEngine or CI filter daemon) failed to log on the specified user because of an error. The remote shares for which the user ID is used will not be filtered correctly. This can happen if either the password is wrong or the validity of the password could not be verified due to network problems.
PropertyStore inconsistency detected in catalog <catalog>. | Corruption was detected in the property store cache of property values. Recovery is automatically scheduled. Usually the result of hardware failure or abrupt shutdown.
Recovery is starting on PropertyStore in catalog <catalog>. | Corruption was detected in the property cache. Recovery is starting on the property cache. Depending upon the size of the property cache, this can take a long time, .
Recovery was performed successfully on PropertyStore in catalog <catalog>. | Corruption was detected in the property cache. The error has been fixed. Usually the result of hardware failure or abrupt shutdown.
Very low disk space was detected on drive <drive>. Please free up at least <number> megabytes (MB) of space for content index to continue. | Free space has fallen below the minimum threshold required for successful merge. This is just a warning, but no merges will be initiated until space is freed. Filtering will also stop.


Virtual Roots Errors

The following error messages can be returned when problems occur involving virtual roots on the server.

Message | Explanation
Added virtual root <root> to index. | The message "Mapped to <path>" is added to the event log when a virtual root is indexed.
Removed virtual root <root> from index. | This message is written to the event log when a virtual root is deleted from the index.
Added scope <path> to index. | This message is added to the event log when a physical scope is indexed.
Removed scope <path> from index. | This message is written to the event log when a new physical scope is deleted from the index.


Query Syntax Errors

The following error messages can be returned when executing a query.

Message | Explanation
Expecting closing parenthesis ')'. | Occurs when parentheses are mismatched.
Expecting closing square bracket ']'. | An opening square bracket was not followed by a closing square bracket. Usually the result of an ill-formed weight.
Expecting comma. | Occurs when a reserved token or end-of-string occurs before the closing brace of a vector property. Example: @VectorString = {A1, B@}.
Expecting currency. | A currency value was expected but not found. Occurs when a property of type DBTYPE_CY is fed incorrect input. Correct format for currency is #.#.
Expecting date. | A date was expected but not found. Occurs when a property of type DBTYPE_DATE is fed incorrect input. Allowed formats for dates are yyyy/mm/dd, yyyy/mm/dd hh:mm:ss, and relative dates (-#y, -#m, -#w, -#d, -#h, -#n, -#s).
Expecting end of string. | A complete restriction has been parsed, and there is still more input. Example: (@size = 100) sample.
Expecting GUID. | A GUID was expected but not found. Occurs when a property of DBTYPE_GUID is fed incorrect input. Property format for a GUID is XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
Expecting integer. | An integer was expected but not found. Occurs when a property of an integer type (DBTYPE_I4, and so on) is fed a non-numeric value, or a non-numeric vector weight is entered.
Expecting phrase. | A textual phrase was expected and not found. This error occurs in a variety of situations where the query parser is expecting plain text and is given a special token instead.
Expecting property name. | Occurs when a correctly formed property name is not found after an @ sign.
Expecting real number. | A real number was expected but not found. Occurs when a property of a real type (DBTYPE_R4, and so on) is fed a non-numeric value.
Expecting regular expression. | Similar to Expecting phrase error. Used when in regular-expression parsing mode.
The file <file> is on a remote UNC share. .Idq, .ida, and .htx files cannot be placed on a remote UNC share. | An .idq, .ida, or .htx file was found on a remote UNC share. None of these files can be on a remote UNC share.
Invalid literal. | Occurs only when a query property is formatted poorly. Almost all conditions are covered by the Expecting integer, Expecting date, and other errors.
No such property. | Property specified after @, #, or $ does not exist. It is not a default property and is not specified in the Names section of the .idq file.
Not yet implemented. | An unimplemented feature of Indexing Service.
Out of memory. | The server ran out of memory processing the CiRestriction parameter.
Regular expressions require a property of type string. | A property of a nontextual type (DBTYPE_I4, DBTYPE_GUID, and so on) was selected for regular-expression mode. For example, #size 100* will cause this error.
Unexpected end of string. | There is a missing quotation mark in your query.
Unsupported property type. | For future expansion. Will occur when a display-only property type is used in a query restriction.
Weight must be between 0 and 1000. | Occurs when a query term weight is outside the legal range of 0 to 1000.


IXSSO Errors

The IXSSO component normally produces a page containing errors encountered when executing Active Server Pages (.asp) queries. This page can point you to the problem that caused the error by using the Microsoft Visual Basic® Scripting Editing (VBScript) OnError statement and the standard VBScript Err object.

The following error messages are generated by the IXSSO component:

Message | Explanation
The catalog directory cannot be found in the location specified by the Catalog property. | The catalog location specified by the Catalog property did not contain a valid Content Index catalog.
The CiFlags property had improper syntax. Expecting 'Shallow' or 'Deep'. | The depth of the AddScopeToQuery method has a value other than SHALLOW or DEEP.
Expecting comma. | A reserved token or end-of-string occurred before the closing brace of a vector property. Example: @VectorString = {A1, B@}.
Duplicate column, possibly by a column alias, found in the Columns property. | The same column was named more than once in the CiColumns variable line. It may have been mentioned with different friendly names that refer to the same column.
Invalid column name found in the Columns property. | A value specified in the Columns property is not a standard property and was not defined by the DefineColumn method.
An invalid locale identifier (LCID) was specified for the LocaleID property or the browser's Accept-Language header. | The LCID specified by the LocaleID property was not recognized as a valid locale ID.
No output columns were set. | The Columns property is empty. At least one output column must be specified for the query.
The property cannot be set while a query is active. | You cannot change the value of a property while a query is being executed. Use the Reset method to reset the state of the query object before you set the property.
The Query property was not set. | The Query property is missing or empty. Every query must have a restriction. A restriction such as #vpath *.* will match all pages.
A reserved tag was used in a query string. | In the SetQueryFromURL method, a parameter name was given that is reserved for future use.
A query is not being executed. | A query-status property was referenced when there was no active query.

See Also

Query Syntax Errors, .Idq File Errors


Web Server Samples

The Web server samples illustrate dynamic HTML (DHTML) and Active Server Pages (ASP) scripting. The DHTML sample is written in HTML and includes client-side scripting. The ASP samples are written in HTML and include both client-side and server-side scripting. Both types of samples use the Admin Helper API or the Query Helper API. The Platform SDK includes the following samples.

  • DHTML Sample. An example of a DHTML client-side query.
  • IISAdmin Sample. A set of HTML and ASP pages that manages Indexing Service using Internet Information Services (IIS).
  • IISSearch Sample. A set of HTML and ASP pages that executes Indexing Service query language and structured query language (SQL) queries.


DHTML Sample

The DHTML sample (CiDHtml.htm) uses Microsoft® Visual Basic® Scripting Edition (VBScript) to create a client-side query form that queries an Indexing Service catalog. The sample uses the Query Helper API for the query and an ActiveX® Data Objects (ADO) Recordset object to return the results.

Path

Source: mssdk\samples\winbase\indexing\DHtml\

User's Guide

To run the sample

  1. Load CiDHtml.htm into any DHTML-capable browser.
  2. Enter the query text in the first text box using Indexing Service Query Language Dialect 2.
  3. Click Go to run the query.

Programming Notes

CiDHtml.htm uses DHTML to build a client-side query form that can search an Indexing Service catalog. The sample uses the Query object of the Query Helper API and the ADO Recordset object. The sample uses VBScript to program the objects. Data entry uses an HTML form, and the query results are formatted using DHTML.


IISAdmin Sample

The IISAdmin sample is a set of HTML and ASP forms that demonstrates how to use IIS to administer Indexing Service. The forms retrieve indexing statistics, force a master merge, rescan paths, and check for documents that could not be filtered.

Path

Source: mssdk\samples\winbase\indexing\IISAdmin\

User's Guide

To install the sample files

  1. Open a command window and change the directory to the source path of the sample.
  2. At the command-line prompt, type "install".

The sample files are copied to the directory %windir%\system32\inetsrv\iisadmin\isadmin.

To use the sample forms

  1. Start Microsoft Internet Explorer.
  2. Enter the URL "http://localhost/iisadmin/isadmin/admin.htm".
  3. In the left frame, select the desired administration operation.

Programming Notes

The forms in the IISAdmin sample require that IIS be running.

The main sample form is admin.htm, which controls all the administrative operations.


IISSearch Sample

The IISSearch sample is a set of HTML and ASP forms that demonstrates how to use IIS to query Indexing Service. The forms use Indexing Service Query Language queries and the Query Helper API, use SQL queries and the ADO and Query Helper APIs, and use IDQ+HTX and the ISAPI Extensions API.

Path

Source: mssdk\samples\winbase\indexing\IISSearch\

User's Guide

To install the sample files

  1. Open a command window and change the directory to the source path of the sample.
  2. Determine where your Inetpub directory resides.
    • If it resides on %SystemDrive%, you can use the install.bat file without modifying it.
    • If it resides on another drive, modify the dst environment variable in the install.bat file to define the location of your inetpub directory.
  3. At the command prompt, type "install".

The sample files are copied to the directory specified by the dst environment variable, which specifies by default the directory %SystemDrive%\Inetpub\IISSamples\ISSamples.

To use using the sample forms

  1. Start Internet Explorer.
  2. Type the URL "http://localhost/iissamples/issamples/default.htm".
  3. In the left frame, select the sample query to execute.

Programming Notes

The sample files include the following.

advquery.asp
An advanced Active Server Pages (ASP) example written in VBScript and Microsoft JScript® that illustrates server-side scripting to execute Indexing Service Query Language queries using the Query Helper API.
advsqlq.asp
An advanced ASP example written in VBScript and JScript that illustrates server-side scripting to execute SQL queries using the ADO and Query Helper APIs.
default.htm
An HTML page that provides easy access to each sample.
fastq.htm, fastq.idq, fastq.htx
An optimized IDQ+HTX example that uses the ISAPI Extensions API.
query.asp
A simple ASP example written in VBScript and JScript that illustrates server-side scripting to execute Indexing Service Query Language queries using the Query Helper API.
query.htm, query.idq, query.htx
A simple IDQ+HTX example that uses the ISAPI Extensions API.
sqlqhit.asp, sqlqhit.htm
A simple ASP example written in VBScript that illustrates the execution of queries using the OLE DB Provider for Indexing Service API.


Using Custom Filters with Indexing Service

Indexing Service for Microsoft® Windows® 2000 uses filters to extract content and properties of files for inclusion in a searchable index. Microsoft provides file-format specific filters for several types of files, including Microsoft Office documents and HTML files.

This section describes the use of the IFilter interface to produce custom filters for other specific file formats. It contains the following sections:

  • About Filters describes how the Indexing Service filter extracts text and properties from a file.
  • Applying Filters describes how the Indexing Service filtering process determines which filters to use for particular files.
  • Constructing Filters describes the construction of several sample filters.
  • Testing Filters describes how to use the IFilter Test Suite to test filters.
  • Filter Samples presents details about the sample filters in the Platform Software Developer's Kit (SDK).

For an overview of how the IFilter interface regards documents and their properties, see Properties of Documents. In particular, for a synopsis and example of how the IFilter interface processes a document, see Property Filtering.


About Filters

An Indexing Service filter implements the IFilter interface for a specific type of file. The filter extracts text and properties from documents for placement in the Indexing Service index. Once this content is in the index, you can query the index to find occurrences of the requested content in the filtered files.

An Indexing Service filter, also known as a content filter, is a dynamic-link library (DLL) that includes an implementation of the IFilter interface for a specific class of files. An Indexing Service filter understands a file format and can extract the text from the content of the file and properties from either the content or associated properties of the file. To filter new file formats, you simply create and install a new filter implementation.

Filters register themselves for a particular file class. For example, an HTML filter can process the class of "htmlfile" files, which include .htm and .html files. For information about filter registration, see Finding the Filter DLL for a File.

Content filters also handle embedded or linked objects by having the parent object call the IFilter interface methods of the embedded or linked objects. These objects should have their own IFilter implementations, supplied by the system or the programmer, which follow the standard COM containment rules. IFilter::Init accepts a flag to control whether filtering follows links to other objects.

You use a filter for the following two purposes:

  • Filtering Text and Properties. A filter performs a full-text search and can also determine properties for a file. A full-text search extracts only the text information from a file, without formatting or graphics information, so that the text can be indexed.
  • Viewing and Hit-Highlighting. A filter provides information for viewing and hit-highlighting. Hit-highlighting enables a text viewer to display the query hits and provides the navigation between hits so you can see exactly where query results occur.


Filtering Text and Properties

Indexing Service uses the IFilter interface to scan documents for text and property information. This section includes the following topics:

  • Filtering Information Chunks. Chunks are the fundamental units of information that can be either contents or properties of an object.
  • Filtering File Contents. A filter extracts chunks of text from the contents of a file to index them.
  • Filtering File Properties. A filter extracts chunks of text from a file's properties to index them.
  • Filtering Well-Known Properties. A filter can extract a consistent set of well-known properties for all files.

Several samples of IFilter interface implementations can be found in subdirectories of the mssdk\samples\winbase\indexing directory of the Platform SDK. To install the samples, see Installing the Samples. For more information about the samples, see Filter Samples.


Filtering Information Chunks

Chunks are the fundamental logical units of text processed by clients of filters. Chunks share the same properties and the same locale, so word breaking and noise-word removal from the text can be tailored to the appropriate native language. Two pieces of text that cannot share the same properties and the same locale must be in different chunks. Chunks may overlap, but a specific property is applied to a given character only once. Following are three examples of chunks.

  • You can represent a simple text file in one chunk of text.
  • With an HTML file, you need to represent each tag as a single chunk of text so that the tag <TITLE> for instance, can be mapped to a known property such as DocTitle.
  • Chunks in other types of files can include separate text boxes in a graphics file, labels and titles on charts, and possibly text in separate cells of a spreadsheet.

The CiDaemon.exe process of Indexing Service filters objects by making successive calls to the IFilter::GetChunk method to get a STAT_CHUNK structure that describes the chunks. All chunks of text use the Unicode representation, so single- and multibyte-characters are converted to Unicode when necessary.

In order for the appropriate word breaker to process the chunks, the file must have language-attribute information accessible to the filter. For example, Microsoft Word documents can tag text with a language tag using the Tools/Language menu. This information is stored with the text and is then available for the Word filter to process it accordingly.

The filter gives each chunk a unique, ULONG identifier (ID) greater than zero. These identifiers are guaranteed to remain constant until the IFilter interface is released. Calling an IFilter method on an object with the same parameters for the IFilter::Init method produces the same set of chunks. If, however, you change the Init method parameters for repeated calls to the IFilter interface, you may get a different set of chunks. Most significantly, changing the set of properties requested from an object by changing the attribute array in the IFilter::Init method may re-partition the chunks of an object.

Calls to the IFilter::GetChunk method do not reveal the original source of the chunk (that is, whether it was embedded, linked, or in a top-level container).


Filtering File Contents

The CiDaemon.exe process of Indexing Service filters a file by successively calling the IFilter::GetChunk method to retrieve one of two kinds of content: text-type properties or value-type properties. The IFilter::GetText method retrieves text from the first category, and the IFilter::GetValue method retrieves values from the second category. For more information about retrieving property values, see Filtering File Properties. Text chunks can have a locale attribute that indicates the type of word-breaker to use, based on the language in which the chunk is written. The resulting word list is normalized (converted to uppercase and given other minor conversions for comparison purposes) and then stored in a word list in memory. Word lists eventually merge into the master index.

When filtering a file, you generally want to filter any linked and embedded objects that you want associated with the top-level object. An HTML link, for example, may not reflect the contents of the outer document and so should not be filtered with the parent object. However, it may be quite suitable to include an embedded Excel chart when filtering the parent object, a Word document, for example. For filtering purposes, logical containment is more important than physical containment. If you want to be able to search for information, filter it.

Logical containment results when you have either of the following.

  • Embedded Objects
  • Linked Objects


Embedded Objects

The parent container of an object is responsible for binding to the IFilter interface of a child object and managing the chunk IDs to keep them unique. Nested chunks appear to the original caller as chunks of the outer object. There is no operating-system support provided for this operation. IFilter interface implementations are responsible for binding to the IFilter interface of embedded objects. If the current chunk is within an embedded object, all calls to the IFilter::GetText and IFilter::GetValue methods should be passed directly to the IFilter interface of the embedded object, and the return values from the embedding should be returned to the client. Other calls require some additional work. The IFilter::GetChunk method, for example, may require that chunk IDs be renumbered to make them unique.


Linked Objects

An object can also be asked to enumerate the chunks of text "contained" in its linked objects. As with embedded objects, IFilter interface implementations are responsible for binding to the IFilter interface of linked objects, and then renumbering the chunks of the linked objects so that they appear to the original caller as chunks of the outer object. The same rules that apply to an embedding's chunks apply to a link's chunks. Use IFILTER_INIT_SEARCH_LINKS to control whether to search links.

The original source of a chunk (embedding, link, or top-level object) is not exposed by the IFilter interface. If the embedded or linked object cannot be filtered because it does not have a registered IFilter interface, the parent container should handle the situation gracefully by returning the error FILTER_E_EMBEDDING_UNAVAILABLE and proceed to the next chunk.


Filtering File Properties

The CiDaemon.exe process of Indexing Service filters file properties by calling the IFilter::GetChunk and IFilter::GetValue methods. Each chunk can have only one property. If the chunk is not ordinary text, it can originate from one of the following kinds of information:

  • Properties accessed through the Microsoft ActiveX® IPropertyStorage and IPropertySetStorage interfaces. For example, the properties you see displayed when you right-click on a Microsoft Office file in a Web browser, or using Microsoft Windows Explorer, are properties from the Office Summary Information property set. The IFILTER_FLAGS_OLE_PROPERTIES flag tells the filter that ActiveX properties exist and should not be returned through the filter.
  • Properties accessed as internal value-type properties from files that treat some internal fields as value-type properties. For example, fields within a spreadsheet can be tagged with property set and property ID values to make them available for later searching. The IFILTER_INIT_APPLY_INDEX_ATTRIBUTES flag indicates that the client wants textual content retrieved as the values they are defined to represent. Examples of internal value-type properties are HTML tags like <TITLE> (which gets mapped into the "DocTitle" Office property set and property ID) and HTML anchor tags.

You can use the Microsoft Management Console (MMC) snap-in of Indexing Service to specify cached properties for the second category (internal, value-type properties). If this has been done, calls to the IFilter::GetValue method produce properties that are saved in the property store for the catalog that indexes these files. Certain well-known properties are cached for performance reasons. Cached properties can be displayed in query result tables and you can search for these properties using relational or regular expression queries (see Property-Value Queries for details).

You can also create file abstracts at this time if the IFilter interface implementation supports creation of such a summary. (See Creating Abstracts for more information). You can adjust the property cache through the MMC by right-clicking MyComputer and choosing Manage, then Server Applications. Then select Services and Indexing Service on Local Machine. The globally unique identifier (GUID) for the property set is in the first column and the property ID, either a number or string, is in the second column. Right-click on the guide to display the property menu and set the Cache check box to cache the property.

An example showing how to expose additional HTML <META> tag properties, how to make these properties available for comparisons, and how to show them in the search results table can be found in the HTMLProp sample in the code samples directory under IFilter.


Filtering Well-Known Properties

Microsoft encourages all IFilter interface implementers to adopt sets of well-known properties so that client applications can use one query to search for these properties on all file classes that have IFilter interface support. Clients calling IFilter interface implementations can request a set of properties they would like to see during the IFilter::Init method call.

Properties have unique identifiers made up of the globally unique identifier (GUID) of a property set, followed by a property ID. The property ID can be a unique number within the property set for properties with type PRSPEC_PROPID or a unique string corresponding to the name of the property for properties of type PRSPEC_LPWSTR. The following list describes the well-known properties used by Indexing Service.

Property Name | Property Set GUID/ Property ID or Name | Description
Text | B725F130-47EF-101A-A5F1-02608C9EEBAC 19 | From storage properties of a file
Description | D1B5D3F0-C0B3-11CF-9A92-00A0C908DBF1 "DESCRIPTION" | From HTML Filter; can be used to generate Abstract
Title | F29F85E0-4FF9-1068-AB91-08002B27B3D9 2 | From Microsoft Office Summary Information property set
Subject | F29F85E0-4FF9-1068-AB91-08002B27B3D9 3 | From Office Summary Information property set
Author | F29F85E0-4FF9-1068-AB91-08002B27B3D9 4 | From Office Summary Information property set
Keywords | F29F85E0-4FF9-1068-AB91-08002B27B3D9 5 | From Office Summary Information property set
Comments | F29F85E0-4FF9-1068-AB91-08002B27B3D9 6 | From Office Summary Information property set


Viewing and Hit-Highlighting

When a document shows in a results list as having a match to a query string, you may naturally want to view that document and see where the hits are. The document viewer then calls the IFilter methods to filter the document, process the results to be an index, and search that in-memory index for query hits. The viewer can then highlight and navigate from hit to hit. This process is known as hit-highlighting.

For an example of hit-highlighting implemented with Indexing Service and Internet Information Services (IIS), see Highlighting Search Hits.


Applying Filters

Clients call IFilter interface implementations to extract text and properties from an object. Although clients of the IFilter interface may use the interface in any way they wish, it was designed to meet the specific needs of full-text search engines. The search engine of Indexing Service breaks the results of the IFilter::GetText method into words, normalizes them, and saves them in an index. If available, the search engine uses the locale identifier (LCID) of a text chunk to perform language-specific word breaking and normalization.

This section includes the following topics.

  • Filter DLLs. A list of the dynamic-link libraries (DLLs) supplied by Indexing Service and the way you associate them to file types.
  • Controlling Filtering. A list of ways you can control the filtering process for Indexing Service.


Filter DLLs

Filter DLLs allow a client to extract text information from the persistent representation of the contents and properties of a file. The Indexing Service filtering process CiDaemon.exe binds to the persistent handler for the IFilter interface implementation for the COM class of a file or for its registered file extension. For details about how this occurs, see Persistent Handlers.

Every time it starts, Indexing Service registers DLLs, including persistent handlers, if they are listed in the registry key HKLM\system\currentcontrolset\control\contentindex\DllsToRegister.

To remove a filter DLL, delete the PersistentHandler registry entry associated with a document type and the filter DLL registry entry. (See Finding the Filter DLL for a File for more information). Once you have found the correct PersistentHandler entry, you can unregister it with the following syntax:

Regsvr32.exe /u filter.dll

This section contains topics that describe how to use the filter DLLs:

  • Indexing Service Implementations of IFilter. A summary of the filter DLLs supplied with Indexing Service.
  • Persistent Handlers. A brief description of how you bind to an IFilter implementation to call its methods and properties.
  • Finding the Filter DLL for a File. A description of how to find the filter DLL for a specific file type.


Indexing Service Implementations of IFilter

Microsoft supplies several standard filters with Indexing Service. The following table lists the filter names, what they filter, and the DLL name. Selecting the name of a filter takes you to a description of the filter.

Filter Name | Files Filtered | Filter DLL
MIME Filter | Multipurpose Internet Mail Extensions (MIME) | mimefilt.dll
HTML Filter | HTML 3.0 or earlier | nlhtml.dll
Microsoft Office Document Filter | Microsoft Word, Excel, PowerPoint® | offfilt.dll
Default or Plain Text Filter | Plain text files - Default Filter | query.dll
Binary or Null Filter | Binary files - Null Filter | query.dll


MIME Filter

The MIME implementation for the IFilter interface (in mimefilt.dll) extracts text and property information from multipurpose Internet mail extension files with the extensions .eml and .nws. IIS includes a Network News Transfer Protocol (NNTP) server that saves files with the .nws extension. This filter enables indexing and querying NNTP messages with Indexing Service.


HTML Filter

The HTML implementation for the IFilter interface (in nlhtml.dll) extracts text and property information from the class "htmlfiles" so that it can be indexed by Indexing Service. Indexing Service calls the methods on this IFilter interface implementation when indexing HTML files. For a description of the association between filter and file type, see Finding the Filter DLL for a File.

You can use the <META> tag feature of HTML documents to convey special handling requests to the HTML filter. <META> tags occur near the beginning of an html file within the <HEAD> ... </HEAD> tags, as shown in the following example.

<head>
<META NAME="DESCRIPTION" CONTENT="This text will appear on the results page as the document's summary.">
</head>

Some HTML META tags are automatically mapped to well-known property set and property ID values so that queries on these properties will search the mapped contents. Examples include the following.

Property example | Mapped to
<meta name="author" content="ruth"> | The author property in the Summary Information property set.
<meta name="subject" content="word processing"> | The subject property in the Summary Information property set.
<meta name="keywords" content="fonts, serif"> | The keyword property in the Summary Information property set.
<meta name="ms.category" content="fiction"> | The category property in the document Summary Information property set.

Here are some other special features of the HTML filter:

  • Creating special abstracts from files

    The filtering process can generate abstracts for each filtered file, which default to being a set of characters at the beginning of the file. As shown in the example at the beginning of this section, you can use the <META NAME="DESCRIPTION" ..> tag to instruct the filter to use the string following the CONTENT keyword as the document abstract.

  • Preventing individual files from being filtered

    Add the following meta tag to the file:

    <meta name="robots" content="noindex">

  • Setting the language code for a file to ensure the system chooses the correct language word breakers and noise word files

    Add the following meta tag to the file, where the content field specifies the appropriate language code (in characters or using the locale value):

    <meta name="ms.locale" content="EN"> or

    <meta name="ms.locale" content=1033>

You can also define new new property names to filter. For additional information, see Defining New Property Names for a Web Catalog.


Microsoft Office Document Filter

This IFilter implementation (in offilt.dll) filters files for the documents in Microsoft Office, including the documents for Word, Excel, and PowerPoint. These include files with the extensions .doc, .mdb, .ppt, and .xlt.


Default or Plain Text Filter

For plain-text files and files of unregistered origin, Indexing Service uses the default filter (in query.dll). It filters both the system properties (such as file names) and the contents of a file. The default filter does not "understand" any document formats; when filtering the contents of a file, it treats the file as a sequence of characters. (It does check for the Unicode byte-order mark at the beginning of the file.) Indexing Service uses the default filter when the file-name extension of a file has no association in the registry, and if the value of the FilterFilesWithUnknownExtensions registry entry is one.


Binary or Null Filter

When a registered binary file is encountered, the null filter (in query.dll) is used. The null filter retrieves only the system properties. The contents of a binary file are not filtered. Examples of system properties are FileName, LastWriteTime, FileSize, and Attributes.


Persistent Handlers

Indexing Service uses a special binding procedure to access IFilter interface implementations because the CiDaemon.exe process operates on the persistent image of an object and does not, as in the more common OLE case, bind to an in-memory image of an object. Using a persistent handler allows the CiDaemon.exe process to bind to only the IFilter interface for a file instead of being registered as the COM server for all clients that want to access the file.

Persistent handlers can be registered for a class identifier (CLSID) that represents a COM class and also for a file extension. Persistent handlers registered for a file extension take precedence over the persistent handler for a CLSID.

Indexing Service supplies helper functions that implement a subset of the COM persistent handler functionality. You can use these functions to access the IFilter interface implementations for embedded or linked objects.

A persistent handler provides the same service for the persistent image of an object that the OLE running object table provides for the loaded, in-memory image. The persistent handler is the broker between the persistent state of an object and clients wishing to access that state. It is responsible for coordinating multiple-client access to the persistent state of an object.

Multiple handlers can be defined to provide behavior for a single persistent object. Each interface can specify a unique handler for only that interface. Potentially, multiple handlers that are ignorant of each other can all operate on the persistent image of the same object. It is the responsibility of the persistent handler to load the correct implementation for each interface.

The following registry entries are sufficient to load the implementation of the IFilter interface for objects of type SampleObject. In addition, a persistent handler can be registered for a file extension that overrides the persistent handler registered for the class.

  • Persistent Handlers Registered for a Class
  • Persistent Handlers Registered for a File Extension


Persistent Handlers Registered for a Class

The following is an example of the registry entry for a persistent handler registered for a class.

\HKEY_LOCAL_MACHINE\SOFTWARE\Classes

    .sam
        = REG_SZ SampleFile

    SampleFile
        = REG_SZ Class for Sample Files
        CLSID
           = REG_SZ {40A45370-0386-11D0-AE19-00AA004B9986}
    CLSID
        {40A45370-0386-11D0-AE19-00AA004B9986}
           = REG_SZ Sample Files
           InprocServer32
              = REG_SZ sample.dll
           PersistentHandler
               = REG_SZ {A6317C60-0386-11D0-AE19-00AA004B9986}

        {A6317C60-0386-11D0-AE19-00AA004B9986}
           = REG_SZ Sample file persistent handler
           PersistentAddinsRegistered
              {89BCB740-6119-101A-BCB7-00DD010655AF}
                 = REG_SZ {D7455400-0386-11D0-AE19-00AA004B9986}

        {D7455400-0386-11D0-AE19-00AA004B9986}
           = REG_SZ Sample files
           InprocServer32
              = REG_SZ sampfilt.dll
              ThreadingModel = Apartment

Up through the entry for the class (CLSID\{40A45370-0386-11D0-AE19-00AA004B9986}), these entries are standard OLE registry entries. The DLL sample.dll implements running object behavior for the .sam class. But note the extra entry, PersistentHandler. This entry specifies the class responsible for brokering requests to the persistent objects of the sample class. The entry under PersistentAddinsRegistered identifies the implementation responsible for the interface named 89BCB740-6119-101A-BCB7-00DD010655AF (IID_IFilter). Finally, we come to the class implementing IID_IFilter and again, the entries are standard OLE registry entries. The InprocServer32 DLL is loaded through the standard OLE mechanism. Indexing Service observes the threading model specified for the filter. When the threading model is Both, the filter must be thread safe. If the filter is not thread safe, specify Apartment.


Persistent Handlers Registered for a File Extension

The following is an example of the registry entry for a persistent handler registered for a file extension.

\HKEY_CLASSES_ROOT\

    .sam
        = REG_SZ SampleFile

    SampleFile
        = REG_SZ Class for Sample Files
        CLSID
           = REG_SZ {40A45370-0386-11D0-AE19-00AA004B9986}
    CLSID
        {40A45370-0386-11D0-AE19-00AA004B9986}
           = REG_SZ Sample Files
           InprocServer32
              = REG_SZ sample.dll
           PersistentHandler
               = REG_SZ {A6317C60-0386-11D0-AE19-00AA004B9986}
...

The remaining content is as in the Persistent Handlers Registered for a Class example.


Finding the Filter DLL for a File

The following example, for HTML files, shows how to find the filter DLL for a document.

1. Determine the persistent handler registered for an extension. Check to see whether the extension for the type of files that the DLL filters has a persistent handler registered under the registry entry \HKEY_LOCAL_MACHINE\SOFTWARE\Classes. Let this be <Value1>.

\HKEY_LOCAL_MACHINE\SOFTWARE\Classes
    .htm
        PersistentHandler
            {EEC97550-47A9-11CF-B952-00AA0051FE20}

If this entry exists, skip to step 4 and use <Value1> there.

2. Alternatively, determine the CLSID. If there isn't a persistent handler registered for the extension, find the CLSID associated with the document type under the registry entry \HKEY_LOCAL_MACHINE\SOFTWARE\Classes. Let this be <Value2>.

\HKEY_LOCAL_MACHINE\SOFTWARE\Classes
    htmlfile
        = Class for WWW HTML files
        CLSID
            = {25336920-03F9-11CF-8FD0-00AA00686F13}

3. Determine the persistent handler. Using <Value2>determined in Step 2, find the PersistentHandler value for the \HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\<Value2> entry. Let this be <Value3>.

\HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
        {25336920-03F9-11CF-8FD0-00AA00686F13}
            = WWW HTML files
            PersistentHandler
                = {EEC97550-47A9-11CF-B952-00AA0051FE20}

4. Determine the IFilter persistent handler GUID. Using <Value1> determined in Step 1 or <Value3> determined in Step 3, find the IFilter Persistent Handler GUID for the document type. The value under the registry entry
\HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\<Value1 or 3>\PersistentAddinsRegistered\
89BCB740-6119-101A-BCB7-00DD010655AF yields the IFilter Persistent Handler GUID for this document type. Let this be <Value4>. 89BCB740-6119-101A-BCB7-00DD010655AF is the IFilter interface GUID.

\HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
        {EEC97550-47A9-11CF-B952-00AA0051FE20}
             = REG_SZ HTML File Persistent Handler
        PersistentAddinsRegistered
             {89BCB740-6119-101A-BCB7-00DD010655AF}
                 = REG_SZ {E0CA5340-4534-11CF-B952-00AA0051FE20}

5. Determine the filter DLL. Using <Value4> determined in Step 4, the filter DLL can be found under the entry
\HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\<Value4>\InprocServer32.

\HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID
     {E0CA5340-4534-11CF-B952-00AA0051FE20}
        = REG_SZ HTML Filter
        InprocServer32
            = REG_SZ nlhtml.dll

In this example, the filter DLL for HTML documents is nlhtml.dll.


Controlling Filtering

Indexing Service provides several ways to customize the behavior of filtering on your system. The following sections describe how to do so:

  • Filtering Directories. The properties of file directories are indexed.
  • Creating Abstracts. Document summary information is created during the filtering process.
  • Maximum Retries. The number of times Indexing Service tries to access an inaccessible file is determined.
  • Corrupted Files. Describes what occurs when Indexing Service tries to filter a corrupted file.
  • Unknown Extensions. Explains what Indexing Service does if there is no association between file extension and filter DLL.


Filtering Directories

By default, directories are not filtered and do not appear in query results. To filter directories, set the registry entry FilterDirectories to one. Filtering directories treats the system properties of the directories.


Creating Abstracts

The CiDaemon.exe process of Indexing Service can automatically generate a summary or abstract (also called a characterization) for each file. If the GenerateCharacterization registry entry is set to one, the abstract is generated. The maximum number of characters in the generated abstract is controlled by the MaxCharacterization registry entry.

If the abstract is set to be generated automatically, Indexing Service usually takes by default the first 320 characters of a document and copies that block of text for the summary. Alternatively, if a document has certain properties, such as DocTitle, they contribute more to the abstract than the first block of text in the file.

See HTML Filter for a description of how you can override this feature for the HTML class of documents. You can use this description as a basis to generate an abstract of any type of documents.


Maximum Retries

If a document cannot be filtered, it will be retried a certain maximum number of times. If the document then still cannot be filtered, it will be considered an unfiltered file. The registry key FilterRetries determines the maximum number of retries for a document.

Unfiltered documents can be found by defining the property

Unfiltered (DBTYPE_BOOL, 1) = 49691c90-7e17-101a-a91c-08002b2ecda97, and then issuing the query

@unfiltered = true.


Corrupted Files

If a file is corrupted, the filter may not be able to properly interpret the contents of that file. When this occurs, an event is written to the event log. Sometimes a file cannot be filtered because of a defective third-party filter. After verifying the contents of a file, an administrator should report problems to the filter vendor. Files protected by passwords are not filtered.


Unknown Extensions

A file with an extension that does not have an association in the registry is treated as an unknown extension. The behavior of Indexing Service depends upon the registry setting FilterFilesWithUnknownExtensions. If this value is set to zero, the null filter is used to filter those files. Otherwise, the default filter is used to filter the contents.


Constructing Filters

This section describes the construction of filters for Indexing Service. The following topics discuss the significant aspects of realizing the required dynamic-link library (DLL) structure for an IFilter interface implementation.

  • Describing the Filter Structure
  • Implementing and Exporting the DLL Entry Points
  • Implementing the Filter Class and Class Factory
  • Inheriting the COM Interfaces
  • Implementing the COM Interface Methods


Describing the Filter Structure

Each filter is a dynamic-link library (DLL) file that implements an in-process COM server to supply the specified filtering capabilities. The following figure shows the overall structure of a typical filter DLL. (A more complex example could implement more than one filter class.)


Implementing and Exporting the DLL Entry Points

Each filter DLL (denoted by filter.dll in this section) must implement and export the following entry points. These entry points are typically exported using a module-definition (.def) file for the filter or by using the __declspec(dllexport) keyword. The DLL file can be registered to be in any folder, but it usually resides in the %SystemRoot%\system32 folder.

DllRegisterServer
The DllRegisterServer entry point registers the DLL as a persistent handler in the registry. You register the DLL by running the regsvr32.exe program with the filter DLL file name as an argument.
regsvr32.exe %SystemRoot%\system32\filter.dll

All the sample filters use macros defined in the header file filtreg.hxx to implement the registration entry point.

DllUnregisterServer
This entry point removes the DLL as a persistent handler in the registry. You unregister the DLL by running the regsvr32.exe program with the /u flag:
regsvr32.exe /u %SystemRoot%\system32\filter.dll

All the sample filters use macros, defined in the header file filtreg.hxx, to implement the unregistration entry point.

DllGetClassObject
The content indexing client calls this entry point, through COM, to create a class factory object for the filter and to get a pointer to the class factory interface of that object.
DllCanUnloadNow
The content-indexing client calls this entry point, through COM, to determine whether it is possible to unload the filter DLL. The filter is unloaded after it is unused for an interval of time as specified by the FilterIdleTimeOut registry value.


Implementing the Filter Class and Class Factory

At least two classes, such as CFilter and CFilterCF, are typically implemented by each filter DLL.

The CFilter class produces the filter object that implements the content-filtering functionality. Its member functions implement the interface methods of the filter. Each filter class requires a unique class identifier (CLSID), which the filter implementer generates.

The CFilterCF class produces the class-factory object for the filter. The class factory is called, through its IClassFactory interface, by the DllGetClassObject entry point of the DLL. The CFilterCF class creates the CFilter object and returns a pointer to its IUnknown interface.

In complex cases, a filter can implement a class hierarchy in place of the single CFilter class.


Inheriting the COM Interfaces

The filter-class factory inherits the IClassFactory interface. The filter class inherits the IFilter interface and one or more derived IPersist interfaces. These interfaces are declared in files included from the mssdk\include directory and have pre-defined interface identifiers (IIDs).

The filter class can inherit one or more of the IPersistFile, IPersistStorage, and IPersistStream interfaces. The content-indexing client queries the filter through its IUnknown interface to determine which of these interfaces to use when filtering content.


Implementing the COM Interface Methods

The filter implements the IUnknown methods for both the filter class and the filter-class factory. The following table lists, in vtable order, the filter-specific interfaces and methods that the filter must also implement. The filter must implement at least one, and can implement several, of the IPersist derived interfaces.

Interface | Method
IClassFactory | CreateInstance LockServer
IFilter | Init GetChunk GetText GetValue BindRegion
IPersist | GetClassID
IPersistFile | IsDirty Load Save SaveCompleted GetCurFile
IPersistStorage | IsDirty InitNew Load Save HandsOffStorage
IPersistStream | IsDirty Load Save GetSizeMax

The reference page for each method specifies the parameters and functional behavior for that method. Each reference page also gives the result codes to implement for that method. The reference pages for the IFilter methods give the interface-specific (FACILITY_ITF) result codes to be implemented, and the content-indexing client can also handle any of the generic (FACILITY_NULL and FACILITY_WIN32) result codes.


Testing Filters

You can test your filter implementations using the programs of the IFilter Test Suite. The IFilter Test Suite can validate IFilter interface implementations by calling IFilter methods and checking the returned values for compliance with the IFilter interface specification. Programs of the Test Suite will, for example, check that chunk identifiers are unique and increasing, that the IFilter interface behaves consistently after reinitialization, and that IFilter method calls with invalid parameters return expected error codes. The programs will also dump the output of a file filtered by an IFilter interface implementation and check the filter registration information in the registry.

The IFilter Test Suite consists of three programs — ifilttst.exe, filtdump.exe, and filtreg.exe — and an initialization file, ifilttst.ini. The programs are all command-line applications.

The topics in this section describe how to test your filter implementations using the IFilter Test Suite.

  • Command-Line Invocation
  • System Requirements
  • The ifilttst.ini File
  • Sample ifilttst.ini File
  • IFilter Test Procedure
  • Sample Log File
  • Sample Dump File


Command-Line Invocation

This section describes how to use the IFilter Test Suite programs from the command-line prompt. The programs are the following.

  • ifilttst.exe
  • filtdump.exe
  • filtreg.exe


ifilttst.exe

The ifilttst.exe program runs several tests to validate an IFilter interface implementation. You invoke the ifilttst.exe program from the command line as follows:

ifilttst /i test.htm /l /d /v 1

The preceding command line directs the program to filter the file "test.htm," redirect the log messages to "test.htm.log", redirect the dump messages to "test.htm.dmp", and set the verbosity to 1.

Note You must include a space between the command line switch and the value.

For the preceding command to work, three files must be located in the current working directory: ifilttst.exe, ifilttst.ini, and test.htm. The ifilttst.ini file is described in The ifilttst.ini File.

The command-line switches can include the following parameters.

Parameter | Meaning
/i <file name> | The input file or directory to be filtered. The file name can contain the wildcard characters * and ?.
/l | Log messages are directed to a file, rather than the screen. Log messages describe the individual tests performed and the pass/fail result of the test. The log file name is the same as the input file name with a .log extension.
/d | Dump messages are directed to a file instead of the screen. Dump messages describe the contents of the chunks. The chunk structure is dumped when the verbosity level is 3. The dump file name is the same as the input file name with a .dmp extension.
/-l | Disable logging. This flag overrides the /l parameter.
/-d | Disable dumping. This flag overrides the /d parameter.
/v <integer> The verbosity level. The default is 3.

0 — The test logs only messages concerning specific IFilter interface failures. The test dumps the chunk contents.

1 — The test logs warning messages as well as those for level 0.

2 — The test logs messages concerning tests which passed as well as those for level 1.

3 — The test logs informational messages as well as those for level 2. In addition, the test dumps the structure of the chunks.
/t <integer> | The number of threads to launch. One by default.
/r [<integer>] | Recursively filters subdirectories. The optional integer parameter specifies the depth to which to recurse. If no integer is specified, or if the integer is 0, full recursion is assumed. By default, the recursion depth is 1.
/c <integer> | The number of times to loop. If the integer is 0, the test loops infinitely. By default, the test loops only once.


filtdump.exe

The filtdump.exe program loads an IFilter interface implementation for a specified document and prints the output produced by the filter DLL. You invoke the filtdump.exe program from the command line as follows:

filtdump filename.ext

Filtdump.exe uses the LoadIFilter function to load the filter DLL appropriate for the specified file extension and prints the filtered results. For example, the command

filtdump myfile.smp

instructs filtdump.exe to load the smpfilt.dll filter for the extension .smp, extract all text and properties from the file myfile.smp, and print the results.


filtreg.exe

The filtreg.exe program inspects filter installation information in the registry. You invoke the filtreg.exe program from the command line simply by typing its name:

filtreg

Filtreg.exe enumerates all file extensions that have filters associated with them by printing the file extension and the name of the filter DLL for the extension. This is a simple way to verify the correct installation of a filter.


System Requirements

To run the IFilter Test Suite on your machine, you must have Internet Information Services (IIS) installed on Windows NT® 4 Server or on Windows® 2000 Server, Advanced Server, or Datacenter Server; or IIS Personal Web Server installed on Windows NT 4.0 Workstation or Windows 2000 Professional. You also must have installed Indexing Service 1.0 or later.


The ifilttst.ini File

An IFilter interface is initialized by calling the IFilter::Init method. The Init method takes four parameters, grfFlags, cAttributes, aAttributes and pdwFlags. The user of the ifilttst.exe program of the IFilter Test Suite can specify the values for these parameters in a file called ifilttst.ini. The next section, Sample ifilttst.ini File, shows a sample file.

The file is organized in sections, with the section name enclosed in square brackets. In the example, the sections are named Test1, Test2, and so forth. All section names must be unique. The test reads the values from the first section and initializes the filter with those values. Then it runs all its tests using this filter configuration. It then releases the filter and reinitializes it, using parameters from the next section. It repeats the process until all configurations have been tested.

The following table gives the parameters for the IFilter::Init method. Each section contains a complete description of the parameters.

Entry | Value of entry
Flags | The names of the IFILTER_INIT flags that are to be joined by the OR operator to form the grfFlags parameter. They must be all uppercase, and they must all be on the same line.
cAttributes | A decimal integer representing the value of the cAttributes parameter.
aAttributes | The name of this entry must start with "aAttributes" and must be different from the other aAttributes entries within the section. Legal names for the aAttributes entry are: aAttributes, aAttributes1, aAttributes2, and so forth. The first token must be a globally unique identifier (GUID). The GUID must be formatted exactly as shown in the section [Test3]. The second token can be either a property identifier (propid), consisting of a number in hexadecimal notation, or a pointer to a wide character string (lpwstr). A lpwstr can be specified by enclosing the string in double quotes (see section [Test6]).

If the Flags and cAttributes entries are not specified, they default to zero. If you set cAttributes equal to 2, you generally specify two aAttribute names. In section [Test5], cAttributes is 1, but no aAttributes have been specified. The test then calls the IFilter::Init method with cAttributes equal to 1, and aAttributes equal to NULL. This is a useful test case, since it is likely to cause an access violation in the IFilter::Init method.

There is no entry for the pdwFlags parameter since this parameter is used solely to return a value to the caller; it does not need to have any special value prior to the call to the IFilter::Init method.

If ifilttst.exe cannot find a file named ifilttst.ini in the working directory, it uses a default configuration to initialize the filter object. Below is the default configuration.

[default]
grfFlags = IFILTER_INIT_APPLY_INDEX_ATTRIBUTES
cAttributes = 0


Sample ifilttst.ini File

; Only extract text from the object
[Test1]
Flags =
cAttributes = 0

; Get all attributes (text-type and internal value-type properties)
[Test2]
Flags = IFILTER_INIT_APPLY_INDEX_ATTRIBUTES
cAttributes = 0

; This also extracts just text from the object (the GUID is PSGUID_STORAGE, and the propid is
; PID_STG_CONTENTS)
[Test3]
Flags = IFILTER_INIT_CANON_PARAGRAPHS IFILTER_INIT_HARD_LINE_BREAKS
cAttributes = 1
aAttributes1 = b725f130-47ef-101a-a5f1-02608c9eebac 13

; Only extract requested attribute from the html object (the GUID corresponds to the html filter)
[Test4]
Flags = IFILTER_INIT_CANON_HYPHENS IFILTER_INIT_CANON_SPACES
cAttributes = 1
aAttributes1 = 70eb7a10-55d9-11cf-b75b-00aa0051fe20 2

; What happens if cAttributes is nonzero, but aAttributes is empty?
[Test5]
Flags = IFILTER_INIT_CANON_SPACES IFILTER_INIT_APPLY_INDEX_ATTRIBUTES IFILTER_INIT_APPLY_OTHER_ATTRIBUTES
cAttributes = 1

; Here is an attribute with a lpwstr instead of a propid (the lpwstr is enclosed in quotes)
; The GUID corresponds to the meta tag clsid for the HTML filter.
[Test6]
Flags =
cAttributes = 1
aAttributes1 = D1B5D3F0-C0B3-11CF-9A92-00A0C908DBF1 "GENERATOR"


IFilter Test Procedure

Once the filter has been initialized, the ifilttst.exe program conducts a series of tests on the filter. These tests are described in the following sections.

  • Validation Test
  • Consistency Test
  • Invalid Input Test
  • Testing Different IFilter Configurations


Validation Test

The validation test steps through the object one chunk at a time, verifying each individual chunk and all return codes. This function saves all returned STAT_CHUNK structures in a list. The validation test verifies the following conditions.

  • Chunk IDs are unique and increasing.
  • STAT_CHUNK.flags is a recognized chunk state (CHUNK_TEXT or CHUNK_VALUE).
  • STAT_CHUNK.breakType is a recognized break type (0,1,2,3,4).
  • If the filter initialization attributes specify that the filter should only return chunks containing internal value-type properties, STAT_CHUNK.idChunkSource must equal 0.
  • If chunk is not derived—that is, if it is not a internal value-type property—idChunkSource must equal idChunk.
  • IFilter::GetChunk returns S_OK or an accepted value (FILTER_E_END_OF_CHUNKS, FILTER_E_LINK_UNAVAILABLE, and so forth).
  • If the chunk contains text, IFilter::GetText returns S_OK, FILTER_S_LAST_TEXT, or FILTER_E_NO_MORE_TEXT.
  • If IFilter::GetText returns FILTER_S_LAST_TEXT, the next call to IFilter::GetText should return FILTER_E_NO_MORE_TEXT.
  • If the chunk contains a value, IFilter::GetValue returns S_OK or FILTER_E_NO_MORE_VALUES.


Consistency Test

The ifilttxt.exe program reinitializes the IFilter interface with the same parameters as in the validation test and performs a consistency test. If the IFilter implementation has been initialized with the IFILTER_INIT_INDEXING_ONLY flag, the test releases the IFilter interface and re-binds it before making another call to the IFilter::Init method. This test checks to make sure that the STAT_CHUNK structures returned are identical to those returned in the validation test. The consistency test verifies the following conditions.

  • Each STAT_CHUNK structure returned by the IFilter::GetChunk method is exactly identical to the corresponding STAT_CHUNK returned in the validation test.
  • A IFilter::GetChunk method call returns S_OK or an accepted value (FILTER_E_END_OF_CHUNKS, FILTER_E_LINK_UNAVAILABLE, and so forth).


Invalid Input Test

The ifilttst.exe program reinitializes the IFilter interface with the same parameters and performs an invalid input test. This test steps through the document one chunk at a time, making function calls incorrectly—such as the IFilter::GetValue method when the current chuck contains text. The test checks all return codes for compliance with the IFilter specification. The invalid input test verifies the following conditions.

  • If the current chunk contains text, IFilter::GetValue returns FILTER_E_NO_VALUES. Then a call to IFilter::GetText should succeed.
  • If the current chunk contains a value, IFilter::GetText should return FILTER_E_NO_TEXT. Then a call to IFilter::GetValue should succeed.
  • If the previous call to IFilter::GetText returned FILTER_E_NO_MORE_TEXT, successive calls to IFilter::GetText should return FILTER_E_NO_MORE_TEXT.
  • If the previous call to IFilter::GetValue returned FILTER_E_NO_MORE_VALUES, successive calls to IFilter::GetValue should return FILTER_E_NO_MORE_VALUES.
  • If the previous call to IFilter::GetChunk returned FILTER_E_END_OF_CHUNKS, successive calls to IFilter::GetChunk should return FILTER_E_END_OF_CHUNKS.
  • In addition, the test compares the current chunk structures to those returned in the validation test to make sure they are identical.


Testing Different IFilter Configurations

The ifilttst.exe program releases the IFilter interface and rebinds, this time initializing it with the next set of parameters. The test repeats the cycle: validation test, consistency test, and invalid input test, until all the desired IFilter configurations, as specified in ifilttst.ini, have been tested.


Sample Log File

When requested, the Ifilttst.exe program produces a log containing a description of the steps it takes during execution. Here are some excerpts from a log file, with the verbosity set to 3 (highest verbosity).

1. INFO----**** New configuration ****
2.
3. Section name : Test2
4. grfFlags     : 63
5. cAttributes  : 0
6. aAttributes  : NONE
7. pdwFlags     : 0
8.
9. INFO----Successfully bound filter.
10.
11. PASS----Init() returned a valid value for pdwFlags.
12.
13. INFO----Successfully initialized filter.
14.
15. INFO----Performing validation test. In this part of the test, the chunks structures
16.         returned by the filter are checked for correctness, and the return values
17.         of the filter calls are checked.
18.
19. PASS----GetChunk() succeeded.
20.
21. PASS----The current chunk has a legal value for the flags field.

The first line is an informational message, indicating that a new configuration has been loaded from the ifilttst.ini file. Line (3) indicates the section name in the ifilttst.ini file from which the current configuration has been read. Lines (4) through (7) list the parameters to IFilter::Init. The lines starting with "INFO" are informational messages about the binding of the filter and start of the validation test. Lines starting with "PASS" are messages regarding specific tests that have passed.

WARNING-First call to GetText() returned FILTER_E_NO_MORE_TEXT.

The line above is a warning. Warnings call attention to filter behavior that is problematic, although legal. The above warning indicates that the IFilter::GetChunk method has returned a text chunk that contains no text.

ERROR---The filter has emitted a chunk which it was not requested to emit. Check
    the initialization parameters in section Test1 of the initialization file.

INFO----Current chunk propid : 0x5

Here is an example of an error message. In this case, the filter has emitted a chunk with a property identifier (ID) of 0x5. Inspection of section [Test1] in ifilttst.ini would show that the filter was configured to not emit chunks with this propid. For example, if neither IFILTER_INIT_APPLY_INDEX_ATTRIBUTES nor IFILTER_INIT_APPLY_OTHER_ATTRIBUTES was specified in the Flags entry and if cAttributes was 0, the filter would emit only chunks with a property ID of 0x13, corresponding to PID_STG_CONTENTS.


Sample Dump File

When requested, the Ifilttst.exe program produces a dump containing the chunks it finds and their content. Here is an excerpt from a dump file:

1. Chunk ID: ........... 2
2. Chunk Break Type: ... END OF SENTENCE
3. Chunk State: ........ TEXT
4. Chunk Locale: ....... 0x411
5. Chunk Source ID: .... 2
6. Chunk Start Source .. 0x0
7. Chunk Length Source . 0x0
8. GUID ................ b725f130-47ef-101a-a5f1-02608c9eebac
9. Property ID ......... 0x13

10. This is a HTML filter test page

11. Chunk ID: ........... 3
12. Chunk Break Type: ... END OF SENTENCE
13. Chunk State: ........ TEXT
14. Chunk Locale: ....... 0x411
15. Chunk Source ID: .... 2
16. Chunk Start Source .. 0x0
17. Chunk Length Source . 0x0
18. GUID ................ f29f85e0-4ff9-1068-ab91-08002b27b3d9
19. Property ID ......... 0x2

20. This is a HTML filter test page

21. Chunk ID: ........... 4
22. Chunk Break Type: ... END OF SENTENCE
23. Chunk State: ........ VALUE
24. Chunk Locale: ....... 0x411
25. Chunk Source ID: .... 2
26. Chunk Start Source .. 0x0
27. Chunk Length Source . 0x0
28. GUID ................ f29f85e0-4ff9-1068-ab91-08002b27b3d9
29. Property ID ......... 0x2

30. This is a HTML filter test page

The first nine lines describe the current chunk structure. Note that the globally unique identifier (GUID) and the property ID correspond to PSGUID_STORAGE / PID_STG_CONTENTS. This is a chunk containing plain text. The text follows the chunk structure: "This is an HTML filter test page."

The next chunk, starting at line (11), has a different GUID, corresponding to the HTML filter, and a different property ID, corresponding to an HTML HREF. This is an internal value-type property, exported by the HTML filter. The next chunk, starting at line (21), has the same GUID and property ID, but its chunk state is VALUE instead of TEXT. Note that the text in these last two chunks is the same as for the first chunk. The filter wanted three attributes (plain text, HTML HREF as text, and HTML HREF as a value) to be applied to this particular phrase, so it was emitted in three separate chunks.


Filter Samples

This section describes some individual sample filters in the Platform SDK. The following samples are listed in order of increasing complexity.

  • SmpFilt Sample. An example implementation of the IFilter interface for unformatted, single-byte-character text files.
  • IFilter Sample. An example implementation of the IFilter interface that filters both text-type and value-type properties for HTML files.
  • HtmlProp Sample. An example implementation of the IFilter interface that specializes the HTML filter (HtmlFilt) implementation of Indexing Service to extract and convert HTML <META> tags to value-type properties.


SmpFilt Sample

The SmpFilt sample is an example IFilter implementation that reads an unformatted text file (with the extension .smp), using the ANSI code page of the current thread, and outputs UNICODE text for the current locale. It accepts as input only single-byte-character text files and not multibyte-character or UNICODE text files. It is the simplest sample of an IFilter implementation included in the Indexing Service sample code.

Path

Source: mssdk\samples\winbase\indexing\smpfilt\

User's Guide

To build the sample

  1. Set the Lib environment variable to "D:\mssdk\Lib;%Lib%" and the Include environment variable to "D:\mssdk\Include;%Include%", where D: is the drive on which you installed the Platform SDK.
  2. Correctly set the CPU environment variable to, for example, "i386".
  3. Open a command window and change the directory to the source path of the sample.
  4. Build the filter DLL by entering, at the command-line prompt, "nmake".

To register the sample

  1. Copy the filter DLL file SmpFilt.dll to your %windir%\System32 directory.
  2. Self-register the filter by entering, at the command-line prompt, "regsvr32.exe %windir%\System32\SmpFilt.dll".
  3. Enable automatic registration of the filter by adding it to the MULTI_SZ value of the DLLsToRegister entry in the registry under the following key.
    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\ContentIndex.

To filter files and submit queries using the sample

  1. Create one or more files to filter. For example, copy the source file SmpFilt.cxx to a file named SmpFilt.smp.
  2. Restart the cisvc service. Touch the .smp files and wait for Indexing Service to filter them.
  3. Formulate queries that you know will succeed on the .smp files and submit them using the Indexing Service MMC snap-in or one of the sample query programs in the Platform SDK.

Programming Notes

The SmpFilt sample illustrates the basic structure of a filter. It minimally implements the methods of the IFilter and IPersistFile interfaces. Because the SmpFilt sample does not filter any value-type properties, the implementation of IFilter::GetChunk does not process properties other than "contents," and IFilter::GetValue always indicates no values. For examples of how to filter value-type properties as well as text, refer to the IFilter Sample (HtmlFilt) or the HtmlProp Sample in the Platform SDK.

Error-handling in the SmpFilt sample is rudimentary. The sample handles only the most obvious error conditions. Comments in the source code list all the standard result codes and indicate whether they are implemented. If you use SmpFilt as a basis for your own filter, carefully determine the additional error conditions that you need to detect and handle.


IFilter Sample

The IFilter sample (HtmlFilt) is an example IFilter implementation for HTML files. It is more complex than the basic text filter, because it demonstrates techniques for filtering both text-type and value-type properties.

Path

Source: mssdk\samples\winbase\indexing\ifilter\

User's Guide

To build the sample

  1. Set the Lib environment variable to "D:\mssdk\Lib;%Lib%" and the Include environment variable to "D:\mssdk\Include;%Include%", where D: is the drive on which you installed the Platform SDK.
  2. Correctly set the CPU environment variable, for example to "i386".
  3. Open a command window and change the directory to the source path of the sample.
  4. Build the filter DLL by entering, at the command-line prompt, "nmake".

To register the sample

  1. Copy the filter DLL file HtmlFilt.dll to your %windir%\System32 directory.
  2. Self-register the filter by entering, at the command-line prompt: "regsvr32.exe %windir%\System32\HtmlFilt.dll".
  3. Enable automatic registration of the filter by adding it to the MULTI_SZ value of the DLLsToRegister entry in the registry under the following key.
    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\ContentIndex.
  4. Remove the default HTML filter, nlhtml.dll, from the registry key given in Step 3. If you don't perform this step, the default HTML filter will re-register when Indexing Service starts.

To filter files and submit queries using the sample

  1. Create one or more appropriate HTML files to filter. Or, check that you already have one or more HTML files with the appropriate sample title, headings, and anchors.
  2. Restart the cisvc service. Touch the HTML files and wait for Indexing Service to filter them.
  3. Formulate queries that you know will succeed on the HTML files and submit them using the Indexing Service MMC snap-in or one of the sample query programs in the Platform SDK.

Programming Notes

HTMLFilt will extract text-type and value-type properties from HTML pages. In addition to the body of the text as a text-type property, headings (levels 1 to 6), title, and anchors are extracted as internal value-type properties available using the IFilter::GetValue method.


HtmlProp Sample

The HtmlProp sample is an example IFilter implementation that specializes the Indexing Service HTML filter to extract value-type properties. It converts HTML meta properties to data types other than strings as specified by a configuration file.

Path

Source: mssdk\samples\winbase\indexing\htmlprop\

User's Guide

To build the sample

  1. Set the Lib environment variable to "D:\mssdk\Lib;%Lib%" and the Include environment variable to "D:\mssdk\Include;%Include%", where D: is the drive on which you installed the Platform SDK.
  2. Correctly set the CPU environment variable, for example to "i386".
  3. Open a command window and change directory to the source path of the sample.
  4. Build the filter DLL by entering, at the command-line prompt, "nmake".

To register the sample

  1. Copy the filter DLL file HtmlProp.dll to your %windir%\System32 directory.
  2. Self-register the filter by entering, at the command-line prompt: "regsvr32.exe %windir%\System32\HtmlProp.dll".
  3. Enable automatic registration of the filter by adding it to the MULTI_SZ value of the DLLsToRegister entry in the registry under the following key.
    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\ContentIndex.

To filter files using the sample

  1. Update htmlprop.ini to specify data types for the HTML meta properties you have defined in your HTML files. Update your HTML files to contain properties that match the definitions. For examples, refer to the sample files htmlprop.ini, dog1,htm, dog2.htm, and dog3.htm.
  2. Copy the file htmlprop.ini to your %windir%\System32 directory.
  3. Copy the properties you defined in htmlprop.ini to your .idq file and/or update your .asp script to define these properties.
  4. Restart the cisvc service. If the files don't need to be filtered, touch files containing all of the meta properties added to htmlprop.ini and wait for them to be filtered.
  5. Using the Indexing Service MMC snap-in, update the property cache to contain the properties you have defined. Be sure to choose the equivalent data type for each property or queries won't work. For example, DBTYPE_I4 is the same as VT_I4.
  6. Force a full re-scan of all files and wait for the index to be updated.

Note Don't commit properties when scans are in progress. Wait for scans to complete. Index Server 2.0 has a bug that will cause your index to become corrupt. The bug is fixed in Indexing Service 3.0, in non-U.S. Index Server 2.0 versions, and in Windows NT® 4.0 Service Pack 4.

You need to repeat steps 5 and 6 when your index is corrupt. Index Server 2.0 doesn't retain the list of properties in the property cache when your index becomes corrupt. Indexing Service 3.0, non-U.S. releases of Index Server 2.0, and Windows NT 4.0 Service Pack 4 actually remember the properties.

To query using the sample

Issue queries using the properties and/or retrieve the values in their native types. The following are some sample queries using the sample files.

@breedWeight > 10

@breedOrigin = Australia

@breedFirstBred = 1840

Programming Notes

The HtmlProp filter loads the default HTML filter (nlhtml.dll) and passes most of the processing to that filter. If the htmlprop.ini configuration file specifies that certain HTML meta properties should be converted into non-string data types, HtmlProp takes the string value from the HTML filter and coerces it into the desired type.

This is useful because if htmlprop.dll is installed and properly configured, the following actions are possible:

  • You can query HTML meta property values using data types other than strings.
  • You can sort meta properties using native data types, rather than just strings.
  • You can retrieve properties in .htx/.asp scripts in their native types, rather than as strings.

HtmlProp supports the following data types.

DBTYPE_UI1, DBTYPE_I2, DBTYPE_UI2, DBTYPE_I4, DBTYPE_UI4, DBTYPE_I8, DBTYPE_UI8, DBTYPE_R4, DBTYPE_R8, and VT_FILETIME

By modifying htmlprop.cxx, additional data types can be supported, and additional date formats can be added. Currently, only the Indexing Service syntax is supported for date specifications.

VT_FILETIME values can be in any time zone you like, but the .htx file parser in Indexing Service assume all times are Coordinated Universal Time (UTC) and will be displayed as such.


Indexing Service Reference

This section contains reference information for high-level API elements provided by Indexing Service. These programming elements are part of the Admin Helper, Query Helper, OLE DB Helper, and Filter Component APIs.

For information about low-level OLE DB Provider for Indexing Service API elements, see OLE DB Provider for Indexing Service Reference.

The reference material is divided into the following categories.

  • Objects
  • Interfaces
  • Functions
  • Property Sets
  • Structures
  • Enumerated Types
  • Constants
  • Return Values
  • Registry Entries
  • Query Language Syntax
  • Dynamic ADO Properties
  • Glossary


Objects

Indexing Service provides a group of objects you can use in scripting languages such as Microsoft® Visual Basic® Scripting Edition (VBScript) and Microsoft JScript®. In fact, you can use these objects with any programming language that supports Automation.

The objects provided by Indexing Service fall into one of two categories:

  • Administration Automation Objects
  • Query Automation Objects

Indexing Service Administration Automation Objects

The Indexing Service Administration Automation Objects contained in ciodm.dll provide ways to manage Indexing Service.

Object name | Description
AdminIndexServer | Manages Indexing Service. Allows access to all the functionality provided by the Microsoft Management Console (MMC) snap-in.
CatAdm | Manages the collection of scopes for a catalog.
ScopeAdm | Manages an individual scope.

Indexing Service can be administered in two ways:

  • Manually, by using the Indexing Service Management snap-in, which is accessible by clicking the right-mouse button on the My Computer icon on the desktop. Manage opens the Computer Management console. Choose Server Applications and Services\Indexing Service on Local computer.
  • Programmatically, by writing applications or scripts to administer Indexing Service components with the Indexing Service Administration Automation Objects.

Examples showing how Indexing Service components can be managed using the administration, catalog, and scope objects that can be found in the mssdk\samples\internet\index\VBAdmin sample code.

Indexing Service Query Automation Objects

The Indexing Service Query Automation Objects in ixsso.dll give script writers control over creating and managing queries and the resultant record sets. Originally designed to integrate Indexing Service with Active Server Pages (ASP) on the Web server, these objects can also be used by client-side scripts, server-side scripts , Windows® Script Host (CScript.exe, WScript.exe), and any Automation-enabled language.

These objects include:

Object name | Description
Query | Manages the query definition and result-set creation and navigation.
Utility | Helpful utilities for managing the queries and result sets.

Examples showing how queries can be created with these objects can be found in the Platform SDK mssdk\samples\internet\index\vbquery directory.


AdminIndexServer

The AdminIndexServer object manages the indexing service itself, including the collection of catalogs that identify the documents to be indexed. This object also provides methods to detect whether the indexing service is currently running and to start and stop it programmatically.

Property names | Type | Access | Description
MachineName | String | Read/ write | Name of Indexing Service machine. Write once only.

Methods

Method names | Description
AddCatalog | Creates a new catalog.
Continue | Continues Indexing Service.
FindFirstCatalog | Initializes catalog enumeration. TRUE if a catalog exists and can be retrieved.
FindNextCatalog | Enumerates the next catalog. TRUE if next catalog exists and can be retrieved.
GetCatalog | Retrieves the current catalog during an enumeration.
GetCatalogByName | Retrieves a catalog object by name.
GetLongProperty | Retrieves a content index registry value of type REG_DWORD, as described in Registry Entries. Accessed as type Long in Visual Basic.
GetSZProperty | Retrieves a content index registry value of type String REG_SZ, as described in Registry Entries. Accessed as type String in Visual Basic.
IsPaused | Checks to see whether Indexing Service is paused.
IsRunning | Determines whether Indexing Service is running.
Pause | Pauses Indexing Service.
RemoveCatalog | Removes an existing catalog.
SetLongProperty | Sets a content index registry value of type Long (REG_DWORD) as described in Registry Entries.
SetSZProperty | Retrieves a content index registry value of type String (REG_SZ) as described in Registry Entries.
Start | Starts Indexing Service.
Stop | Stops Indexing Service.

Remarks

Although you can manage many aspects of Indexing Service while it is running, you must stop the service to create catalogs with the AddCatalog method or delete catalogs with RemoveCatalog. To determine whether Indexing Service is running, use IsRunning. To stop the service, use the Stop method, make any additions or deletions necessary, and begin the service again using the Start method. Additional information about configuring catalogs can be found through the Help command on the Start menu on the main taskbar under the topic Other Tools.

If multiple instances of the AdminIndexServer object are created, changes made to one instance do not propagate to the other running instances. For example, if you have two instances of the AdminIndexServer object running and invoke the AddCatalog method of one object, the other AdminIndexServer object doesn't know about the newly added catalog. New instances of this object are created with the most current information.

The programmatic identifier (ProgID) in the registry under HKEY_LOCAL_MACHINE/Software/Classes for the administration object in ciodm.dll is Microsoft.ISAdm.1. The version-independent ProgID is Microsoft.ISAdm. The Indexing Service administration object implementation is enabled for apartment and free threading.

This object supports IErrorInfo to report errors.

Registry entries currently in use by Indexing Service can be found under HKEY_LOCAL_MACHINE/System/CurrentControlSet/Control/ContentIndex.

Example

Set objISAdmin = CreateObject("Microsoft.ISAdm")

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


AdminIndexServer.AddCatalog

The AddCatalog method creates a new catalog to be used by Indexing Service that runs on the computer specified by the MachineName property.

Syntax

Set objCatAdm = objAdminIS.AddCatalog(strCatName, strCatLocation)
objCatAdm
The new catalog object if the create action is successful.
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.
strCatName
Required. String. The name of the catalog. The catalog name cannot be reused on the same computer. Limited to 40 characters in length.
strCatLocation
Required. String. The full path name to a local nonremovable drive where the catalog is located.

Remarks

Indexing Service must be stopped, using the Stop method, before creating a new catalog. If the specified catalog location doesn't already exist, a catalog folder is created at the specified location.

Example

' Add another catalog to index
Set objCatAdmin =  objAdminIS.AddCatalog("sources","d:\src")

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

RemoveCatalog


AdminIndexServer.Continue

The Continue method continues Indexing Service.

Syntax

objAdminIS.Continue( )
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.

Example

If objCatAdm.IsPaused Then
   objCatAdm.Continue()
EndIf

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


AdminIndexServer.FindFirstCatalog

The FindFirstCatalog method determines whether a catalog exists. It also initializes the enumeration of catalogs, enabling you to find additional catalogs using the FindNextCatalog method.

Syntax

blnFound = objAdminIS.FindFirstCatalog( )
blnFound
VARIANT_BOOL. TRUE if catalog was found, otherwise FALSE.
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.

Remarks

If this method finds a catalog, use GetCatalog to retrieve the catalog object. To find additional catalogs, if any, use the FindNextCatalog method after using FindFirstCatalog.

Example

Set objCatAdmin = CreateObject("Microsoft.ISAdm")
' Find the first catalog
bFound = objCatAdmin.FindFirstCatalog()
If (bFound)
   Set objCatAdm = objAdminIS.GetCatalog()
'   Work with this catalog
'   Free this catalog object
   Set objCatAdm = Nothing
EndIf

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

FindNextCatalog


AdminIndexServer.FindNextCatalog

The FindNextCatalog method enumerates the collection of catalogs for Indexing Service from the current location and checks whether another catalog exists. Before calling this method, call FindFirstCatalog to initialize catalog enumeration.

Syntax

blnFound = objAdminIS.FindNextCatalog( )
blnFound
VARIANT_BOOL. TRUE if next catalog was found, FALSE otherwise.
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.

Remarks

If this method finds another catalog, use GetCatalog to retrieve the catalog object.

Example

' Enumerate through the catalogs
Do While (objAdminIS.FindNextCatalog() )
   Set objCatAdm = objAdminIS.GetCatalog()
   ' Use objCatAdm
   ' Free the catalog object
   Set objCatAdm = Nothing
Loop

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

FindFirstCatalog


AdminIndexServer.GetCatalog

The GetCatalog method retrieves the current catalog object.

Syntax

Set objCatAdm = objAdminIS.GetCatalog( )
objCatAdm
The CatAdm object that represents the current catalog.
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.

Remarks

This method assumes that the catalog exists and has been found by enumerating an administration object's collection of catalogs using FindFirstCatalog or FindNextCatalog.

Example

' Find the next catalog
Do While (objAdminIS.FindNextCatalog( ) )
   Set objCatAdm = objAdminIS.GetCatalog()
   ' Use objCatAdm
   ' Free the catalog object
   Set objCatAdm = Nothing
Loop

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

GetCatalogByName


AdminIndexServer.GetCatalogByName

The GetCatalogByName method retrieves an existing catalog object from a catalog collection, given its name.

Syntax

Set objCatAdm = objAdminIS.GetCatalogByName(strCatName)
objCatAdm
The CatAdm object that represents the retrieved catalog.
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.
strCatName
Required. String. The name of an existing catalog.

Remarks

This method expects an existing catalog name. When you attempt to retrieve a nonexistent catalog object, Indexing Service returns an error object with the Number property set to ERROR_NOT_FOUND.

Example

' Get a catalog object named "Sources"
Set objCatAdm = objAdminIS.GetCatalogByName("Sources")

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

GetCatalog


AdminIndexServer.GetLongProperty

The GetLongProperty method retrieves the value of an existing Indexing Service registry value of type Long (REG_DWORD in the registry).

Syntax

lngPropValue = objAdminIS.GetLongProperty(strPropName)
lngPropValue
Long. The retrieved property value.
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.
strPropName
Required. String. The name of an existing Indexing Service registry value.

Remarks

The registry value name must already exist for the Indexing Service entry. Attempting to retrieve the value of a nonexistent property results in the creation of an error object with the Number property set to E_FAIL.

Example

' See if indexing is set to create abstracts of the documents being
'   indexed
lngCreateAbstracts = objAdminIS.GetLongProperty( "GenerateCharacterization")

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

GetSZProperty, SetLongProperty, Registry Entries


AdminIndexServer.GetSZProperty

The GetSZProperty method retrieves the value of an existing Indexing Service registry value of type REG_SZ (null-terminated string). This value is accessed as type String in Visual Basic.

Syntax

strPropValue = objAdminIS.GetSZProperty(strPropName)
strPropValue
String. The retrieved value.
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.
strPropName
Required. String. The name of an existing registry value.

Remarks

The registry value must already exist for the Indexing Service entry. Attempting to retrieve the value of a nonexistent property results in the creation of an error object with the Number property set to E_FAIL.

Example

' Get the default Catalog directory
strCatalogName = objAdminIS.GetSZProperty("ISAPIDefaultCatalogDirectory")

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

GetLongProperty, SetSZProperty, Registry Entries


AdminIndexServer.IsPaused

The IsPaused method checks whether the Indexing Service is currently paused.

Syntax

blnIsPaused = objAdminIS.IsPaused( )
blnIsPaused
VARIANT_BOOL. TRUE if Indexing Service is paused, otherwise FALSE.
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.

Example

If objCatAdm.IsPaused Then
   objCatAdm.Continue()
EndIf

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


AdminIndexServer.IsRunning

The IsRunning method checks whether Indexing Service is currently running.

Syntax

blnIsRunning = objAdminIS.IsRunning( )
blnIsRunning
VARIANT_BOOL. TRUE if the indexing service is running, FALSE otherwise.
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.

Example

' Get the catalog state if content indexing service is running
If objAdmIS.IsRunning Then
    lngStateInfo = objCatAdm.StateInfo( )
EndIf

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

Start, Stop


AdminIndexServer.MachineName

The MachineName property is the case-insensitive name of the computer where Indexing Service is running. This property is read/write, but once it is set it cannot be changed. It identifies the computer that the administration object controls and can be set only once. If not set, the content index on the local computer is administered by default.

Type

String

Syntax

objAdminIS.MachineName
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.

Remarks

This property must be set to administer Indexing Service on remote computers. If this property is not set, the local machine is administered by default. The local machine name is represented by ".". Attempting to set this property more than once results in the creation of an error object with the Number property set to ERROR_ALREADY_INITIALIZED.

Example

' To administer indexing services on a remote machine,
'   set the MachineName property to the remote machine name
objAdminIS.MachineName = "RemoteServer1"

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


AdminIndexServer.Pause

The Pause method pauses Indexing Service.

Syntax

objAdminIS.Pause( )
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.

Example

If objCatAdm.IsRunning Then
   objCatAdm.Pause()
EndIf

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


AdminIndexServer.RemoveCatalog

The RemoveCatalog method removes an existing catalog from the collection of catalog objects managed by an AdminIndexServer object. It can also delete the catalog directory from the system.

Syntax

objAdminIS.RemoveCatalog(strCatName, blnDelDirectory)
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.
strCatName
Required. String. The name of an existing catalog to remove.
blnDelDirectory
Optional. VARIANT_BOOL. Defaults to FALSE. To delete the directory and remove the catalog from the collection, set this to TRUE. To remove the catalog from the collection but leave the directory intact, set this to FALSE.

Remarks

Indexing Service must be stopped before a catalog can be removed.

Example

' Remove the directory "src" from catalogs to be indexed, but
'  don't delete it.
objAdminIS.Stop   'Stop the indexing service
objAdminIS.RemoveCatalog("src")
objAdminIS.Start  'Start the indexing service up again

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

AddCatalog


AdminIndexServer.SetLongProperty

The SetLongProperty method sets the Indexing Service value strPropName with a value of type Long (REG_DWORD in the registry). This value is accessed as type Long in Visual Basic.

Syntax

objAdminIS.SetLongProperty(strPropName, lngPropValue)
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.
strPropName
Required. String. The name of an existing registry value that refers to a value of type REG_DWORD.
lngPropValue
Required. The value to store in the given registry value name.

Remarks

This method does not validate that a property name/value is a valid Indexing Service property. It is the caller's responsibility to verify that the property name and value are valid under the HKLM\System\CurrentControlSet\Control\ContentIndex entries. If strPropName exists, its value is set to lngPropValue. Otherwise, the strPropName value name is created and set to lngPropValue.

Example

' Set the current value of the flag that determines whether or not
'    to filter the system properties of directories.
objAdminIS.SetLongProperty( "FilterDirectories", 1)

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

GetLongProperty, SetSZProperty, Registry Entries


AdminIndexServer.SetSZProperty

The SetSZProperty method stores a REG_SZ value under the HKLM\System\CurrentControlSet\Control\ContentIndex registry subkey.

Syntax

objAdminIS.SetSZProperty(strPropName, strPropValue)
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.
strPropName
Required. String. The name of an Indexing Service property to set.
strPropValue
String. Required. The value to which the property should be set.

Remarks

This method does not guarantee that a property name/value is a valid Indexing Service property. It is the responsibility of the caller to verify that the property name and value are valid under the HKLM\System\CurrentControlSet\Control\ContentIndex entries. If strPropName exists, its value is set to strPropValue. Otherwise, the strPropName value name is created and set to strPropValue.

Example

' Set the default Catalog directory
objAdminIS.SetSZProperty("ISAPIDefaultCatalogDirectory","system")

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

GetSZProperty, SetLongProperty, Registry Entries


AdminIndexServer.Start

The Start method initiates Indexing Service on the computer named in the MachineName property (if Indexing Service wasn't already running).

Syntax

objAdminIS.Start( )
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.

Remarks

Any failure encountered when trying to start Indexing Service results in the creation of an error object. A call to this method does not return until the Indexing Service has finished starting.

Example

' The following starts the indexing service:
Set objAdminIS = CreateObject("Microsoft.ISAdm")
objAdminIS.Start()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

IsRunning, Stop


AdminIndexServer.Stop

The Stop method shuts down Indexing Service on the computer named in the MachineName property (if Indexing Service is already running).

Syntax

objAdminIS.Stop( )
objAdminIS
Required. The AdminIndexServer object that manages Indexing Service.

Remarks

Any failure encountered when using the Stop stop method to stop Indexing Service results in the creation of an error object. A call to this method does not return until Indexing Service has finished shutting down.

Example

' The following stops Indexing Service:
' Assume the following statement has been executed
'  Set objAdminIS = CreateObject("Microsoft.ISAdm")
objAdminIS.Stop()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

IsRunning, Start


CatAdm

The CatAdm catalog administration object manages a catalog definition for Indexing Service. The catalog defines the set of documents to index by specifying the list of directories that are used by Indexing Service to determine the files to index. Catalog objects can be created only by means of the AddCatalog method on the AdminIndexServer object and can be retrieved in the following ways.

  • Through the numeration methods FindFirstCatalog and FindNextCatalog on the AdminIndexServer class; or
  • GetCatalogByName on the AdminIndexServer class.

The properties supported on this object include counters that show the current state of the indexing process.

Use methods defined on the CatAdm object to monitor performance, adjust local parameters, force merges, and add and remove scopes from the catalog.

Remarks

Access CatAdm objects only through methods defined on the AdminIndexServer object.

This object supports IErrorInfo to report errors.

The following table lists the catalog properties of CatAdm objects. Many of these properties can only be retrieved while Indexing Service is running.

Property names | Type | Access | Description
CatalogLocation | STR | R/O | Case-insensitive path.
CatalogName | STR | R/O | Case-insensitive catalog name.
DelayedFilterCount | LONG | R/O | Count of documents delayed for indexing. This reflects the number of documents that couldn't be indexed during a previous pass for various reasons, such as sharing violations.
DocumentsToFilter | LONG | R/O | Number of documents to index.
FilteredDocumentCount | LONG | R/O | Number of documents indexed since the last time Indexing Service started.
FreshTestCount | LONG | R/O | FOR INTERNAL USE.
IndexSize | LONG | R/O | Total size of the index in megabytes. Includes master and shadow indexes, and the property store.
IsUpToDate | VARIANT_BOOL | R/O | Flag indicating whether index is up to date.
PctMergeComplete | LONG | R/O | Percentage of merge process completed.
PendingScanCount | LONG | R/O | Number of directories to be scanned.
PersistentIndexCount | LONG | R/O | Number of persistent indexes that currently exist.
QueryCount | LONG | R/O | Number of active queries since Indexing Service started.
StateInfo | LONG | R/O | A combination of CI_STATE_* constants reflecting the state of the service.
TotalDocumentCount | LONG | R/O | Total document count in the set of documents to index.
UniqueKeyCount | LONG | R/O | Number of unique keys. Includes existing persistent indexes and nonpersistent wordlists.
WordListCount | LONG | R/O | Number of existing word lists.

Method names | Description
AddScope | Creates a new scope.
ContinueCatalog | Starts the catalog and returns its previous state.
FindFirstScope | Finds the first scope in an enumeration.
FindNextScope | Finds the next scope in an enumeration.
ForceMasterMerge | Begins a master index merge for the catalog.
GetScope | Retrieves current scope object.
GetScopeByAlias | Retrieves scope object by alias name.
GetScopeByPath | Retrieves scope object by path name.
IsCatalogPaused | Checks whether the catalog is in read-only mode.
IsCatalogRunning | Checks whether the catalog is in read/write mode.
IsCatalogStopped | Checks whether the catalog is stopped.
PauseCatalog | Pauses the catalog and returns its previous state.
RemoveScope | Removes an existing scope object from a collection.
StartCatalog | Starts the catalog and returns its previous state.
StopCatalog | Stops the catalog and returns its previous state.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.AddScope

The AddScope method creates a new scope in the collection of scopes managed by a CatAdm object.

Syntax

objScopeAdm = objCatAdm.AddScope(strScopePath, blnExclude, [vtLogon], [vtPassword])
objScopeAdm
The new ScopeAdm object.
objCatAdm
Required. The CatAdm object managing the collection of scopes within the current catalog.
strScopePath
Required. String. The case-insensitive scope path to create. This path must be unique for a given catalog and must represent a valid local path or a universal naming convention (UNC) path.
blnExclude
Required. VARIANT_BOOL. If TRUE, excludes this scope from indexing. If FALSE, enables indexing for this scope.
vtLogon
Optional. Variant. String that represents the logon name.
vtPassword
Optional. Variant. String that represents the logon password.

Remarks

The vtLogon and vtPassword arguments are optional. However, they are both required if the scope path is a UNC path. Neither argument should be supplied when the scope path is local.

Values for the Number property of the Error object include:

ERROR_ALREADY_EXISTS
The path in strScopePath already is in use.
E_INVALIDARG
The logon and password values are included for local paths or the logon and password values are missing for UNC paths.

Example

' Create a scope for a remote UNC share
Set objScopeAdm = objCatAdm.AddScope("\\Server1\Correspondence\", _
FALSE, "LogonName", "LogonPassword")

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

RemoveScope


CatAdm.CatalogLocation

The CatalogLocation property is the case-insensitive path of the catalog. This property is read-only.

Syntax

objCatAdm.CatalogLocation
objCatAdm
Required. The CatAdm object managing the collection of scopes within this catalog.

Example

' The value of objCatAdm.CatalogLocation might be
'    "c:\InetPub" or "d:\"
Select Case objCatAdm.CatalogLocation
    Case "c:\InetPub"
        ' actions taken in this instance
    Case "d:\"
        ' actions taken in this instance
    Case Else
        ' actions taken if other cases fail
End Select

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.CatalogName

The CatalogName property is the case-insensitive name of the catalog. This property is read-only.

Syntax

objCatAdm.CatalogName
objCatAdm
Required. The CatAdm object managing the collection of scopes within this catalog.

Example

' The value of objCatAdm.CatalogName might be
'   "system" or "Web".
Select Case objCatAdm.CatalogName
    Case "system"
        ' take actions for system catalog
    Case "web"
        ' take actions for web catalog
End Select

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.ContinueCatalog

The ContinueCatalog method starts the catalog and returns its previous state.

Syntax

lngState = objCatAdm.ContinueCatalog( )
lngState
Long. A numeric value that indicates the previous state of the catalog. Can be any of the values associated with the CICAT* Constants.
objCatAdm
Required. The CatAdm object that manages the scopes for this catalog.

Example

' Restart the catalog
lngState = objCatAdm.ContinueCatalog()
' Check previous state to make sure you can query
If lngState = CICAT_WRITABLE Or CICAT_READONLY Then
    ' Run a query
End If

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

StartCatalog, StopCatalog, PauseCatalog


CatAdm.DelayedFilterCount

The DelayedFilterCount property is the current number of documents that weren't indexed on the first try for reasons such as sharing violations; for example, some other process locked the file when Indexing Service was trying to open it for indexing. This property is read-only.

Syntax

objCatAdm.DelayedFilterCount
objCatAdm
Required. The CatAdm object that manages the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Example

' Check for unindexed documents
If objCatAdm.DelayedFilterCount > 0 Then
    ' take action as necessary
End If

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.DocumentsToFilter

The DocumentsToFilter property is the number of documents left to index. This property is read-only.

Syntax

objCatAdm.DocumentsToFilter
objCatAdm
Required. The CatAdm object that manages the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Example

' Check for documents left to index
If objCatAdm.DocumentsToFilter > 0 Then
    ' take action as necessary
End If

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.FilteredDocumentCount

The FilteredDocumentCount property is the number of documents indexed since the last time Indexing Service was started. This property is read-only.

Syntax

objCatAdm.FilteredDocumentCount
objCatAdm
Required. The CatAdm object managing the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Example

thisCount = objCatAdm.FindFirstScope

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.FindFirstScope

The FindFirstScope method initializes scope enumeration for a catalog and checks to see whether a catalog exists.

Syntax

blnFound = objCatAdm.FindFirstScope( )
blnFound
VARIANT_BOOL. TRUE if a scope was found, FALSE otherwise.
objCatAdm
Required. The CatAdm object that manages the scopes for this catalog.

Remarks

If a scope exists, use GetScope to retrieve the scope object.

Example

' Find the first scope
If (objCatAdm.FindFirstScope( ) ) Then
    Set objScopeAdm = objCatAdm.GetScope()
'  Use it
'  Free when finished
    Set objScopeAdm = Nothing
End If

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

FindNextScope


CatAdm.FindNextScope

The FindNextScope method enumerates a collection of scopes for the current catalog and checks whether another catalog exists.

Syntax

blnFound = objCatAdm.FindNextScope( )
blnFound
VARIANT_BOOL. TRUE if a scope was found, FALSE otherwise.
objCatAdm
Required. The CatAdm object that manages the scopes for this catalog.

Remarks

If a scope is found, use GetScope to retrieve the scope object.

Example

' Enumerate through the scopes
Do While (objCatAdm.FindNextScope() )
    Set objScopeAdm = objCatAdm.GetScope()
'  Use it
'  Free it when done
    Set objScopeAdm = Nothing
Loop

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

FindFirstScope


CatAdm.ForceMasterMerge

The ForceMasterMerge method initiates a master merge for the current catalog.

Syntax

objCatAdm.ForceMasterMerge( )
objCatAdm
Required. The CatAdm object that manages the scopes for this catalog.

Remarks

This method starts a master merge on the current catalog and immediately returns control to the caller.

Example

' Time to merge all the indexes...
objCatAdm.ForceMasterMerge( )

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.FreshTestCount

The FreshTestCount property is the number of entries in the fresh test list. This property is read-only. For internal use only.

Syntax

objCatAdm.FreshTestCount
objCatAdm
Required. The CatAdm object that manages the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.GetScope

The GetScope method retrieves the current scope object.

Syntax

Set objScopeAdm = objCatAdm.GetScope( )
objScopeAdm
The current scope object.
objCatAdm
Required. The CatAdm object that manages the scopes for this catalog.

Remarks

This method assumes that the scope exists and has been found by enumerating a catalog administration object's collection of scopes using FindFirstScope or FindNextScope.

Example

' Find the first scope
Do While (objCatAdm.FindNextScope( ) )
    Set objScopeAdm = objCatAdm.GetScope()
'  Use the scope
'  Free the scope when done
    Set objScopeAdm = Nothing
End If

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

GetScopeByAlias, GetScopeByPath


CatAdm.GetScopeByAlias

The GetScopeByAlias method retrieves an existing scope object by alias or alternative friendly name for the scope.

Syntax

Set objScopeAdm = objCatAdm.GetScopeByAlias(strScopeAlias)
objScopeAdm
The returned CatAdm scope object.
objCatAdm
Required. The CatAdm object that manages the scopes for this catalog.
strScopeAlias
Required. String. The alias of an existing scope.

Remarks

The scope name must refer to a valid scope. If the name is not valid, an error object is created with the Number property set to ERROR_NOT_FOUND. The alias of a scope is defined by the Alias property of the scope's ScopeAdm object.

Example

' Retrieve the scope whose alias is "src"
Set objScopeAdm = objCatAdm.GetScopeByAlias("Src") )

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

GetScope, GetScopeByPath


CatAdm.GetScopeByPath

The GetScopeByPath method retrieves an existing scope object by path.

Syntax

Set objScopeAdm = objCatAdm.GetScopeByPath(strScopePath)
objScopeAdm
The returned CatAdm scope object.
objCatAdm
Required. The CatAdm object that manages the scopes for this catalog.
strScopePath
Required. String. The name of an existing scope. The scope path must be a valid local or universal naming convention (UNC) path.

Remarks

The scope name must refer to a valid scope. Specifying an invalid scope path results in the creation of an error object with the Number property set to ERROR_NOT_FOUND.

Example

' Get scope for "d:\sources" path
Set objScopeAdm = objCatAdm.GetScopeByPath("d:\Sources") )

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

GetScope, GetScopeByAlias


CatAdm.IndexSize

The IndexSize property is the total size of the index in megabytes, including the master index, shadow indexes, and the property store cache. This property is read-only.

Syntax

objCatAdm.IndexSize
objCatAdm
Required. The CatAdm object that manages the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.IsCatalogPaused

The IsCatalogPaused method checks whether the catalog is in read-only mode.

Syntax

blnPaused = objCatAdm.IsCatalogPaused( )
blnPaused
VARIANT_BOOL. TRUE if the catalog is in read-only mode, otherwise FALSE.
objCatAdm
Required. The CatAdm object managing the collection of scopes within this catalog.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.IsCatalogRunning

The IsCatalogRunning method checks whether the catalog is in read/write mode.

Syntax

blnRunning = objCatAdm.IsCatalogRunning( )
blnRunning
VARIANT_BOOL. TRUE if the catalog is in read/write mode, otherwise FALSE.
objCatAdm
Required. The CatAdm object that manages the collection of scopes within this catalog.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.IsCatalogStopped

The IsCatalogStopped method checks whether the catalog is stopped.

Syntax

blnStopped = objCatAdm.IsCatalogStopped( )
blnStopped
VARIANT_BOOL. TRUE if the catalog is stopped, otherwise FALSE.
objCatAdm
Required. The CatAdm object that manages the collection of scopes within this catalog.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.IsUpToDate

The IsUpToDate property is a flag that indicates whether the index is up to date. This property is read-only.

Syntax

objCatAdm.IsUpToDate
objCatAdm
Required. The CatAdm object that manages the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Example

' The value of objCatAdm.IsUpToDate

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.PauseCatalog

The PauseCatalog method pauses the catalog and returns its previous state.

Syntax

lngState = objCatAdm.PauseCatalog( )
lngState
Long. A numeric value that indicates the previous state of the catalog. Can be any of the values associated with the CICAT* Constants.
objCatAdm
Required. The CatAdm object that manages the scopes for this catalog.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.PctMergeComplete

The PctMergeComplete property is the percentage of the merge process completed. This property is read-only.

Syntax

objCatAdm.PctMergeComplete
objCatAdm
Required. The CatAdm object that manages the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.PendingScanCount

The PendingScanCount property is the number of directories remaining to be scanned during the scan process. This property is read-only.

Syntax

objCatAdm.PendingScanCount
objCatAdm
Required. The CatAdm object managing the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.PersistentIndexCount

The PersistentIndexCount property is the number of persistent indexes that exist for this catalog. This property is read-only.

Syntax

objCatAdm.PersistentIndexCount
objCatAdm
Required. The CatAdm object that manages the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.QueryCount

The QueryCount property is the number of active queries for this catalog. This property is read-only.

Syntax

objCatAdm.QueryCount
objCatAdm
Required. The CatAdm object managing the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.RemoveScope

The RemoveScope method removes an existing scope from the collection of scope objects managed by a CatAdm object.

Syntax

objCatAdm.RemoveScope(strScopePath)
objCatAdm
The CatAdm object managing the collection of scopes within the current catalog.
strScopePath
Required. String. The existing scope to remove.

Remarks

This method does not validate the path of the scope. Attempting to remove the path of a nonexistent scope results in the creation of an error object with the Number property set to ERROR_NOT_FOUND.

Example

' Remove the scope "c:\sources"
objCatAdm.RemoveScope("c:\sources")

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.

See Also

AddScope


CatAdm.StartCatalog

The StartCatalog method starts the catalog and returns its previous state.

Syntax

lngState = objCatAdm.StartCatalog( )
lngState
Long. A numeric value that indicates the previous state of the catalog. Can be any of the values associated with the CICAT* Constants.
objCatAdm
Required. The CatAdm object that manages the scopes for this catalog.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.StateInfo

The StateInfo property represents one or more values from the CI_STATE_* Constants and indicates various activities or states of Indexing Service. This property is read-only.

Syntax

objCatAdm.StateInfo
objCatAdm
Required. The CatAdm object managing the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.StopCatalog

The StopCatalog method stops the catalog and returns its previous state.

Syntax

lngState = objCatAdm.StopCatalog( )
lngState
Long. A numeric value that indicates the previous state of the catalog. Can be any of the values associated with the CICAT* Constants.
objCatAdm
Required. The CatAdm object that manages the scopes for this catalog.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.TotalDocumentCount

The TotalDocumentCount property is the number of items in the set of documents to be indexed. This property is read-only.

Syntax

objCatAdm.TotalDocumentCount
objCatAdm
Required. The CatAdm object that manages the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.UniqueKeyCount

The UniqueKeyCount property is the number of unique keys since indexing started. This property is read-only.

Syntax

objCatAdm.UniqueKeyCount
objCatAdm
Required. The CatAdm object that manages the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


CatAdm.WordListCount

The WordListCount property is the number of word lists that currently exist in memory. This property is read-only.

Syntax

objCatAdm.WordListCount
objCatAdm
Required. The CatAdm object that manages the collection of scopes within this catalog.

Remarks

Retrieving this property requires Indexing Service to be running. If it is not running, an error object is created with the Number property set to CI_E_NOT_RUNNING.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


ScopeAdm

The ScopeAdm scope administration object manages a scope definition for a catalog within Indexing Service. Use scope objects to force rescans and modify logon information for remote scopes. A scope defines a path to a local, remote, or virtual directory. You can create scope objects through the AddScope, GetScopeByPath, or GetScopeByAlias methods on the CatAdm object.

Property names | Type | Access | Description
Alias | STR | R/W | Friendly name for the scope object.
ExcludeScope | VARIANT_BOOL | R/W | TRUE disables indexing for this scope.
Logon | STR | R/O | Logon name.
Path | STR | R/W | Case-insensitive path.
VirtualScope | VARIANT_BOOL | R/O | TRUE if this scope refers to a virtual root.

Method names | Description
Rescan | Full or incremental rescan trigger.
SetLogonInfo | Sets name, password pair.

Remarks

Scope objects can be created only through the defined methods of the CatAdm object.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


ScopeAdm.Alias

The Alias property is the case-insensitive name of the alias or friendly name for this scope. This property is read/write.

Syntax

objScopeAdm.Alias
objScopeAdm
Required. The ScopeAdm object.

Example

objScopeAdm.Alias = "\\Server1\CodeSources"

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


ScopeAdm.ExcludeScope

The ExcludeScope property determines whether to index this scope. If TRUE, indexing is disabled for this scope. If FALSE, indexing is enabled for this scope. This property is read/write.

Syntax

objScopeAdm.ExcludeScope
objScopeAdm
Required. The ScopeAdm object.

Example

objScopeIS.ExcludeScope = TRUE

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


ScopeAdm.Logon

The Logon property contains the case-insensitive logon name. This property is read/write.

Syntax

objScopeAdm.Logon
objScopeAdm
Required. The ScopeAdm object.

Example

strLogonName = objScopeAdm.Logon

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


ScopeAdm.Path

The Path property is the case-insensitive scope path to the directory for Indexing Service to index.

Syntax

objScopeAdm.Path
objScopeAdm
Required. The ScopeAdm object.

Example

objScopeIS.Path = "c:\"

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


ScopeAdm.Rescan

The Rescan method initiates the scanning process.

Syntax

objScopeAdm.Rescan(blnFull)
objScopeAdm
Required. The scope object.
blnFull
Required. VARIANT_BOOL. If TRUE, this is a full scan of the scope. If FALSE, this is an incremental scan of the scope.

Remarks

This method assumes that Indexing Service is already running. It initiates the scanning process and returns control to the caller.

Example

' Initiate an incremental scan on this scope
objScopeAdm.Rescan(FALSE)

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


ScopeAdm.SetLogonInfo

The SetLogonInfo method sets the logon password pair for establishing credentials for scopes with universal naming convention (UNC) paths.

Syntax

objScopeAdm.SetLogonInfo(strLogon, strPassword)
objScopeAdm
Required. The scope object.
strLogon
Required. String. The logon name used to log on to the scope's UNC path.
strPassword
Required. String. The logon password, which must be a valid string. A null password is represented by a null string.

Remarks

Any failures cause an error object to be created.

Example

' Set the logon info for this scope
objScopeAdm.SetLogonInfo("LogonName","LogonPassword")

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


ScopeAdm.VirtualScope

The VirtualScope property indicates whether this scope is a virtual path. If TRUE, the scope is virtual. This property is read-only.

Syntax

objScopeAdm.VirtualScope
objScopeAdm
Required. The ScopeAdm object.

Example

Dim blnIsScopeVirtual As Boolean
blnIsScopeVirtual = objScopeAdm.VirtualScope

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ciodm.dll.


Query

The Query object of Indexing Service supports methods and properties that allow you to formulate a query and define an ActiveX® Data Objects (ADO) recordset to manage and display the results of the query.

The programmatic identifier (ProgID) in the registry under the HKLM/Software/Classes path for the query object in ixsso.exe is the literal value IXSSO.Query.2. The version-independent ProgID is IXSSO.Query.

Property names | Type | Access | Description
AllowEnumeration | VARIANT_BOOL | R/W | TRUE indicates that enumeration is allowed.
Catalog | STR | R/W | The index catalog name.
CiFlags | STR | R/W | Indexing Service flags. This is a deprecated property. Use Utility.AddScopeToQuery instead.
CiScope | STR | R/W | The catalog path. This is a deprecated property. Use Utility.AddScopeToQuery instead.
CodePage | LONG | R/W | The character set code page.
Columns | STR | R/W | List of columns available for OLE DB recordset retrieval for query results.
Dialect | STR | R/W | Query language version.
GroupBy | STR | R/W | Choice for grouping.
LocaleID | LONG | R/W | Language locale ID (LCID) to use when executing query.
MaxRecords | LONG | R/W* R/O | Maximum number of records to retrieve. Read/write when recordset is closed and read-only when it is open.
OptimizeFor | STR | R/W | Controls whether queries are optimized for better performance or for a greater number of hits.
OutOfDate | VARIANT_BOOL | R/O | TRUE if content index is out of date.
Query | STR | R/W | Query string, also known as restriction.
QueryIncomplete | VARIANT_BOOL | R/O | TRUE if query could not be resolved using the Content Index and if the AllowEnumeration property was FALSE.
QueryTimedOut | VARIANT_BOOL | R/O | TRUE if query exceeded time limit for execution.
ResourceUseFactor | LONG | R/W | Reserved for Internal Use.
SortBy | STR | R/W | Choice for sorting.
StartHit | VARIANT | R/W | Reserved for internal use.

Method names | Description
CreateRecordset | Execute the query, creating an OLE DB results table or an ADO recordset.
DefineColumn | Defines a column to be used in the query.
OnStartPage | For internal use only.
QueryToURL | Creates the query string portion of a URL from the the internal state of the query properties.
Reset | Clears the state of the query object.
SetQueryFromURL | Sets Query and other properties from the query string.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.AllowEnumeration

The AllowEnumeration property indicates whether the query engine can use enumeration queries to resolve the result set. This property is used when resolving a query for properties that involve recursively searching directories for property information.

Syntax

objQuery.AllowEnumeration = [ fAllowEnum ]
fAllowEnum
VARIANT_BOOL. When set to TRUE, allows queries to use enumeration to resolve the result set. Otherwise, queries are forced to use indexes only for resolution. The default value is FALSE.
objQuery
Required. The Query object.

Remarks

This property expresses the inverse of the .idq parameter CiForceUseCI. For Web clients, the query string variable in URLs associated with this property is ae.

Example

objQuery.AllowEnumeration = TRUE

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.Catalog

The Catalog property is the catalog name on a local computer; for example, Web or System.

Syntax

objQuery.Catalog = [ strCatalog ]
strCatalog
String. The catalog name can be the name of a directory on the local computer. You can specify more than one catalog name by separating each name with a comma.

The catalog name uses URL-like syntax in the following format.

query://hostname/indexname

The hostname is the name of the computer where the catalog can be found. The indexname gives the catalog name on that computer. The hostname defaults to the local computer if not supplied. The indexname defaults to the default catalog on the computer if not supplied.

objQuery
Required. The Query object.

Remarks

If no name is supplied, Indexing Service uses the default catalog on the computer. If Internet Information Services (IIS) is installed, the default catalog name is Web. The catalog name for Windows® 2000 is System. For Web clients, the query string variable in URLs associated with this property is ct.

Example

objQuery.Catalog = "query://search.microsoft.com/kb"

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.CiFlags

The CiFlags property represents the Indexing Service flags that control whether the queries are resolved by searching recursively through the scope hierarchy or through only the scope directory itself. This property is for internal use only and is used in conjunction with CiScope.

This is a deprecated property. Use Utility.AddScopeToQuery instead.

Syntax

objQuery.CiFlags = [ strFlags ]
strFlags
String. "DEEP" | "SHALLOW". "DEEP" indicates to Indexing Service that it needs to use the directory given in CiScope and recursively search through all directories within it. "SHALLOW" means search only the directory specified in CiScope.
objQuery
The query object.

Remarks

The CiFlags and CiScope properties are used primarily for debugging and are always used together. Use the AddScopeToQuery method to add this restriction to the query object.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.CiScope

The CiScope property specifies where to search to resolve the query defined in Query. Scope contains the starting directory or list of directories as physical or virtual path names.

This is a deprecated property. Use Utility.AddScopeToQuery instead.

Syntax

objQuery.CiScope = [ strScope ]
strScope
String. Separate a list of scopes with a comma (,). The scope / (forward slash) matches every page in all virtual directories and the scope \ (backslash) matches every page on every physical directory. To use CiScope in a URL with a query expression, see HTML Extension Files.
objQuery
The query object.

Remarks

Use CiFlags to indicate the type of searching to perform, whether deep or shallow. Use the AddScopeToQuery method to add this restriction and CiScope on the query object.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.CodePage

The CodePage property contains the code page to use for this query.

Syntax

lCodePage = objQuery.CodePage
lCodePage
Long. The code page identifier.
objQuery
The query object.

Remarks

A code page is a set of typographical characters used to represent text, which can differ by language or locale. Code pages are designated by numbers such as ANSI code page 1252 for American English and OEM code page 932 for Japanese Kanji. Code pages are used to parse the query string and other strings such as column names, and to convert back and forth between URL sequences and query strings in the SetQueryFromURL and QueryToURL methods.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.Columns

The Columns property contains the list of case-insensitive column names used in formatting the query result set.

Syntax

objQuery.Columns = [ strColumns ]
strColumns
String. The list of column names separated by commas.
objQuery
The query object.

Remarks

This property gives a list of column names, each separated by commas. The column names can be enclosed in quotation marks if they contain characters other than alphabetic and numeric characters.

Example

objQuery.Columns = "DocAuthor, vpath, doctitle"

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.

See Also

DefineColumn, GroupBy, SortBy


Query.CreateRecordset

The CreateRecordset method executes a query and creates an ADO recordset to navigate through query results.

Syntax

Set objRecordset = objQuery.CreateRecordset(strCursorType)
objRecordset
The ADO recordset object for iterating the results of a query.
strCursorType
Required. String. Either "sequential" or "nonsequential" to create an IRowset (sequential) or an IRowsetScroll (nonsequential) recordset.
objQuery
The query object.

Remarks

Before calling CreateRecordset, you must set any required parameters for a query, such as the Query property and the Columns property.

Example

' Create a sequential recordset
objQuery.Query = "$contents " & chr(34) & SrchStr & chr(34)"
objQuery.Columns = "DocTitle, VPath, Characterization, HitCount"
Set objRecordset = objQuery.CreateRecordset("sequential")

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.DefineColumn

The DefineColumn method defines a new friendly name for a column to be included in queries. By defining an alias for an existing property, you create a shorthand term to refer to it.

Syntax

objQuery.DefineColumn(strColumnDef)
objQuery
The query object.
strColumnDef
Required. String. Defines the column. The syntax of the column definition string is:

fname [ ( type ) ] = propset-id [ prop-id | " prop-name " ]

fname
The friendly name given to the property.
type
Optional. DBTYPE of the column (used in query restrictions).
propset-id
Globally unique identifier (GUID) of the property set ID for the column.
prop-id
Numeric ID of the property ID for the column.
prop-name
The property name for the column.

Remarks

The fname can mask some previously defined or predefined column name. Also, DefineColumn can define an alternative friendly name (an alias) for some existing column.

If the DefaultColumnFile registry value is set, the file named in the setting is read for a set of column definitions available for every query. Otherwise, the column names in List of Property Names become the default column settings.

Example

strNewColumn = """dc.source.type.category""(dbtype_wstr|dbtype_byref) = CF2EAF90-9311-11CF-BF8C-0020AFE50508 dc.source.type.category"
objQuery.DefineColumn(strNewColumn)
objQuery.Columns = "path, ""dc.source.type.category"""

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.Dialect

The Dialect property specifies the dialect of the Indexing Service Query Language being used in the Query property for this query.

Syntax

strDialect = objQuery.Dialect
strDialect
String. The literal value "1" indicates Indexing Service Query Language Dialect 1, and "2" refers to Indexing Service Query Language Dialect 2 (default value).
objQuery
The query object.

Remarks

For Web clients, the query string variable in URLs associated with this property is di. Scripts written with the previous version of the Query object may behave differently due to the change in dialect.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.GroupBy

The GroupBy property groups search results by value within a column. For example, searches could group, in the result table, all documents written by one author.

Syntax

objQuery.GroupBy = [ strGroupingTerm ]
strGroupingTerm
String. A grouping specification made up of a type (currently only [unique] is supported), a property name, and a sort order ([a] for ascending or [d] for descending). In unique grouping, unique values of the column set form the individual categories.

The syntax for the unique grouping term is:

unique fname [ {[a]|[d]} ] [ , fname2 {[a]|[d]} ... ]

where fname, or fname2, is the friendly name assigned by the Query.DefineColumn method.

Because the initial default value for a type is also unique, you can omit this term. Column names separated by a comma (,) are grouped together into subgroups of the previous grouping.

objQuery
The query object.

Remarks

For Web clients, the query string variables in URLs associated with this property are gr (group) and gd (group in descending order).

Example

' Organize all the document hits with the same author
'   together alphabetically by author
objQuery.GroupBy = "[unique] DocAuthor"

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.LocaleID

The LocaleID property is the unique locale identifier (LCID) that specifies a language identifier to use for this query. Convert between language identifiers (strings) and LCIDs (constants) by using the ISOToLocaleID and LocaleIDToISO methods on the utility object.

Syntax

lLcid = objQuery.LocaleID
lLcid
Long (LCID). The locale identifier.
objQuery
The query object.

Remarks

The value is a Microsoft Win32® LCID. This locale identifies the language to use to perform a query on existing indexes.

For Web clients requesting an Active Server Pages (ASP), browsers send an HTTP header — HTTP_ACCEPT_LANGUAGE — that specifies the locale to use in a query. This can be overridden with this LocaleID property. The U.S. English locale is 1033 (equivalent to the language code "en-us").

For Web clients using the ISAPI .idq files to define queries, assign the locale identifier string to CiLocale in the [Query] section of the query.idq file to override browser settings. See Valid Locale Identifiers for a list of language identifiers recognized by Indexing Services.

Otherwise the system default LCID is used

Example

objQuery.LocaleID = 1033 ' EN-US locale code

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.MaxRecords

The MaxRecords property defines the maximum number of records (rows) to use in the query result set, which is an ADO Rowset object.

Syntax

lMaxHits = objQuery.MaxRecords
lMaxHits
Long. The maximum number of hits to allow for in the query result set.
objQuery
The query object.

Remarks

This property limits the number of records in the Rowset object the Indexing Service OLE DB provider retrieves from its data source object, which is the group of indexes defined by the current catalog. The default setting of zero requests all records. MaxRecords is read/write when the recordset is closed and read-only when it is open.

For Web clients, the query string variables in URLs associated with this property is mh (MaxHits).

Example

lngRecs = objQuery.MaxRecords

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.OnStartPage

The OnStartPage method for the query object is a standard method for all classes called by the Server object after it creates an instance of the object in an Active Server Pages (ASP) script. This happens before the server processes the script. This method is for Web clients.

Syntax

This method should not be called directly.

Example

' VBScript in an ASP page
<% Set objQuery = Server.CreateObject("IXSSO.Query") %>
' Here the OnStartPage method is invoked automatically by the ASP scripting context


Query.OptimizeFor

The OptimizeFor property controls whether queries are optimized for better performance or for a greater number of hits.

Syntax

strOptimizeFor = objQuery.OptimizeFor
strOptimizeFor
String. This string has the following syntax:

"performance" | "recall" [, "hitcount" | "nohitcount" ]

where the parts are defined as follows:

"performance" | "recall"
Default is "recall". If "performance", Indexing Service first collects the maximum number of hits and then eliminates hits that don't meet the scope or security requirements.

Note Optimizing for performance may result in less than the expected number of hits for queries in which scope checks or security checks remove hits.

If "recall", Indexing Service trims the result set as it finds the hits of matches that don't meet the scope or security requirements.

"hitcount" | "nohitcount"
Defaults to "nohitcount". It controls whether or not to request the Hitcount property, which represents the total number of hits matching the query, from the ADO query property collection. This property is a custom property supported by the OLE DB provider, accessed through the query object property set.

The "hitcount" and "nohitcount" options are not implemented for Indexing Service in Windows 2000. It is used exclusively by the Microsoft SiteServer Indexing Service implementation.

objQuery
The query object.

Remarks

If you choose the performance option, scope and security trimming are deferred until after the maximum number of hits is collected. If the option is set to recall, the result set trimming occurs while executing the query. The default is to optimize for recall.

For Web clients, the query string variable URLs associated with this property is op.

In former releases of Indexing Service, this property replaces the .idq parameter CiDeferNonIndexedTrimming.

Example

' Optimize for the fastest performance
objQuery.OptimizeFor = "performance,nohitcount"

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.OutofDate

The OutofDate property is a flag that warns when the content index is no longer current. This property is read-only.

Syntax

fFlag = objQuery.OutofDate
fFlag
VARIANT_BOOL. TRUE if the content index is out of date, otherwise FALSE.
objQuery
The query object.

Remarks

You must call the CreateRecordSet method before using this property. The OutofDate property value comes from detecting how many documents remain to be indexed for a catalog. Because different operating systems support different notification systems, this value is only as accurate as is allowed by the change notification system or by the interval between directory scans.

Documents that are temporarily inaccessible to the filtering process because of sharing violations or other reasons are placed on a separate queue for later retry and can prevent the count of files to index from decreasing to zero. Use the GetLongProperty or SetLongProperty for the DelayedFilterRetries registry value to adjust this value for such a situation.

Example

If (objQuery.OutofDate = TRUE) Then
    ' Report this condition.
End if

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.Query

The Query property is the query string, also known as the restriction or query restriction.

Syntax

objQuery.Query = [ strRestriction ]
strRestriction
String. The query string itself.
objQuery
The query object.

Remarks

The combination of words or phrases or properties to search for that determines the documents to be returned in a search For Web clients, the query string variable in URLs associated with this property is qu.

The Dialect property defines the version of query language contained in the Query property. The LocaleID determines the language components (English (US), Japanese, French, and any one of the other supported languages) to use to break the query string into words, to remove noise words, and to create the appropriate stemming variations of the words in the query string.

Example

' Search for the word "dog" near the word "cat" in .htm files
objQuery.Query = "#filename *.htm and dog near cat"

See Also

Query Languages for Indexing Service

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.QueryIncomplete

The QueryIncomplete property is a flag that warns when the Indexing Service could not resolve the query because of a very complicated regular expression query, or some prefix query that matched too many terms in an index. This property is read-only.

Syntax

fFlag = objQuery.QueryIncomplete
fFlag
VARIANT_BOOL. TRUE if the query could not be resolved using the Content Index and if the AllowEnumeration property was FALSE; FALSE otherwise.
objQuery
The query object.

Remarks

A query can be incomplete when it becomes too complex or expands to an unreasonable number of query restriction nodes. This can happen for a variety of reasons. You must call the CreateRecordSet method before using this property.

.

Example

If (objQuery.QueryIncomplete = TRUE) Then
   ' Report this condition.
End if

See Also

MaxRestrictionNodes

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.QueryTimedOut

The QueryTimedOut property is a flag that warns that Indexing Service exceeded the time limit for execution as specified by the MaxQueryExecutionTime set by administrators for Indexing Service. This property is read-only.

Syntax

fFlag = objQuery.QueryTimedOut
fFlag
VARIANT_BOOL. TRUE if the query timed out before it finished processing, FALSE otherwise.
objQuery
The query object.

Remarks

You must call the CreateRecordSet method before using this property.

Example

If (objQuery.QueryTimedOut = TRUE) Then
   ' Report this condition.
End if

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.QueryToURL

The QueryToUrl method reads the properties of the query object and creates and creates the QueryString portion of a uniform resource locator (URL) string from their values. The converse of this method is SetQueryFromURL. The SetQueryFromURL method converts a query string to settings of the query object properties.

Syntax

strQueryString = objQuery.QueryToURL( )
strQueryString
String. The Common Gateway Interface (CGI) QueryString, which uses certain combinations of character escape sequences for unprintable characters to be used in a URL (for example, "Now" would be %22Now%22).
objQuery
The query object.

Remarks

Properties read from the query object include Catalog, SortBy, GroupBy, Query, MaxRecords, and AllowEnumeration.

Example

' Take the current property settings on the query object for
'   Q.Query = "Change Notification"
'   Q.SortBy = "rank[d]"
'   Q.Dialect = "1"
'   create an URL version
Dim strURL As String
strURL = Q.QueryToURL( )
Debug.Print "URL Version = " + strURL
' Output is:
'   URL Version = di=1&so=Rank%5Bd%%5D&qu=Change+Notification

See Also

SetQueryFromURL

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.Reset

The Reset method resets the state of the query object.

Syntax

objQuery.Reset( )
objQuery
The query object.

Remarks

This method clears any internal state on the query object. This method is useful when reusing a query object from a previous query.

Example

objQuery.Reset

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.ResourceUseFactor

Reserved for internal use.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.SetQueryFromURL

The SetQueryFromURL method sets the properties on the query object of a Web client request. The converse of this method is QueryToURL.

Syntax

objQuery.SetQueryFromURL(strQueryString)
objQuery
The query object.
strQueryString
Required. String. The CGI QueryString that is URL-encoded. See QUERY_STRING Variables

Remarks

The state of the query object is not reset before loading the query string values. Unrecognized tag names in the query string are ignored.

Query string and form variables can also be parsed from a script without calling this method.

Example

' Take the URL query string that specifies files > 10,000,
'     sort order by rank in descending alphabetical order,
'     and the maximum hit count = 200
' Set the corresponding query object properties
objQuery.SetQueryFromURL("qu=%40size+%3E+10000&so=rank%5bd%5d&mh=200")
' results are:
' objQuery.Query = "@size > 10,000"
' objQuery.SortBy = "rank[d]"
' objQuery.MaxRecords = 200

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.

See Also

QueryToURL, Reset


Query.SortBy

The SortBy property indicates how to sort the result set of a query, by listing column names and sorting order.

Syntax

objQuery.SortBy = [ strSortString ]
strSortString
One or more existing result set column names separated by commas. Each column name can be followed by an optional sort order identifier: [a] for ascending and [d] for descending order. The column names must already exist in the ADO recordset object.
objQuery
The query object.

Remarks

This property sorts results in ascending order ( [a] ) by default. The query string variables associated with this property are so (sort order) and sd (sort descending).

Example

objQuery.SortBy = "DocAuthor, rank[d]"

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Query.StartHit

The StartHit property is not implemented for Indexing Service in Windows 2000. It is used exclusively by the Microsoft SiteServer Indexing Service implementation.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Utility

The Indexing Service Utility object is an ActiveX server-side control that is an automation object with a dual interface supporting IDispatch. The methods supported by this object give script writers utility routines for use with the Query object.

The programmatic identifier (ProgID) for the Utility object in ixsso.exe is IXSSO.Util.2. The version-independent ProgID is IXSSO.Util.

Methods | Description
AddScopeToQuery | Add a new scope restriction to a query.
GetArrayElement | Access a safe-array vector element.
HTMLEncode | Encode a string using HTML encoding using a given code page.
ISOToLocaleID | Convert a language code to a Win32 locale identifier (LCID).
LocaleIDToISO | Convert a Win32 LCID into a language code.
TruncateToWhitespace | Truncate a string at a white-space character.
URLEncode | Encode a string using URL encoding using a given code page.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Utility.AddScopeToQuery

The AddScopeToQuery method adds a search path to the Query property of the Query object.

Do not confuse this with ScopeAdm, which is the Indexing Service administration object that defines the paths to index.

Syntax

objUtility.AddScopeToQuery(objQuery, strPath[,strDepth])
objUtility
The utility object.
objQuery
Required. The Query object using this scope.
strPath
Required. String. The physical or virtual path of the scope to add.
strDepth
Optional. String. Case-insensitive. Whether the scope covers only the named directory ("shallow") or the named directory and all its subdirectories ("deep").

Remarks

When you first create an instance of the Query object or when you reset it, Query defaults to the entire catalog. The first time you call AddScopeToQuery, the specified scope replaces the default value. Subsequent calls to AddScopeToQuery append the additional scopes to a collection of scopes.

Example

' Replace default value with a specific scope.
objUtility.AddScopeToQuery objQuery, "/sources", "deep"

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Utility.GetArrayElement

The GetArrayElement method accesses a variant array element.

Syntax

varResult = objUtil.GetArrayElement(varArray, lngElem)
varResult
VARIANT. Contains the iElem element of varArray.
objUtil
The utility object.
varArray
VARIANT. Required. An array containing a singly dimensioned safe array.
lngElem
Long. Required. Identifies the array element to return.

Remarks

If varArray is not a safe array, or lElem is either less than the lower limit of varArray or more than its upper limit, the type of varResult returned is VT_EMPTY. This method exists due to restrictions in Visual Basic Scripting Edition (VBScript).

Example

Request.Write (objUtil.GetArrayElement( RS("vector-col"), i))

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Utility.HTMLEncode

The HTMLEncode method applies HTML encoding rules to a specified string using characters from a given code page.

Syntax

strHTML = objUtility.HTMLEncode(strString, lngCodePage)
strHTML
String.
objUtility
The utility object.
strString
String. Required. The string to encode.
lngCodePage
Long. Required. The code page to use for encoding this string.

Remarks

The HTMLEncode method is used to work around difficulties with the proper handling of code pages in previous versions of Active Server Pages (ASP).

Example

<%= Utility.HTMLEncode("The paragraph tag: <P>") %>
produces
The paragraph tag: &lt;P&gt;
which would display on a Web browser as
The paragraph tag: <P>

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.

See Also

URLEncode


Utility.ISOToLocaleID

The ISOToLocaleID method converts an ISO 639 language code into a Win32 locale identifier (LCID). Use LocaleIDToISO for the converse operation.

Syntax

lLocaleID = objUtility.ISOToLocaleID(strLocale)
lLocaleID
Long. The LCID. If there is no matching language code, 1 is returned.
objUtility
The utility object.
strLocale
String. Required. The language code. In addition to the ISO language codes, the name "neutral" can be used.

Remarks

The first recognized language code found in strLocale is converted to a Win32 LCID. The recognized language codes include all those from the ISO 639 standard that map to Win32 language IDs and some country codes that have sublanguage codes in Win32. If a language code is recognized, but the country code is not, the language code alone is used, unless there is a better match later in the string.

Example

Lcid = objUtility.ISOToLocaleID( Request.QueryString("HTTP_ACCEPT_LANGUAGE"))

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Utility.LocaleIDToISO

The LocaleIDToISO method converts a Win32 locale identifier (LCID) into an ISO 639 language code. Use ISOToLocaleID for the converse operation.

Syntax

strLocaleID = objUtility.LocaleIDToISO(lngLcid)
strLocaleID
String. The language code. In addition to the ISO language codes, the name neutral can be used.
objUtility
The utility object.
lngLcid
Long. Required. The LCID to translate.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.

See Also

Locale identifiers (LCIDs) under the Base Services documentation for the Platform SDK.


Utility.TruncateToWhitespace

The TruncateToWhitespace method truncates a string at a white-space character. Script writers can call this method to display short forms of the value of long properties like the contents of the Description property without truncating in the middle of a word.

Syntax

strTruncStr = objUtility.TruncateToWhitespace(strString, lngMaxLength)
strTruncStr
String. The truncated string.
objUtility
The query object.
strString
String. Required. The string to truncate.
lngMaxLength
Long. Required. The maximum length of the string.

Remarks

The space checking of this method doesn't work well with NLS; however it works well in ANSI. There is no equivalent routine for Asian languages.

Example

Response.Write objUtility.TruncateToWhitespace( RS("Characterization"),200)

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.


Utility.URLEncode

The URLEncode method applies URL encoding rules, including escape characters, to a given string using a specific code page.

Syntax

strURLStr = objUtility.URLEncode(strString, lCodePage)
strURLStr
String. The resulting URL encoded string.
objUtility
The utility object.
strString
String. Required. The string to encode.
lCodePage
Long. Required. The code page to use for encoding this string.

Remarks

The URLEncode method is used to work around difficulties with the proper handling of code pages in previous versions of Active Server Pages (ASP).

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Import Library: Included as a resource in ixsso.dll.

See Also

HTMLEncode


Interfaces

Indexing Service provides a Component Object Model (COM) interface to facilitate implementation of format-dependent document filtering. It includes the following interface.

  • IFilter


IFilter

The IFilter interface scans documents for text and properties (sometimes called attributes). It extracts chunks of text from these documents, filtering out embedded formatting and retaining positional information. It also extracts chunks of values, which are properties of an entire document or of well-defined parts of a document. IFilter provides the foundation for building higher-level applications such as document indexers and application-independent viewers.

For introductory information about how the IFilter interface treats documents and their properties, see Properties of Documents. In particular, for a synopsis and example of how the IFilter interface processes a document, see Property Filtering and Property Indexing.

When to Implement

Implement this interface if you are providing a filter to extract information from a proprietary file format so that the text and properties can be indexed. For information about constructing your IFilter implementation, see Constructing Filters. For information about registering your dynamic-link library (DLL) so that it will be called by Indexing Service for the associated file class, see Applying Filters. For information about testing your IFilter implementation, see Testing Filters.

When to Use

Full-text search engines like Indexing Service call the methods of this interface to extract text and property information for indexing. Text viewers can also use this interface after a query, for example, to show the hit highlights of the file that matched terms in a query string.

Indexing Service supplies three functions that it uses to access registered IFilter implementations. These functions are especially useful when loading and binding to an embedded object's IFilter implementation: LoadIFilter, BindIFilterFromStorage, and BindIFilterFromStream.

Methods in Vtable Order

IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IFilter methods | Description
Init | Initializes a filtering session.
GetChunk | Positions filter at beginning of first or next chunk and returns a descriptor.
GetText | Retrieves text from the current chunk.
GetValue | Retrieves values from the current chunk.
BindRegion | Retrieves an interface representing the specified portion of object. Currently reserved for future use.

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.
Import Library: User-defined.

See Also

Applying Filters, BindIFilterFromStorage, BindIFilterFromStream, CHUNK_BREAKTYPE, CHUNKSTATE, Constructing Filters, FILTERREGION, FULLPROPSPEC, IFILTER_FLAGS, IFILTER_INIT, LoadIFilter, PROPVARIANT, STAT_CHUNK, Testing Filters


IFilter::BindRegion

The IFilter::BindRegion method retrieves an interface representing the specified portion of the object. Currently reserved for future use.

SCODE BindRegion(
  FILTERREGION origPos,
  REFIID riid,
  void ** ppunk
);

Parameters

origPos
[in] Specifies a FILTERREGION structure that contains the position of the text.
riid
[in] Reference to requested interface ID.
ppunk
[out] Pointer to an output variable that receives the interface pointer requested in riid. Upon successful return, *ppunk contains the requested interface pointer.

Return Values

S_OK
Successful completion.
E_NOTIMPL
Currently not implemented.
FILTER_W_REGION_CLIPPED
The filter couldn't bind the entire region.

Remarks

If it is impossible for the BindRegion method to bind an interface to the specified region, return FILTER_W_REGION_CLIPPED. This situation can occur when the next such chunk is in a linked object or an embedded object.

Not all filters are capable of supporting the IFilter::BindRegion method in a rational way. Filters that are implemented by viewing applications will benefit the most from this method. The method is intended to be a way to pass cookies through the search engine and back to the IFilter interface implementation.

Notes to Implementers

This method is currently reserved for future use. Always return E_NOTIMPL.

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.
Import Library: User-defined.

See Also

FILTERREGION, IFilter


IFilter::GetChunk

The IFilter::GetChunk method positions the filter at the beginning of the next chunk, or at the first chunk if this is the first call to the GetChunk method, and returns a description of the current chunk.

SCODE GetChunk(
  STAT_CHUNK * pStat
);

Parameters

pStat
[out] Pointer to a STAT_CHUNK structure containing a description of the current chunk.

Return Values

S_OK
Successful completion.
FILTER_E_END_OF_CHUNKS.
The previous chunk is the last chunk.
FILTER_E_EMBEDDING_UNAVAILABLE.
The next chunk is an embedding and no content filter is available.
FILTER_E_LINK_UNAVAILABLE
The next chunk is a link and no content filter is available.
FILTER_E_PASSWORD
Password or other security-related access failure.
FILTER_E_ACCESS
General access failure.

Remarks

If upon return pStat points to a STAT_CHUNK structure with the breakType member equal to CHUNK_NO_BREAK, only the idChunk member will be updated with the new chunk identifier (ID) value. The other members of the STAT_CHUNK structure remain unchanged.

Internal value-type properties (chunks with a CHUNKSTATE enumeration value of CHUNK_VALUE) cannot be concatenated using CHUNK_NO_BREAK. A single word cannot span more than two glued chunks.

Chunk ID zero is invalid.

Before the GetChunk method is called for the first time, there is no current chunk. After an error return code of anything other than FILTER_E_END_OF_CHUNKS the next call to the GetChunk method nevertheless retrieves the next chunk after the unavailable one.

Notes to Callers

When the GetChunk method finishes, the chunk described in *pStat is the current chunk. The chunk descriptor is owned by the routine calling the GetChunk method, but the property name pointer, which can be set in the property specification, is owned by the GetChunk method and should not be freed.

Notes to Implementers

If a call to the GetChunk method of the content filter of a linked or embedded object returns FILTER_E_END_OF_CHUNKS, the implementation should return the next chunk of the linking or embedding object. For example, if a document has two embedded objects and the first has returned FILTER_E_END_OF_CHUNKS, then the outer content filter must call the GetChunk method of the content filter for the embedded object.

Before returning the results of a call to the GetChunk method on an embedded or linked object, check to make sure that the chunk ID is unique. If not, the implementer must renumber the chunk and keep a mapping of the new chunk ID.

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.
Import Library: User-defined.

See Also

IFilter, IFilter::GetText, IFilter::GetValue, CHUNKSTATE, CHUNK_BREAKTYPE, STAT_CHUNK


IFilter::GetText

The IFilter::GetText method retrieves text (text-type properties) from the current chunk, which must have a CHUNKSTATE enumeration value of CHUNK_TEXT.

SCODE GetText(
  ULONG * pcwcBuffer,
  WCHAR * awcBuffer
);

Parameters

pcwcBuffer
[in/out] On entry, the size of awcBuffer array in wide/Unicode characters. On exit, the number of Unicode characters written to awcBuffer. Note that this value is not the number of bytes in the buffer.
awcBuffer
[out] Text retrieved from the current chunk. Do not terminate the buffer with a character.

Return Values

S_OK
Successful completion.
FILTER_E_NO_TEXT
The flags member of the STAT_CHUNK structure for the current chunk does not have a value of CHUNK_TEXT.
FILTER_E_NO_MORE_TEXT
All the text in the current chunk has been returned. Additional calls to the GetText method should return this error until the IFilter::GetChunk method has been called successfully.
FILTER_S_LAST_TEXT
As an optimization, the last call that returns text can return FILTER_S_LAST_TEXT, indicating that the next call to the GetText method will return FILTER_E_NO_MORE_TEXT. This optimization can save time by eliminating unnecessary calls to GetText.

Remarks

If the current chunk is too large for the awcBuffer array, more than one call to the GetText method can be required to retrieve all the text in the current chunk. Each call to the GetText method retrieves text that immediately follows the text from the last call to the GetText method. The last character from one call can be in the middle of a word, and the first character in the next call would continue that word. Search engines must handle this situation.

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.
Import Library: User-defined.

See Also

CHUNKSTATE, IFilter, IFilter::GetValue, IFilter::GetChunk, STAT_CHUNK


IFilter::GetValue

The IFilter::GetValue method retrieves a value (internal value-type property) from a chunk, which must have a CHUNKSTATE enumeration value of CHUNK_VALUE.

SCODE GetValue(
  PROPVARIANT ** ppPropValue
);

Parameters

ppPropValue
[out] Pointer to an output variable that receives a pointer to the PROPVARIANT structure that contains the value-type property.

Return Values

S_OK
Successful completion.
FILTER_E_NO_MORE_VALUES
The GetValue method has already been called on this chunk; this value should be returned until the IFilter::GetChunk method has been called successfully and has advanced to the next chunk.
FILTER_E_NO_VALUES
The current chunk does not have a CHUNKSTATE enumeration value of CHUNK_VALUE.

Remarks

Call the GetValue method only once per chunk.

Note that the effect of producing the same value from more than one chunk is undefined. Only the last setting of the value is valid.

Notes to Callers

Allocate the PROPVARIANT structure with CoTaskMemAlloc. Some PROPVARIANT structures contain pointers, which can be freed by calling the PropVariantClear function. It is up to the caller of the GetValue method to call the PropVariantClear method.

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.
Import Library: User-defined.

See Also

CHUNKSTATE, CoTaskMemAlloc, IFilter, IFilter::GetChunk, IFilter::GetText, PROPVARIANT, PropVariantClear, STAT_CHUNK


IFilter::Init

The IFilter::Init method initializes a filtering session.

SCODE Init(
  ULONG grfFlags,
  ULONG cAttributes,
  FULLPROPSPEC const * aAttributes,
  ULONG * pdwFlags
);

Parameters

grfFlags
[in] Flag settings from the IFILTER_INIT enumeration for controlling text standardization, property output, embedding scope, and IFilter access patterns.
cAttributes
[in] The size of the attributes array. When nonzero, cAttributes takes precedence over attributes specified in grfFlags. If no attribute flags are specified and cAttributes is zero, the default is given by the PSGUID_STORAGE storage property set, which contains the date and time of the last write to the file, size, and so on; and by the PID_STG_CONTENTS 'contents' property, which maps to the main contents of the file. For more information about properties and property sets, see Property Sets.
aAttributes
[in] Array of pointers to FULLPROPSPEC structures for the requested properties. When cAttributes is nonzero, only the properties in aAttributes are returned.
pdwFlags
[out] Information about additional properties available to the caller; from the IFILTER_FLAGS enumeration.

Return Values

S_OK
Successful completion.
E_FAIL
File to filter was not previously loaded.
E_INVALIDARG
Count and contents of attributes do not agree.
FILTER_E_PASSWORD
Access has been denied because of password protection or similar security measures.
FILTER_E_ACCESS
General access failures.

Remarks

The IFilter::Init method sets the state of the filter object. The content filter positions at the beginning of the object and the object state is frozen until the object is released. You can pass the filter object the set of properties you would like returned by setting up their property set and property identifier (ID) descriptions in the aAttributes array. For more information, see Filtering File Properties.

Notes to Callers

Call the Init method before calling all other IFilter methods.

Notes to Implementers

Chunk IDs must remain consistent across multiple calls to the Init method with the same parameters.

For some implementations of the IFilter interface, detection of failure to access a document may not be possible (or may be computationally expensive) until the Init method has been called, or possibly even later.

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.
Import Library: User-defined.

See Also

Filtering File Properties, FULLPROPSPEC, IFilter, IFILTER_FLAGS, IFILTER_INIT, PSGUID_STORAGE


Functions

Indexing Service provides functions for finding and managing catalogs, determining the catalog file's path, for creating Microsoft® OLE DB Command objects to query catalogs using Query Languages for Indexing Service, and for filtering files.

The following tables list the functions in each category.

For finding and managing catalogs | Description
CIState | Queries the state of the selected catalog.
LocateCatalogs | Find the catalog that indexes a directory.
SetCatalogState | Set the catalog state for backup or other purposes.

For creating queries using OLE DB command objects | Description
CICreateCommand | Creates a Command object.
CIMakeICommand | Creates a Command object, specifying computers, catalogs, and scopes.
CIBuildQueryNode | Builds one node of a query restriction tree for a Command object.
CIBuildQueryTree | Builds a query restriction tree for a Command object.
CIRestrictionToFullTree | Convert a query restriction tree with columns, sort columns, and grouping columns to a DBCOMMANDTREE structure.
CITextToFullTree | Creates a full command tree using Query Language 1.
CITextToFullTreeEx | Creates a full command tree using the Query Language Dialect that you specify.
CITextToSelectTree | Creates a SELECT node for a DBCOMMANDTREE structure using Query Language Dialect 1.
CITextToSelectTreeEx | Creates a SELECT node for a DBCOMMANDTREE structure using the Query Language Dialect that you specify.

For filtering files | Description
LoadIFilter | Retrieves IFilter from path name for object.
BindIFilterFromStorage | Given the IStorage interface pointer, retrieves the appropriate IFilter.
BindIFilterFromStream | Given the IStream interface pointer, retrieves the appropriate IFilter.


BindIFilterFromStorage

The BindIFilterFromStorage function takes an IStorage interface pointer of a structured storage object and retrieves the IFilter interface pointer for that object in order to filter its text. This is especially useful when filtering the contents of a document and processing embedded OLE objects that are accessible through their IStorage interfaces.

STDAPI BindIFilterFromStorage(
  IStorage * pStg,
  IUnknown * pUnkOuter,
  void ** ppIUnk
);

Parameters

pStg
[in] Pointer to the IStorage interface to use to access the file.
pUnkOuter
[in] Pointer to the controlling IUnknown interface of the aggregate in which this storage object exists.
ppIUnk
[out] Pointer to an output variable that receives the IFilter interface pointer.

Return Values

S_OK
Successful completion.
E_ACCESSDENIED
The function was denied access to the path of the storage object.
E_HANDLE
The function encountered an invalid handle, probably due to a low-memory situation.
E_INVALIDARG
The function received an invalid parameter.
E_OUTOFMEMORY
The function did not have sufficient memory or other resources to complete the operation.
E_FAIL
The function encountered an unknown error.

Remarks

This function is not a full implementation of a COM persistent handler.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

BindIFilterFromStream, IFilter, IStorage, IUnknown, LoadIFilter


BindIFilterFromStream

The BindIFilterFromStream function takes an IStream interface pointer of a Structured Storage object and retrieves the IFilter interface pointer for that object in order to filter the text of that object. This is especially useful when filtering the contents of a document and processing embedded OLE objects accessible through their IStream interfaces.

STDAPI BindIFilterFromStream(
  IStream * pStm,
  IUnknown * pUnkOuter,
  void ** ppIUnk
);

Parameters

pStm
[in] Pointer to the IStream interface to use to access the file.
pUnkOuter
[in] Pointer to the controlling IUnknown interface of the aggregate in which this stream object exists.
ppIUnk
[out] Pointer to an output variable that receives the IFilter interface pointer.

Return Values

S_OK
Successful completion.
E_ACCESSDENIED
The function was denied access to the path of the storage object.
E_HANDLE
The function encountered an invalid handle, probably due to a low-memory situation.
E_INVALIDARG
The function received an invalid parameter.
E_OUTOFMEMORY
The function did not have sufficient memory or other resources to complete the operation.
E_FAIL
The function encountered an unknown error.

Remarks

This function is not a full implementation of a COM persistent handler.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

BindIFilterFromStorage, IFilter, IStream, IUnknown, LoadIFilter


CIBuildQueryNode

The CIBuildQueryNode function takes a simple query restriction and creates a DBCOMMANDTREE structure for a node.

STDAPI CIBuildQueryNode(
  WCHAR const * wcsProperty,
  DBCOMMANDOP dbOperator,
  PROPVARIANT const * pvarPropertyValue,
  DBCOMMANDTREE ** ppTree,
  ULONG cProperties,
  CIPROPERTYDEF const * pProperty,
  LCID LocaleID
);

Parameters

wcsProperty
[in] Pointer to a null-terminated string that specifies the friendly name for a property. The friendly name can be used in an Indexing Service query, column list, or sort order.
dbOperator
[in] Value of type DBCOMMANDOP that specifies the operation to be performed on the node.
pvarPropertyValue
[in] Pointer to the PROPVARIANT structure for the value to use for the wcsProperty parameter.
ppTree
[out] Pointer to an output variable that receives the pointer to the DBCOMMANDTREE structure for the node created by this function.
cProperties
[in] Count of the number of properties in the pProperty array.
pProperty
[in] Pointer to an array of CIPROPERTYDEF structures, each of which describes a property that can be referred to by a friendly name. This array is populated when pvarPropertyValue itself contains a string that contains references to properties. Can be NULL when cProperties equals zero.
LocaleID
[in] Locale ID used when converting properties. The pvarPropertyValue parameter itself contains a string that contains references to friendly property names, which are converted to uppercase for comparison and efficiency purposes.

Return Values

S_OK
Successful completion.
QPARSE_E_NO_SUCH_PROPERTY
The function failed because the property name specified by wcsProperty was not found.
E_HANDLE
The function encountered an invalid handle, probably due to a low-memory situation.
E_INVALIDARG
The function received an invalid parameter.
E_OUTOFMEMORY
The function did not have sufficient memory or other resources to complete the operation.
E_FAIL
The function encountered an unknown error.

Remarks

Use nodes created by the CIBuildQueryNode function to create or add to a query tree using the CIBuildQueryTree function. Content properties are in turn passed to the CITextToSelectTree function to create the SELECT part of the full tree.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

CIBuildQueryTree, CIPROPERTYDEF, CITextToSelectTree, CITextToSelectTreeEx, CITextToFullTree, CITextToFullTreeEx, Command Trees, DBCOMMANDOP, DBCOMMANDTREE


CIBuildQueryTree

The CIBuildQueryTree function adds a simple restriction node to a tree of DBCOMMANDTREE structures.

STDAPI CIBuildQueryTree(
  DBCOMMANDTREE const * pExistingTree
  DBCOMMANDOP dbBoolOp,
  ULONG cSiblings,
  DBCOMMANDTREE const * const * ppSibsToCombine,
  DBCOMMANDTREE ** ppTree
);

Parameters

pExistingTree
[in] Pointer to a DBCOMMANDTREE structure representing the tree. Can be NULL.
dbBoolOp
[in] Value of type DBCOMMANDOP that specifies the operation to be performed on the node.
cSiblings
[in] Count of the number of sibling nodes for this node.
ppSibsToCombine
[in] Pointer to the address that contains the array of DBCOMMANDTREE structures for the siblings to be combined with this node using the operation in dbBoolOp.
ppTree
[out] Address of the location to receive a pointer to the DBCOMMANDTREE structure for the tree structure.

Return Values

S_OK
Successful completion.
E_ACCESSDENIED
The function was denied access to the specified path.
E_HANDLE
The function encountered an invalid handle, probably due to a low-memory situation.
E_INVALIDARG
The number of operands (siblings) for the specified dbBoolOp is not correct.
E_OUTOFMEMORY
There was not enough memory to build the nodes of the tree.
E_FAIL
The function encountered an unknown error.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

CIBuildQueryNode, CITextToSelectTree, CITextToSelectTreeEx, CITextToFullTree, CITextToFullTreeEx, Command Trees, DBCOMMANDOP, DBCOMMANDTREE


CICreateCommand

The CICreateCommand function creates an OLE DB Command object, retrieves the ICommand interface pointer to it, and sets the catalog and machine properties for the object.

STDAPI CICreateCommand(
  IUnknown ** ppICommand,
  IUnknown * pUnkOuter,
  REFIID riid,
  WCHAR const * pwcsCatalog,
  WCHAR const * pwcsMachine
);

Parameters

ppICommand
[out] Pointer to an output variable that receives the IUnknown interface pointer requested in riid.
pUnkOuter
[in] Pointer to an optional outer IUnknown interface. Can be zero for no aggregation, in which case riid can contain a value other than IID_IUnknown.
riid
[in] Specifies the interface identifier (IID) of the interface returned in ppICommand. Must be IID_IUnknown unless pUnkOuter is NULL. Pass IID_ICommand to get an ICommand interface if aggregation isn't needed and pUnkOuter is NULL.
pwcsCatalog
[in] Pointer to a null-terminated string that specifies the name of the catalog used to execute queries. This is the value for the DBPROP_CI_CATALOG_NAME property of the ICommand interface.
pwcsMachine
[in] Pointer to a null-terminated string that specifies the name of the machine on which the query is executed. This is the value for the DBPROP_CI_MACHINE_NAME property of the ICommand interface. Use L"." for the local machine.

Return Values

S_OK
Successful completion.
CLASS_E_NOAGGREGATION
Aggregation exists (pUnkOuter is not NULL) and riid is not IID_IUnknown.
E_INVALIDARG
The function received an invalid pointer parameter.

Remarks

The CICreateCommand function simplifies the task of connecting to the Indexing Service content and property indexes as an OLE DB provider data source object (DSO) and creating a session object. Queries made with the resulting ICommand interface default to the scope "\" and search everywhere under that hierarchy (a "deep" search). To specify a scope, use CIMakeICommand.

If interface aggregation isn't required, pass IID_ICommand for riid and NULL for pUnkOuter. Otherwise, call IUnknown::QueryInterface on the returned object to get an ICommand interface.

The CICreateCommand function does not return an error if the catalog or machine do not exist or are not available. The connection to the catalog and machine are established when the ICommand::Execute method is called, and connection errors are returned at that time.

Additional catalog, machine, and scope parameters can be specified after an ICommand interface is created using the ICommandProperties interface.

Multiple queries can be executed using the ICommand interface returned by the CICreateCommand function, but only one query can exist at a time. Issuing multiple queries on a single ICommand interface is much more efficient than creating a new ICommand interface for each query.

Example

This example creates an ICommand interface for the system catalog on the local machine.

ICommand * pICommand;
HRESULT hr = CICreateCommand( (IUnknown **) &pICommand, 0, IID_ICommand, L"system", L"." );
if ( SUCCEEDED( hr ) )
{
    // ...
    // execute one or more queries with the ICommand
    // ...
    pICommand->Release();
}

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

CiMakeICommand, Command, Command Trees, ICommand, ICommand::Execute, ICommandProperties, IUnknown, IUnknown::QueryInterface


CIMakeICommand

The CIMakeICommand function creates an OLE DB Command object supporting the ICommand interface and sets the command's scope, catalogs, and machine name properties. To create a Command object using a default scope, use the CICreateCommand function.

STDAPI CIMakeICommand(
  ICommand ** ppCommand,
  ULONG       cScope,
  DWORD const * aDepths,
  WCHAR const * const * awcsScope,
  WCHAR const * const * awcsCatalogs,
  WCHAR const * const * awcsMachine
);

Parameters

ppCommand
[out] Pointer to an output variable that receives the ICommand interface pointer.
cScope
[in] Count of scopes in the awcsScope array.
aDepths
[in] Pointer to an array of values that represent the type of search (deep or shallow, virtual or physical) for each scope in awcsScope. For the possible values for each scope, see QUERY_* Scope Constants.
awcsScope
[in] Pointer to a an array of null-terminated strings that specify the names of the file path(s) over which the query is processed. This is the value for the DBPROP_CI_INCLUDE_SCOPE property of the ICommand interface. Use L"\" for the entire catalog. Use L"\" for the entire Internet Information Services (IIS) virtual-path name space, but set QUERY_VIRTUAL_PATH in the aDepths parameter to indicate the path is virtual.
awcsCatalogs
[in] Pointer to a an array of null-terminated strings that specify the names of the catalogs used to execute queries. This is the value for the DBPROP_CI_CATALOG_NAME property of the ICommand interface.
awcsMachine
[in] Pointer to a null-terminated string that specifies the name of the machine on which the query is executed. This is the value for the DBPROP_CI_MACHINE_NAME property of the ICommand interface. Use L"." for the local machine.

Return Values

S_OK
Successful completion.
E_ACCESSDENIED
The function was denied access to a specified path.
E_HANDLE
The function encountered an invalid handle, probably due to a low-memory situation.
E_INVALIDARG
The function received an invalid parameter.
E_OUTOFMEMORY
The function did not have sufficient memory or other resources to complete the operation.
E_FAIL
The function encountered an unknown error.

Remarks

The CIMakeICommand function does not return an error if the catalog or computer does not exist or is unavailable. The connection to the catalog and computer is established when the ICommand::Execute method is called, and connection errors are returned at that time.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

CICreateCommand, Command, Command Trees, ICommand


CIRestrictionToFullTree

The CIRestrictionToFullTree function creates a full DBCOMMANDTREE structure for a given query restriction (SELECT tree), set of column definitions for the display output (PROJECT part of the tree), and set of sort columns (SORT part of the tree).

STDAPI CIRestrictionToFullTree(
  DBCOMMANDTREE const * pTree,
  WCHAR const * pwszColumns,
  WCHAR const * pwszSortColumns,
  WCHAR const * pwszGroupings,
  DBCOMMANDTREE ** ppTree,
  ULONG cProperties,
  CIPROPERTYDEF * pProperties,
  LCID LocaleID
);

Parameters

pTree
[in] Pointer to a DBCOMMANDTREE structure that is the top node defining a SELECT tree for a query.
pwszColumns
[in] Pointer to a null-terminated string that specifies a comma separated list of column names returned in the query results. These columns can be bound by OLE DB accessors and are used to create the PROJECT part of the full tree.
pwszSortColumns
[in] Pointer to a null-terminated string that contains a comma-separated list of column names that specify the sort order for the query results. A sort direction can be appended to each column name. Use [d] for descending, and [a] for ascending. If no sort order is specified, ascending is the default. Can be NULL for no sort order. These columns are used to create the SORT part of the full tree.
pwszGroupings
[in] Pointer to a null-terminated string that contains a grouping specification made up of a type (currently only [unique] is supported), a property name, and a sort order ([a] for ascending or [d] for descending). In a unique grouping, unique values of the column set form the individual categories.

The syntax for the unique grouping term is:

unique fname [ {[a]|[d]} ] [ , fname2 {[a]|[d]} ... ]

where fname and fname2 are the assigned friendly names.

Column names separated by a comma (,) are grouped together into subgroups of the preceding grouping.

Optional (can be NULL).

ppTree
[out] Pointer to an output variable that receives a pointer to a DBCOMMANDTREE structure. Must be non-NULL.
cProperties
[in] Count of properties in the pProperties array, or zero if pProperties is NULL.
pProperties
[in] Pointer to an array of properties that can be referred to by a friendly name in the pwszColumns, pwszSortColumns, and pwszGroupings parameters. Column names in the wcsFriendlyName member of each CIPROPERTYDEF structure must be specified in uppercase. Can be NULL if no properties are being defined and if cProperties is zero. Indexing Service's built-in properties do not need to be defined to be used. It is an error to define a property with the same friendly name as that of a built-in property.
LocaleID
[in] Locale ID (LCID) used when converting properties.

Return Values

S_OK
Successful completion.
E_HANDLE
The function encountered an invalid handle, probably due to a low-memory situation.
E_INVALIDARG
The function received an invalid parameter.
E_OUTOFMEMORY
The function did not have sufficient memory or other resources to complete the operation.
E_FAIL
The function encountered an unknown error.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

CIPROPERTYDEF, Command Trees, DBCOMMANDTREE


CIState

The CIState function queries the state of the selected Indexing Service catalog.

STDAPI CIState(
  WCHAR const * pwcsCat,
  WCHAR const * pwcsMachine,
  CI_STATE *    pCiState
);

Parameters

pwcsCat
Pointer to a string containing the catalog name, such as Web or System.
pwcsMachine
Pointer to a string containing the machine name, such as "." for the local machine or "RemoteServer1", on which the catalog is located.
pCiState
Pointer to a CI_STATE structure that receives the catalog state.

Return Values

S_OK
Successful completion.
E_INVALIDARG
pwcsCat or pCiState is not a valid pointer, or the structure to which pCiState points does not contain enough bytes to hold the resulting state.
CI_E_NOT_FOUND
The function failed because either the catalog or the machine was not found.
CI_E_NOT_RUNNING
The function failed because Indexing Service is not running.
CI_E_TIMEOUT
The function failed because Indexing Service is too busy to respond to the query.

Remarks

The CI_STATE structure must be initialized (the CI_STATE::cbStruct member must be correctly set) before calling the CIState function.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

CI_STATE, CI_STATE_* Constants


CITextToFullTree

The CITextToFullTree function creates a complete DBCOMMANDTREE structure from an Indexing Service query language, Dialect 1 query string, output columns, sort columns, and a set of custom properties. To specify the use of a later version of the Indexing Service Query Language, use the CITextToFullTreeEx function.

STDAPI CITextToFullTree(
  WCHAR const * pwszRestriction,
  WCHAR const * pwszColumns,
  WCHAR const * pwszSortColumns,
  WCHAR const * pwszGroupings,
  DBCOMMANDTREE ** ppTree,
  ULONG cProperties,
  CIPROPERTYDEF * pProperties,
  LCID LocaleID
);

Parameters

pwszRestriction
[in] Pointer to a null-terminated string that specifies an Indexing Service query language, Dialect 1 query.
pwszColumns
[in] Pointer to a null-terminated string that specifies a comma-separated list of column names returned in the query results. These columns can be bound by OLE DB accessors.
pwszSortColumns
[in] Pointer to a null-terminated string that contains a comma separated list of column names that specify the sort order for the query results. A sort direction can be appended to each column name. Use [d] for descending, and [a] for ascending. If no sort order is specified, ascending is the default. Can be NULL for no sort order.
pwszGroupings
[in] Pointer to a null-terminated string that contains a grouping specification made up of a type (currently only [unique] is supported), a property name, and a sort order ([a] for ascending or [d] for descending). In a unique grouping, unique values of the column set form the individual categories.

The syntax for the unique grouping term is:

unique fname [ {[a]|[d]} ] [ , fname2 {[a]|[d]} ... ]

where fname and fname2 are the assigned friendly names.

Column names separated by a comma (,) are grouped together into subgroups of the preceding grouping.

Optional (can be NULL).

ppTree
[out] Pointer to an output variable that receives a pointer to the DBCOMMANDTREE structure for the command tree built by the function.
cProperties
[in] Count of properties in the pProperties array, or NULL if pProperties is zero.
pProperties
[in] Pointer to an array of properties that can be referred to by friendly names in the pwszColumns, pwszSortColumns, pwszGroupings, and pwszRestriction parameters. Column names in the wcsFriendlyName field of each CIPROPERTYDEF must be specified in uppercase. Can be NULL if no properties are being defined and cProperties is zero. Indexing Service's built-in properties do not need to be defined to be used. It is an error to define a property with the same friendly name as that of a built-in property.
LocaleID
[in] The locale ID (LCID) used for nodes in ppTree that contain an LCID member, including such nodes as content restrictions, sort order, and so on.

Return Values

S_OK
Successful completion.
E_HANDLE
The function encountered an invalid handle, probably due to a low-memory situation.
E_INVALIDARG
The function received an invalid parameter.
E_OUTOFMEMORY
The function did not have sufficient memory or other resources to complete the operation.
E_FAIL
The function encountered an unknown error.

Remarks

The query tree allocated by the CITextToFullTree function must be freed either with the ICommandTree::FreeCommandTree method or passed to the ICommandTree::SetCommandTree method with the fCopy parameter set to FALSE.

You need to include the following #define directive before your #include <oledberr.h> to access the command tree definitions.

#define DBINITCONSTANTS
#include <oledberr.h>
#include <oledb.h>
#include <cmdtree.h>

Example

This sample code creates a command tree. A custom property from a Microsoft Word document named "IssueNumber" of type "Number" is defined and used in the query. The list of properties returned by the query includes path and size. The sort order is first by rank descending, then by path ascending. The default system locale is used to create the command tree.

CIPROPERTYDEF aProperties[1];
const GUID guidOffice = { 0xd5cdd505, 0x2e9c, 0x101b,
                          0x93, 0x97, 0x08, 0x00, 0x2b, 0x2c, 0xf9, 0xae }
                            };
aProperties[0].wcsFriendlyName = L"ISSUENUMBER";
aProperties[0].dbType = DBTYPE_R8;
aProperties[0].dbCol.uGuid.guid = guidOffice;
aProperties[0].dbCol.eKind = DBKIND_GUID_NAME;
aProperties[0].dbCol.pwszName.ulPropid = L"ISSUENUMBER";
DBCOMMANDTREE * pTree;
HRESULT hr = CiTextToFullTree( L"microsoft and @issuenumber=2",
                               L"size,path,issuenumber",
                               L"rank[d],path[a]",
                               ,
                               &pTree,
                               1,
                               aProperties,
                               GetSystemDefaultLCID() );
if ( SUCCEEDED( hr ) )
{
    hr = pICommandTree->SetCommandTree( pTree,
                                    DBCOMMANDREUSE_NONE,
                                    FALSE );
    if ( SUCCEEDED( hr ) )
    {
        // ...
        // execute a query
        // ...
    }
}

The following diagram shows the pTree parameter, created by the example code, of the DBCOMMANDTREE structure.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

CIPROPERTYDEF, CITextToFullTreeEx, CITextToSelectTree, Command Trees, DBCOMMANDTREE, Indexing Service Query Language, ICommandTree::FreeCommandTree, ICommandTree::SetCommandTree


CITextToFullTreeEx

The CITextToFullTreeEx function extends the functionality of the CITextToFullTree function to include all Indexing Service query dialects and creates a complete DBCOMMANDTREE structure from a query string, output columns, sort columns, and a set of custom properties.

STDAPI CITextToFullTreeEx(
  WCHAR const * pwszRestriction,
  ULONG         ulDialect,
  WCHAR const * pwszColumns,
  WCHAR const * pwszSortColumns,
  WCHAR const * pwszGroupings,
  DBCOMMANDTREE ** ppTree,
  ULONG cProperties,
  CIPROPERTYDEF * pProperties,
  LCID LocaleID
);

Parameters

pwszRestriction
[in] Pointer to a null-terminated string that specifies an Indexing Service query. The syntax for queries is described in Query Languages for Indexing Service.
ulDialect
[in] A value from ISQLANG_* constants that specifies a specific version of the Indexing Service query language to use.
pwszColumns
[in] Pointer to a null-terminated string that specifies a comma-separated list of column names returned in the query results. These columns can be bound by OLE DB accessors.
pwszSortColumns
[in] Pointer to a null-terminated string that contains a comma-separated list of column names that specify the sort order for the query results. A sort direction can be appended to each column name. Use [d] for descending, and [a] for ascending. If no sort order is specified, ascending is the default. Can be NULL for no sort order.
pwszGroupings
[in] Pointer to a null-terminated string that contains a grouping specification made up of a type (currently only [unique] is supported), a property name, and a sort order ([a] for ascending or [d] for descending). In a unique grouping, unique values of the column set form the individual categories.

The syntax for the unique grouping term is:

unique fname [ {[a]|[d]} ] [ , fname2 {[a]|[d]} ... ]

where fname and fname2 are the assigned friendly names.

Column names separated by a comma (,) are grouped together into subgroups of the preceding grouping.

Optional (can be NULL).

ppTree
[out] Pointer to the address of the location to receive the DBCOMMANDTREE structure for the command tree.
cProperties
[in] Count of properties in the pProperties array, or zero if pProperties is NULL.
pProperties
[in] Pointer to an array of properties that can be referred to by a friendly name in the pwszColumns, pwszSortColumns, pwszGroupings, and pwszRestriction parameters. Column names in the wcsFriendlyName member of each CIPROPERTYDEF structure must be specified in uppercase. Can be NULL if no properties are being defined and cProperties is zero. Indexing Service's built-in properties do not need to be defined to be used. It is an error to define a property with the same friendly name as that of a built-in property.
LocaleID
[in] The locale ID (LCID) used for nodes in ppTree that contain an LCID member, including nodes such as content restrictions, sort order, and other locale properties.

Return Values

S_OK
Successful completion.
E_HANDLE
The function encountered an invalid handle, probably due to a low-memory situation.
E_INVALIDARG
The function received an invalid parameter.
E_OUTOFMEMORY
The function did not have sufficient memory or other resources to complete the operation.
E_FAIL
The function encountered an unknown error.

Remarks

The query tree allocated by the CITextToFullTreeEx function must be freed either with the ICommandTree::FreeCommandTree method or passed to the ICommandTree::SetCommandTree method with the fCopy parameter set to FALSE.

You need to include the following #define directive before your #include <oledberr.h> to access the command tree definitions.

#define DBINITCONSTANTS
#include <oledberr.h>
#include <oledb.h>
#include <cmdtree.h>

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

CIPROPERTYDEF, CITextToFullTree, CITextToSelectTree, Command Trees, DBCOMMANDTREE, ICommandTree::FreeCommandTree, ICommandTree::SetCommandTree, ISQLANG_* Constants, Query Languages for Indexing Service


CITextToSelectTree

The CITextToSelectTree function creates a DBCOMMANDTREE structure from an Indexing Service query language, Dialect 1 query string. The command tree returned by this function can be used as the next sibling under a DBOP_table_name node. A DBOP_project node is also required to form a complete command tree. To use the Indexing Service query language, Dialect 2, use the CITextToSelectTreeEx function.

STDAPI CITextToSelectTree(
  WCHAR const * pwszRestriction,
  DBCOMMANDTREE ** ppTree,
  ULONG cProperties,
  CIPROPERTYDEF * pProperties,
  LCID LocaleID
);

Parameters

pwszRestriction
[in] Pointer to a null-terminated string specifying an Indexing Service Query Language Dialect 1 query.
ppTree
[out] Pointer to the address of the location to receive the DBCOMMANDTREE structure that represents the top node of the SELECT part of the full command tree.
cProperties
[in] Count of properties in the pProperties array, or zero if pProperties is NULL.
pProperties
[in] Pointer to an array of properties that can be referred to by friendly name in pwszRestriction. Column names in the wcsFriendlyName member of each CIPROPERTYDEF structure must be specified in uppercase. Indexing Service's built-in properties do not need to be defined to be used. It is an error to define a property with the same friendly name as that of a built-in property.
LocaleID
[in] The locale ID (LCID) used for nodes in the tree returned in ppTree that contain an LCID member, including such nodes as content restrictions and sort order.

Return Values

S_OK
Successful completion.
E_HANDLE
The function encountered an invalid handle, probably due to a low-memory situation.
E_INVALIDARG
The function received an invalid parameter.
E_OUTOFMEMORY
The function did not have sufficient memory or other resources to complete the operation.
E_FAIL
The function encountered an unknown error.

Remarks

Command trees created by the CITextToSelectTree function contain the SELECT portion of a DBCOMMANDTREE structure. A tree returned by the CITextToSelectTree function can be combined with project and sort nodes to form a complete command tree. Use the CITextToSelectTree function instead of the CITextToFullTree function if the sort order and project columns tree nodes are already available.

The query tree allocated by the CITextToSelectTree function must be freed either with the ICommandTree::FreeCommandTree method or passed to the ICommandTree::SetCommandTree method with the fCopy parameter set to FALSE.

Example

This example creates a DBCOMMANDTREE structure. A custom property from a Microsoft Word document named "IssueNumber" of type "Number" is defined and used in the query.

DBCOMMANDTREE * pCompleteTree;
DBCOMMANDTREE * pTableNode;

// ...
// Insert code here to make pCompleteTree a complete tree using pTableNode
// as the DBOP_table_name node that has no query restriction (yet).
// User CoTaskMemAlloc to allocate memory for the nodes.
// ...
//

CIPROPERTYDEF aProperties[1];
const GUID guidOffice = { 0xd5cdd505, 0x2e9c, 0x101b,
                          0x93, 0x97, 0x08, 0x00, 0x2b, 0x2c, 0xf9, 0xae }
                            };
aProperties[0].wcsFriendlyName = L"ISSUENUMBER";
aProperties[0].dbType = DBTYPE_R8;
aProperties[0].dbCol.uGuid.guid = guidOffice;
aProperties[0].dbCol.eKind = DBKIND_GUID_NAME;
aProperties[0].dbCol.pwszName.ulPropid = L"ISSUENUMBER";
DBCOMMANDTREE * pSelectTree;
HRESULT hr = CiTextToSelectTree( L"Microsoft and @issuenumber=2",
                                 &pSelectTree,
                                 1,
                                 aProperties,
                                 GetSystemDefaultLCID() );
if ( SUCCEEDED( hr ) )
{
    pTableNode->pctNextSibling = pSelectTree;
    hr = pICommand->SetCommandTree( pCompleteTree,
                                    DBCOMMANDREUSE_NONE,
                                    FALSE );
    if ( SUCCEEDED( hr ) )
    {
        // ...
        // execute a query
        // ...
    }
}

The following diagram shows the DBCOMMANDTREE structure pSelectTree created by the example code.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

CIPROPERTYDEF, CIRestrictionToFullTree, CITextToFullTree, CITextToSelectTreeEx, Command Trees, DBCOMMANDTREE, ICommandTree::FreeCommandTree, ICommandTree::SetCommandTree, Indexing Service Query Language


CITextToSelectTreeEx

The CITextToSelectTreeEx function extends the functionality of the CITextToSelectTree function to include all dialects of Query Languages for Indexing Service and creates a DBCOMMANDTREE structure from an Indexing Service query language string. The command tree returned by this function can be used as the next sibling under a DBOP_table_name node. A DBOP_project node is also required to form a complete command tree.

STDAPI CITextToSelectTreeEx(
  WCHAR const * pwszRestriction,
  ULONG         ulDialect,
  DBCOMMANDTREE ** ppTree,
  ULONG cProperties,
  CIPROPERTYDEF * pProperties,
  LCID LocaleID
);

Parameters

pwszRestriction
[in] Pointer to a null-terminated string specifying an Indexing Service query. The syntax for queries is described in Query Languages for Indexing Service.
ulDialect
[in] A value from ISQLANG_* constants that specifies a specific version of the Indexing Service query language to use.
ppTree
[out] Pointer to an output variable that receives a pointer to the DBCOMMANDTREE structure for the command tree built by the function.
cProperties
[in] Count of properties in the pProperties array, or zero if pProperties is NULL.
pProperties
[in] Pointer to an array of properties that can be referred to by friendly name in pwszRestriction. Column names in the wcsFriendlyName member of each CIPROPERTYDEF structure must be specified in uppercase. Indexing Service's built-in properties do not need to be defined to be used. It is an error to define a property with the same friendly name as that of a built-in property.
LocaleID
[in] The locale ID (LCID) used for nodes in the tree returned in ppTree that contain an LCID member, including such nodes as content restrictions and sort order.

Return Values

S_OK
Successful completion.
E_ACCESSDENIED
The function was denied access to the specified path.
E_HANDLE
The function encountered an invalid handle, probably due to a low-memory situation.
E_INVALIDARG
The function received an invalid parameter.
E_OUTOFMEMORY
The function did not have sufficient memory or other resources to complete the operation.
E_FAIL
The function encountered an unknown error.

Remarks

Command trees created by the CITextToSelectTreeEx function contain the select portion of a DBCOMMANDTREE structure. A tree returned by the CITextToSelectTreeEx function can be combined with project and sort nodes to form a complete command tree. Use the CITextToSelectTreeEx function instead of the CITextToFullTreeEx function if the sort order and project columns tree nodes are already available.

The query tree allocated by the CITextToSelectTreeEx function must be freed either with the ICommandTree::FreeCommandTree method or passed to the ICommandTree::SetCommandTree method with the fCopy parameter set to FALSE.

Example

This example creates a DBCOMMANDTREE structure. A custom property from a Microsoft Word document named "IssueNumber" of type "Number" is defined and used in the query.

DBCOMMANDTREE * pCompleteTree;
DBCOMMANDTREE * pTableNode;

// ...
// Insert code here to make pCompleteTree a complete tree using pTableNode
// as the DBOP_table_name node that has no query restriction (yet).
// User CoTaskMemAlloc to allocate memory for the nodes.
// ...
//

CIPROPERTYDEF aProperties[1];
const GUID guidOffice = { 0xd5cdd505, 0x2e9c, 0x101b,
                          0x93, 0x97, 0x08, 0x00, 0x2b, 0x2c, 0xf9, 0xae }
                            };
aProperties[0].wcsFriendlyName = L"ISSUENUMBER";
aProperties[0].dbType = DBTYPE_R8;
aProperties[0].dbCol.uGuid.guid = guidOffice;
aProperties[0].dbCol.eKind = DBKIND_GUID_NAME;
aProperties[0].dbCol.pwszName.ulPropid = L"ISSUENUMBER";
DBCOMMANDTREE * pSelectTree;
HRESULT hr = CiTextToSelectTreeEx( L"microsoft and @issuenumber=2",
                                 ISQLANG_V1
                                 &pSelectTree,
                                 1,
                                 aProperties,
                                 GetSystemDefaultLCID() );
if ( SUCCEEDED( hr ) )
{
    pTableNode->pctNextSibling = pSelectTree;
    hr = pICommand->SetCommandTree( pCompleteTree,
                                    DBCOMMANDREUSE_NONE,
                                    FALSE );
    if ( SUCCEEDED( hr ) )
    {
        // ...
        // execute a query
        // ...
    }
}

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

CIPROPERTYDEF, CIRestrictionToFullTree, CITextToFullTreeEx, CITextToSelectTree, Command Trees, DBCOMMANDTREE, ICommandTree::FreeCommandTree, ICommandTree::SetCommandTree, ISQLANG_* Constants, Query Languages for Indexing Service


LoadIFilter

The LoadIFilter function takes the path name for an object and retrieves the IFilter interface pointer on that object in order to filter its text.

STDAPI LoadIFilter(
  WCHAR const * pwcsPath,
  IUnknown * pUnkOuter,
  void ** ppIUnk
);

Parameters

pwcsPath
[in] Pointer to the full path of an object for which an IFilter interface pointer is to be returned.
pUnkOuter
[in] Pointer to the controlling IUnknown interface of the aggregate in which this storage object exists.
ppIUnk
[out] Pointer to an output variable that receives the IFilter interface pointer.

Return Values

S_OK
Successful completion.
E_ACCESSDENIED
The function was denied access to the filter file.
E_HANDLE
The function encountered an invalid handle, probably due to a low-memory situation.
E_INVALIDARG
The function received an invalid parameter.
E_OUTOFMEMORY
The function did not have sufficient memory or other resources to complete the operation.
E_FAIL
The function encountered an unknown error.

Remarks

This function is not a full implementation of a COM-persistent handler.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

BindIFilterFromStorage, BindIFilterFromStream, IFilter, IUnknown


LocateCatalogs

The LocateCatalogs function determines which indexes can be used to process queries for files in a specified path. The machine and catalog parameter values returned by the LocateCatalogs function can be used to create an OLE DB Command object for issuing queries over a given scope.

STDAPI LocateCatalogs(
  TCHAR const * pwszScope,
  ULONG iBmk,
  TCHAR * pwszMachine,
  ULONG * pcMachine,
  TCHAR * pwszCat,
  ULONG * pcCat
);

Parameters

pwszScope
[in] Pointer to a null-terminated string that specifies the scope for an Indexing Service query. The scope can be local (C:\directory) or a remote universal naming convention (UNC) (\\MACHINE\SHARE\directory). The scope cannot be a redirected drive letter (a drive letter that refers to a drive on a remote machine). For Web catalogs, scopes must be physical, not IIS virtual scopes. To specify any catalog on the machine, use L"\".
iBmk
[in] Specifies the zero-based bookmark of the result to be retrieved. Pass zero to retrieve the first machine and catalog that index pwszScope, pass one to retrieve the second machine and catalog that index pwszScope, and so on. If no index for the bookmark is available, the LocateCatalogs function returns S_FALSE.
pwszMachine
[out] Pointer to a buffer where a null-terminated string is written if the function is successful. The result string is the machine name on which a query over the scope pwszScope can be executed.
pcMachine
[in/out] On input, pointer to a character count that specifies the size of pwszMachine, including the terminating null character. On output, specifies the count of characters used in pwszMachine if the function is successful, or the count of characters needed to store the name of the machine if the buffer is too small. If the buffer is too small, the LocateCatalogs function returns S_OK.
pwszCat
[out] Pointer to a buffer where a null-terminated string is written if the function is successful. The result string is the machine name on which a query over the scope pwszScope can be executed.
pcCat
[in/out] On input, pointer to a character count that specifies the size of pwszCat, including the terminating null character. On output, specifies the count of characters used in pwszCat if the function is successful, or the count of characters needed to store the name of the catalog if the buffer is too small. If the buffer is too small, the LocateCatalogs function returns S_OK.

Return Values

S_OK
Successful completion.
S_FALSE
No machine and catalog can be found that index the scope, or iBmk is beyond the count of machines and catalogs that index the scope.
E_INVALID_ARG
The function received an invalid pointer.
QUERY_E_INVALID_DIRECTORY
The function received an invalid scope.

For other errors, the LocateCatalogs function returns a valid OLE-defined or Query-defined OLE error.

Remarks

Use the LocateCatalogs function to determine catalogs that cover a specific scope. If the computer and catalog are known, it's more efficient to execute a query without calling the LocateCatalogs function.

The LocateCatalogs function does not verify that the computer and catalog returned are available. If an application fails to issue a query with the computer and catalog returned, it should increment iBmk and call the LocateCatalogs function again to get the next computer and catalog that index the specified scope.

If a machine-and-catalog match is found but the machine and catalog buffers aren't large enough, the LocateCatalogs function returns S_OK, and fills the pcCat and pcMachine parameters with the wide character required. Callers of the LocateCatalogs function must check the return code, pcMachine, and pcCat to determine whether the call was successful.

Note If the LocateCatalogs function finds a catalog that includes the path in pwszScope, it does not determine whether the scope is excluded for that catalog.

Example

This example enumerates all computers and catalogs capable of resolving queries over the scope "C:\directory".

HRESULT hr = S_OK;

for ( ULONG iBmk = 0; S_OK == hr; iBmk++ )
{
    TCHAR awcMachine[ MAX_COMPUTERNAME_LENGTH + 1 ];
    const ULONG cwcMachineBuffer = sizeof awcMachine / sizeof TCHAR;
    ULONG cwcMachine = cwcMachineBuffer;
    TCHAR awcCatalog[ MAX_PATH + 1 ];
    const ULONG cwcCatalogBuffer = sizeof awcCatalog / sizeof TCHAR;
    ULONG cwcCatalog = cwcCatalogBuffer;

    hr = LocateCatalogs( L"c:\\directory",
                         iBmk,
                         awcMachine,
                         &cwcMachine,
                         awcCatalog,
                         &cwcCatalog );
    if ( ( hr == S_OK ) &&
         ( cwcMachine <= cwcMachineBuffer ) &&
         ( cwcCatalog <= cwcCatalogBuffer ) )
    {
        wprintf( L"matching machine and catalog: '%s', '%s'\n",
                awcMachine, awcCatalog );
    }
}

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Command, SetCatalogState


SetCatalogState

The SetCatalogState function provides administration control over Indexing Service catalogs. You can use it to take a catalog offline, to allow only queries (no indexing), to allow only indexing (no queries), to allow both querying and indexing, or to simply read the current state of a catalog.

STDAPI SetCatalogState(
  WCHAR const * pwcsCat,
  WCHAR const * pwcsMachine,
  DWORD dwNewState,
  DWORD * pdwOldState
);

Parameters

pwcsCat
[in] Pointer to the name of the catalog, for example, L"system" or L"Web".
pwcsMachine
[in] Pointer to the name of the computer where the catalog exists; for example, L"." for the local computer.
dwNewState
[in] A constant from CICAT_* constants to set the state of the catalog.
pdwOldState
[out] Pointer to a value that receives one of the CICAT_* constants that reflects the current state of the catalog.

Return Values

S_OK
Successful completion.
E_INVALIDARG
The function received an invalid parameter.
CI_E_NOT_FOUND
The function failed because either the catalog or the computer was not found.
CI_E_NOT_RUNNING
The function failed because Indexing Service is not running.
CI_E_TIMEOUT
The function failed because Indexing Service is too busy.

Remarks

The following table describes the possible states of an Indexing Service catalog. You do not have to stop the catalog first to set its state. To retrieve only the current state, use a setting of CICAT_GET_STATE.

Desired State | CICAT_ Setting
Catalog stopped or offline | CICAT_STOPPED
Processing queries only | CICAT_READONLY
Querying and indexing. | CICAT_WRITABLE
Indexing only | CICAT_NO_QUERY

A catalog can be read-only if any of the following conditions exist:

  1. The value of the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\ContentIndex\Catalogs\<catalog name>\IsReadOnly registry entry is set to 1.
  2. The catalog is on a write-protected volume.
  3. The catalog, specifically the file cicat.hsh, is read-only.

If any of the preceding conditions exist and the CICAT_WRITABLE bit is set, it does not have the desired effect and the catalog is opened read-only.

If the dwNewState parameter contains CICAT_NO_QUERY, the system checks to see whether the catalog can be set to a writable state. If any of the preceding conditions exist that prevent the catalog from being writable, the catalog remains read-only and the pdwOldState parameter returns CICAT_READONLY. However, because the intention of the flag is to halt querying, the catalog stops accepting queries even though it is in this read-only state.

Specifically, if you make the call:

SetCatalogState("System", ".", CICAT_NO_QUERY, &OldState)

the value of the pdwOldState parameter on return will contain CICAT_NO_QUERY in addition to CI_CAT_WRITABLE or CI_CAT_READONLY values, depending on the READONLY/WRITABLE attributes of the volume or file.

If you make the call to SetCatalogState, where the dwNewState parameter is any value other than CICAT_NO_QUERY, then the value of the *pdwOldState parameter on return will contain one of the mutually exclusive CICAT_* constants (excluding CICAT_NO_QUERY and CICAT_GET_STATE) which reflects the current state of the catalog.

Note If you issue a net pause command or a net continue command for Indexing Service, the state changes that were set by the SetCatalogState function are not preserved.

For examples of changes in a catalog's state, see the ChgState sample in the Platform SDK directory mssdk\samples\winbase\indexing\chgstate.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.
Import Library: Use ntquery.lib.

See Also

CICAT_* Constants, LocateCatalogs


Property Sets

Indexing Service provides several property sets to use with OLE DB Provider for Indexing Service. In addition, Indexing Service uses several COM property sets.

For examples of how to use these property sets, see the Simple sample and the AdvQuery sample in the Platform SDK directories mssdk\samples\winbase\indexing\simple and mssdk\samples\winbase\indexing\advquery.

The following table lists the globally unique identifier (GUID) and a short description of each property set:

GUID identifier | Description
DBPROPSET_CIFRMWRKCORE_EXT | Extended core properties including the machine name and class identifier (CLSID) of clients of indexing service.
DBPROPSET_FSCIFRMWRK_EXT | Extended file system properties including catalog and scope properties.
DBPROPSET_MSIDXS_ROWSETEXT | Rowset properties including the query string and its locale.
DBPROPSET_QUERYEXT | Extended query properties including query control properties.
PSGUID_QUERY | Query properties including query result properties.
PSGUID_STORAGE | Storage properties including file properties.


DBPROPSET_CIFRMWRKCORE_EXT

The DBPROPSET_CIFRMWRKCORE_EXT property set contains system properties that define the machine name and client CLSID.

#define DBPROPSET_CIFRMWRKCORE_EXT \
    { 0xafafaca5, 0xb5d1, 0x11d0, \
        { 0x8c, 0x62, 0x00, 0xc0, 0x4f, 0xc2, 0xdb, 0x8d } }

Remarks

The DBPROPSET_CIFRMWRKCORE_EXT property set contains the following property constants.

DBPROP_MACHINE
Property ID 2. The computer name running Indexing Service.
DBPROP_CLIENT_CLSID
Property ID 3. The CLSID of the client querying Indexing Service.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.

See Also

OLE DB Provider for Indexing Service


DBPROPSET_FSCIFRMWRK_EXT

The DBPROPSET_FSCIFRMWRK_EXT property set contains file system properties that represent the catalog name and the scopes indexed by that catalog.

#define DBPROPSET_FSCIFRMWRK_EXT \
    { 0xA9BD1526, 0x6A80, 0x11D0, \
        { 0x8C, 0x9D, 0x00, 0x20, 0xAF, 0x1D, 0x74, 0x0E } }

Remarks

The DBPROPSET_FSCIFRMWRK_EXT property set contains the following property constants:

DBPROP_CI_CATALOG_NAME
Property ID 2. PIDContent Index catalog name.
DBPROP_CI_INCLUDE_SCOPES
Property ID 3. Directories indexed by a catalog.
DBPROP_CI_SCOPE_FLAGS
Property ID 4. A combination of QUERY_* scope constants.
DBPROP_CI_EXCLUDE_SCOPES
Property ID 5. Directories excluded from indexing by a catalog.
DBPROP_CI_SECURITY_ID
Property ID 6. Security ID of query. Reserved for future use.
DBPROP_CI_QUERY_TYPE
Property ID 7. Type of query. Reserved for future use.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.

See Also

OLE DB Provider for Indexing Service, QUERY_* Scope Constants


DBPROPSET_MSIDXS_ROWSETEXT

The DBPROPSET_MSIDXS_ROWSETEXT property set extends properties defined for the OLE DB Rowset object.

#define DBPROPSET_MSIDXS_ROWSETEXT \
    { 0xaa6ee6b0, 0xe828, 0x11d0, \
        { 0xb2, 0x3e, 0x00, 0xaa, 0x00, 0x47, 0xfc, 0x01 } }

Remarks

The DBPROPSET_MSIDXS_ROWSETEXT property set contains the following property constants:

MSIDXSPROP_ROWSETQUERYSTATUS
Property ID 2. Query status for the rowset. The STAT_* constants indicate the execution and reliability status.
MSIDXSPROP_COMMAND_LOCALE_STRING
Property ID 3. Locale string that represents the language and locale setting to use for this rowset.
MSIDXSPROP_QUERY_RESTRICTION
Property ID 4. The query string associated with this rowset.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.

See Also

OLE DB Provider for Indexing Service, Rowset


DBPROPSET_QUERYEXT

The DBPROPSET_QUERYEXT property set contains several settings that give you control over the way Indexing Service satisfies a query.

#define DBPROPSET_QUERYEXT \
    { 0xA7AC77ED, 0xF8D7, 0x11CE, \
        { 0xA7, 0x98, 0x00, 0x20, 0xF8, 0x00, 0x80, 0x25 } }

Remarks

The DBPROPSET_QUERYEXT property set contains the following property constants.

DBPROP_USECONTENTINDEX
Property ID 2. When this value is TRUE, all queries use the content index to resolve queries, even if the index is out of date (when there are files waiting to be indexed). This avoids the time-consuming enumeration of all files in a catalog's scopes to resolve the query. It is for use when your application can tolerate resolution of queries using the current state of the index.
DBPROP_DEFERNONINDEXEDTRIMMING
Property ID 3. When this value is TRUE, Indexing Service first collects the maximum number of hits allowed for a query and then eliminates hits that don't meet the scope or security requirements. This can result in fewer-than-expected hits but better performance.
DBPROP_USEEXTENDEDDBTYPES
Property ID 4. When this value is TRUE, data returned is in PROPVARIANT structures instead of the default automation VARIANT types. This is useful in improving performance because it obviates the need for type conversions. It is unique to OLE DB Provider for Indexing Service.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.

See Also

OLE DB Provider for Indexing Service, PROPVARIANT


PSGUID_QUERY

The PSGUID_QUERY property set contains query properties computed or made available by the query engine in Indexing Service.

extern const GUID PSGUID_QUERY = {0x49691c90,0x7e17,0x101a,{0xa9,0x1c,0x08,0x00,0x2b,0x2e,0xcd,0xa9}};

Remarks

The PSGUID_QUERY property set contains the following property constants:

PROPID_QUERY_RANKVECTOR
Property ID 2. The array of ranks for each term in a vector query. Default type is VT_VECTOR | VT_UI4. The Indexing Service friendly name is "rankvector".
PROPID_QUERY_RANK
Property ID 3. A file's rank, which indicates how well the query matched the file. This value is between zero and 1000. Default type is VT_I4. The Indexing Service friendly name is "rank".
PROPID_QUERY_HITCOUNT
Property ID 4. The count of query hits in a file. Default type is VT_I4. The Indexing Service friendly name is "hitcount".
PROPID_QUERY_WORKID
Property ID 5. Value used to track objects.
PROPID_QUERY_ALL
Property ID 6. Refers to all properties of the file. This property is for query restrictions only; it cannot be retrieved in a query result. Default type is VT_LPWSTR. The Indexing Service friendly name is "all".
PROPID_QUERY_UNFILTERED
Property ID 7. Filtered state of the file. Default type is VT_BOOL. There is no Indexing Service name for this property; it must be defined manually.
PROPID_QUERY_VIRTUALPATH
Property ID 9. The Internet Information Services (IIS) virtual path of a file. The path can be in the World Wide Web (WWW), Network News Transfer Protocol (NNTP), or Internet Message Access Protocol (IMAP) name spaces. Default type is VT_LPWSTR. The Indexing Service friendly name is "vpath".
PROPID_QUERY_LASTSEENTIME
Property ID 10. Time-stamp value used for caching queries.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h and oledb.h.

See Also

OLE DB Provider for Indexing Service


PSGUID_STORAGE

The PSGUID_STORAGE property set defines storage properties found for files in a file system.

#define PSGUID_STORAGE \
    { 0xb725f130, 0x47ef, 0x101a, \
        { 0xa5, 0xf1, 0x02, 0x60, 0x8c, 0x9e, 0xeb, 0xac } }

Remarks

The PSGUID_STORAGE property set contains the following property constants.

PID_STG_DIRECTORY
Property ID 2. The directory in which a file is located. Default type is VT_LPWSTR. The Indexing Service friendly name is "directory".
PID_STG_CLASSID
Property ID 3. CLID of a file. Default type is VT_CLSID. The Indexing Service friendly name is "classid".
PID_STG_STORAGETYPE
Property ID 4. Storage type for this file.
PID_STG_VOLUME_ID
Property ID 5. Volume ID of the disk.
PID_STG_PARENT_WORKID
Property ID 6. Internal work ID for the parent or folder for this file.
PID_STG_SECONDARYSTORE
Property ID 7. Whether the file has been placed in secondary storage.
PID_STG_FILEINDEX
Property ID 8. Internal file index for this file.
PID_STG_LASTCHANGEUSN
Property ID 9. Last change Update Sequence Number (USN) for this file.
PID_STG_NAME
Property ID 0x0a. The name of the file. Default type is VT_LPWSTR. The Indexing Service friendly name is "filename".
PID_STG_PATH
Property ID 0x0b. The complete path for a file. Default type is VT_LPWSTR. The Indexing Service friendly name is "path".
PID_STG_SIZE
Property ID 0x0c. The size of a file. Default type is VT_I8. The Indexing Service friendly name is "size".
PID_STG_ATTRIBUTES
Property ID 0x0d. The attribute flags for a file. Default type is VT_UI4. The Indexing Service friendly name is "attrib".
PID_STG_WRITETIME
Property ID 0x0e. The date and time of the last write to the file. Default type is VT_FILETIME. The Indexing Service friendly name is "write".
PID_STG_CREATETIME
Property ID 0x0f. The date and time the file was created. Default type is VT_FILETIME. The Indexing Service friendly name is "create".
PID_STG_ACCESSTIME
Property ID 0x10.The time of the last access to the file. Default type is VT_FILETIME. The Indexing Service friendly name is "access".
PID_STG_CHANGETIME
Property ID 0x11.The time of the last change to a file in an NTFS file system, including changes in the main data stream and secondary streams. Default type is VT_FILETIME. The Indexing Service friendly name is "change".
PID_STG_ALLOCSIZE
Property ID 0x12. File allocation size.
PID_STG_CONTENTS
Property ID 0x13. The contents of the file. This property is for query restrictions only; it cannot be retrieved in a query result. Default type is VT_LPWSTR. The Indexing Service friendly name is "contents".
PID_STG_SHORTNAME
Property ID 0x14. The short (8.3) file name for the file. Default type is VT_LPWSTR. The Indexing Service friendly name is "shortname".
PID_STG_MAX
Property ID 0x14. Identifies the last PID_STG constant assigned.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.

See Also

OLE DB Provider for Indexing Service


Structures

Indexing Service defines several structures for use with interfaces and functions. The structures include:

  • CI_STATE
  • CIPROPERTYDEF
  • FILTERREGION
  • FULLPROPSPEC
  • STAT_CHUNK


CI_STATE

The CI_STATE structure contains information about the current state of an Indexing Service catalog.

typedef struct _CI_STATE
{
  DWORD cbStruct;
  DWORD cWordList;
  DWORD cPersistentIndex;
  DWORD cQueries;
  DWORD cDocuments;
  DWORD cFreshTest;
  DWORD dwMergeProgress;
  DWORD eState;
  DWORD cFilteredDocuments;
  DWORD cTotalDocuments;
  DWORD cPendingScans;
  DWORD dwIndexSize;
  DWORD cUniqueKeys;
  DWORD cSecQDocuments;
  DWORD dwPropCacheSize;
}  CI_STATE;

Members

cbStruct
Size, in bytes, of this CI_STATE structure.
cWordList
Number of current word lists.
cPersistentIndex
Number of persistent indexes.
cQueries
Number of actively running queries.
cDocuments
Total number of documents waiting to be filtered.
cFreshTest
Number of unique documents in word lists and shadow indexes.
dwMergeProgress
Completion percentage of current merge, if one is running.
eState
State of content indexing as given by one or more of the CI_STATE_* constants.
cFilteredDocuments
Number of documents filtered since content indexing was begun.
cTotalDocuments
Total number of documents in the system.
cPendingScans
Number of pending scans, possibly one for each scope in the directories list. The value is usually zero, except immediately after content indexing has been started or after a notification queue overflows.
dwIndexSize
Size, in megabytes, of the index (excluding the property cache).
cUniqueKeys
Number of unique keys in the master index.
cSecQDocuments
Number of documents in the secondary queue, which contains documents that failed filtering due to a sharing violation.
dwPropCacheSize
Size, in megabytes, of the property cache.

Remarks

When using this structure, all members are output values. cbStruct is both an input value and an output value.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.

See Also

CIState, CI_STATE_* Constants


CIPROPERTYDEF

The CIPROPERTYDEF structure contains information about the friendly name, type, and property identifier (ID) information.

typedef struct tagCIPROPERTYDEF
{
  LPWSTR wcsFriendlyName;
  DWORD  dbType;
  DBID   dbCol;
}  CIPROPERTYDEF;

Members

wcsFriendlyName
Pointer to a null-terminated string that specifies the friendly name for a property. The friendly name can be used in an Indexing Service query, column list, or sort order parsed by the CITextToSelectTree function and the CITextToFullTree function. Friendly names must be entered in uppercase.
dbType
The data type for the property. This type is used when building a DBCOMMANDTREE structure for a restriction node. The same property with different friendly names can have different types. Its value must be either an OLE DB DBTYPE type or a PROPVARIANT variant type.
dbCol
The property ID for the property. Refer to the OLE DB Programmer's Reference in the Platform SDK for information about DBID structures. Indexing Service properties must be either DBKIND_GUID_NAME or DBKIND_GUID_PROPID.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.

See Also

CITextToFullTree, CITextToSelectTree, DBCOMMANDTREE, DBID, DBTYPE, OLE DB Programmer's Reference, PROPVARIANT


FILTERREGION

The FILTERREGION structure describes the position and extent of a specified portion of text within an object. This structure is used by the IFilter::BindRegion method.

typedef struct tagFILTERREGION
{
  ULONG idChunk;
  ULONG cwcStart;
  ULONG cwcExtent;
}  FILTERREGION;

Members

idChunk
Chunk ID.
cwcStart
Beginning of the region, specified as an offset from the beginning of the chunk.
cwcExtent
Extent of the region, specified as a number of Unicode characters.

Remarks

The cwcExtent member might specify a number of characters (starting from a position the cwcStart member specifies) that extends beyond the end of the chunk. In that case, the region should be continued into the next chunk, which should have the same attribute as the current region.

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.

See Also

IFilter::BindRegion


FULLPROPSPEC

The FULLPROPSPEC structure specifies a property set and a property within the property set.

typedef struct  tagFULLPROPSPEC
{
  GUID     guidPropSet;
  PROPSPEC psProperty;
}  FULLPROPSPEC;

Members

guidPropSet
The globally unique identifier (GUID) that identifies the property set.
psProperty
Pointer to the PROPSPEC structure that specifies a property either by its property identifier (propid) or by the associated string name (lpwstr).

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.

See Also

PROPSPEC, IFilter::Init


STAT_CHUNK

The STAT_CHUNK structure describes the characteristics of a chunk.

typedef struct tagSTAT_CHUNK
{
  ULONG              idChunk;
  CHUNK_BREAKTYPE    breakType;
  CHUNKSTATE         flags;
  LCID               locale;
  FULLPROPSPEC       attribute;
  ULONG              idChunkSource;
  ULONG              cwcStartSource;
  ULONG              cwcLenSource;
}  STAT_CHUNK;

Members

idChunk
The chunk identifier. Chunk identifiers must be unique for the current instance of the IFilter interface. Chunk identifiers must be in ascending order. The order in which chunks are numbered should correspond to the order in which they appear in the source document. Some search engines can take advantage of the proximity of chunks of various properties. If so, the order in which chunks with different properties are emitted will be important to the search engine.
breakType
The type of break that separates the previous chunk from the current chunk. Values are from the CHUNK_BREAKTYPE enumeration.
flags
Flags indicate whether this chunk contains a text-type or a value-type property. Flag values are taken from the CHUNKSTATE enumeration. If the CHUNK_TEXT flag is set, IFilter::GetText should be used to retrieve the contents of the chunk as a series of words. If the CHUNK_VALUE flag is set, IFilter::GetValue should be used to retrieve the value and treat it as a single property value. If the filter dictates that the same content be treated as both text and as a value, the chunk should be emitted twice in two different chunks, each with one flag set.
locale
The language and sublanguage associated with a chunk of text. Chunk locale is used by document indexers to perform proper word breaking of text. If the chunk is neither text-type nor a value-type with data type VT_LPWSTR, VT_LPSTR or VT_BSTR, this field is ignored.
attribute
The property to be applied to the chunk. If a filter requires that the same text have more than one property, it needs to emit the text once for each property in separate chunks.
idChunkSource
The ID of the source of a chunk. The value of the idChunkSource member depends on the nature of the chunk:
  • If the chunk is a text-type property, the value of the idChunkSource member must be the same as the value of the idChunk member.
  • If the chunk is an internal value-type property derived from textual content, the value of the idChunkSource member is the chunk ID for the text-type chunk from which it is derived.
  • If the filter attributes specify to return only internal value-type properties, there is no content chunk from which to derive the current internal value-type property. In this case, the value of the idChunkSource member must be set to zero, which is an invalid chunk.
cwcStartSource
The offset from which the source text for a derived chunk starts in the source chunk.
cwcLenSource
The length in characters of the source text from which the current chunk was derived. A zero value signifies character-by-character correspondence between the source text and the derived text. A nonzero value means that no such direct correspondence exists.

Remarks

The final three members (idChunkSource, cwcStartSource, and cwcLenSource) are used to describe the source of a derived chunk; that is, one that can be mapped back to a section of text. For example, the heading of a chapter can be both a text-type property and an internal value-type property — a heading. The value-type property "heading" would be a derived chunk. If the text of the current value-type chunk (from an internal value-type property) is derived from some text-type chunk, then it must be emitted more than once.

The following segment is an example of how this might happen in a book.

The small detective exclaimed, "C'est fini!"

Confessions

The room was silent for several minutes. After thinking very hard about it, the young woman asked, "But how did you know?"

This segment might be broken into chunks in the following way.

ID | Text | BreakType | Flags | Locale | Attribute
1 | The small dete | N/A | CHUNK_TEXT | ENGLISH_UK | CONTENT
2 | ctive exclaimed, | CHUNK_NO_ BREAK | N/A | N/A | N/A
3 | "C'est fini!" | CHUNK_EOW | CHUNK_TEXT | FRENCH_BELGIAN | CONTENT
4 | Confessions | CHUNK_EOC | CHUNK_TEXT | ENGLISH_UK | CHAPTER_ NAMES
5 | Confessions | CHUNK_EOP | CHUNK_TEXT | ENGLISH_UK | CONTENT
6 | The room was silent for several minutes. | CHUNK_EOP | CHUNK_TEXT | ENGLISH_UK | CONTENT
7 | After thinking very hard about it, the young woman asked, "But how did you know?" | CHUNK_EOS | CHUNK_TEXT | ENGLISH_UK | CONTENT

Information provided by idChunkSource, cwcStartSource, and cwcLenSource is useful for a search engine that highlights hits. If the query is done for an internal value-type property, the search engine will highlight the original text from which the text of the internal value-type property has been derived. For instance, in a C++ code filter, the browser, when searching for MyFunction in internal value-type property "function definitions," will highlight the function header in the file.

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.

See Also

CHUNK_BREAKTYPE, CHUNKSTATE, IFilter, IFilter::GetChunk, IFilter::GetText, IFilter::GetValue, CHUNK_BREAKTYPE


Enumerated Types

Indexing Service defines several enumerated types for use with interfaces and functions. The enumerations include:

  • CHUNK_BREAKTYPE
  • CHUNKSTATE
  • IFILTER_FLAGS
  • IFILTER_INIT


CHUNK_BREAKTYPE

The CHUNK_BREAKTYPE enumeration describes the type of break that separates the current chunk from the previous chunk.

typedef enum tagCHUNK_BREAKTYPE
{
  CHUNK_NO_BREAK = 0,
  CHUNK_EOW      = 1,
  CHUNK_EOS      = 2,
  CHUNK_EOP      = 3,
  CHUNK_EOC      = 4
}  CHUNK_BREAKTYPE;

Elements

CHUNK_NO_BREAK
No break is placed between the current chunk and the previous chunk. The chunks are glued together.
CHUNK_EOW
A word break is placed between this chunk and the previous chunk that had the same attribute. Use of CHUNK_EOW should be minimized because the choice of word breaks is language-dependent, so determining word breaks is best left to the search engine.
CHUNK_EOS
A sentence break is placed between this chunk and the previous chunk that had the same attribute.
CHUNK_EOP
A paragraph break is placed between this chunk and the previous chunk that had the same attribute.
CHUNK_EOC
A chapter break is placed between this chunk and the previous chunk that had the same attribute.

Remarks

A change in attributes implies a word, sentence, paragraph, or chapter break.

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.

See Also

IFilter::GetChunk, STAT_CHUNK


CHUNKSTATE

The CHUNKSTATE enumeration specifies whether the current chunk is a text-type property or a value-type property.

typedef enum tagCHUNKSTATE
{
  CHUNK_TEXT               = 0x1,
  CHUNK_VALUE              = 0x2,
  CHUNK_FILTER_OWNED_VALUE = 0x4
}  CHUNKSTATE;

Elements

CHUNK_TEXT
The current chunk is a text-type property.
CHUNK_VALUE
The current chunk is a value-type property.
CHUNK_FILTER_OWNED_VALUE
Reserved.

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.

See Also

IFilter::GetText, IFilter::GetChunk, STAT_CHUNK


IFILTER_FLAGS

The IFILTER_FLAGS enumeration indicates whether the caller should use the IPropertySetStorage and IPropertyStorage interfaces to locate additional properties.

typedef enum tagIFILTER_FLAGS
{
  IFILTER_FLAGS_OLE_PROPERTIES    = 1
}  IFILTER_FLAGS;

Elements

IFILTER_FLAGS_OLE_PROPERTIES
The caller should use the IPropertySetStorage and IPropertyStorage interfaces to locate additional properties. When this flag is set, properties available through COM enumerators should not be returned from IFilter.

Remarks

The pdwFlags parameter in the IFilter::Init method allows the IFilter implementation to pass information back to the caller. For Indexing Service 3.0, the only valid flag is IFILTER_FLAGS_OLE_PROPERTIES. If OLE properties should not be enumerated, then pdwFlags should be set to zero.

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.

See Also

IFilter, IFilter::Init, IPropertySetStorage, IPropertyStorage


IFILTER_INIT

The IFILTER_INIT enumeration contains flags that control:

  • Mapping of nonprinting character codes
  • Property output
  • Embedding scope
  • IFilter access patterns

The IFilter::Init method uses these flags to control the filtering process.

typedef enum tagIFILTER_INIT
{
  IFILTER_INIT_CANON_PARAGRAPHS          = 1,
  IFILTER_INIT_HARD_LINE_BREAKS          = 2,
  IFILTER_INIT_CANON_HYPHENS             = 4,
  IFILTER_INIT_CANON_SPACES              = 8,

  IFILTER_INIT_APPLY_INDEX_ATTRIBUTES    = 16,
  IFILTER_INIT_APPLY_CRAWL_ATTRIBUTES    = 256,
  IFILTER_INIT_APPLY_OTHER_ATTRIBUTES    = 32,
  IFILTER_INIT_INDEXING_ONLY             = 64,

  IFILTER_INIT_SEARCH_LINKS              = 128,

  IFILTER_INIT_FILTER_OWNED_VALUE_OK     = 512
}  IFILTER_INIT;

Elements

IFILTER_INIT_CANON_PARAGRAPHS
Paragraph breaks should be marked with the Unicode PARAGRAPH SEPARATOR (0x2029).
IFILTER_INIT_HARD_LINE_BREAKS
Soft returns, such as the newline character in Microsoft® Word, should be replaced by hard returns—LINE SEPARATOR (0x2028). Existing hard returns can be doubled. A carriage return (0x000D), line feed (0x000A), or the carriage return and line feed in combination should be considered a hard return. The intent is to enable pattern-expression matches that match against observed line breaks.
IFILTER_INIT_CANON_HYPHENS
Various word-processing programs have forms of hyphens that are not represented in the host character set, such as optional hyphens (appearing only at the end of a line) and nonbreaking hyphens. This flag indicates that optional hyphens are to be converted to nulls, and non-breaking hyphens are to be converted to normal hyphens (0x2010), or HYPHEN-MINUSES (0x002D).
IFILTER_INIT_CANON_SPACES
Just as the IFILTER_INIT_CANON_HYPHENS flag standardizes hyphens, this one standardizes spaces. All special space characters, such as nonbreaking spaces, are converted to the standard space character (0x0020).
IFILTER_INIT_APPLY_INDEX_ATTRIBUTES
Indicates that the client wants text split into chunks representing internal value-type properties.
IFILTER_INIT_APPLY_CRAWL_ATTRIBUTES
Indicates that the client wants text split into chunks representing properties determined during the indexing process.
IFILTER_INIT_APPLY_OTHER_ATTRIBUTES
Any properties not covered by the IFILTER_INIT_APPLY_INDEX_ATTRIBUTES and IFILTER_INIT_APPLY_CRAWL_ATTRIBUTES flags should be emitted.
IFILTER_INIT_INDEXING_ONLY
Optimizes IFilter for indexing because the client calls the IFilter::Init method only once and does not call IFilter::BindRegion. This eliminates the possibility of accessing a chunk both before and after accessing another chunk.
IFILTER_INIT_SEARCH_LINKS
The text extraction process must recursively search all linked objects within the document. If a link is unavailable, the IFilter::GetChunk call that would have obtained the first chunk of the link should return FILTER_E_LINK_UNAVAILABLE.
IFILTER_INIT_FILTER_OWNED_VALUE_OK
The content indexing process can return property values set by the filter.

Remarks

Generally, text output by the IFilter::GetText method should match exactly the actual text of the document. However, in order to achieve maximum interoperability, some standardization of common features is desirable. These features include paragraph breaks, line breaks, hyphens and spaces. IFilter interface servers can also embed null characters in text, which are nearly ignored by clients. That is, Unicode character 0x0000 is completely ignored and 0x0001 is treated as a word break.

Four flags control text standardization: IFILTER_INIT_CANON_PARAGRAPHS, IFILTER_INIT_HARD_LINE_BREAKS, IFILTER_INIT_CANON_HYPHENS, and IFILTER_INIT_CANON_SPACES.

Different clients of the IFilter interface want different views of an object. Three flags, IFILTER_INIT_APPLY_INDEX_ATTRIBUTES, IFILTER_INIT_APPLY_CRAWL_ATTRIBUTES, and IFILTER_INIT_APPLY_OTHER_ATTRIBUTES, control the set of properties that should be applied to chunks. In addition, specific properties can be requested in calls to the IFilter::Init method as an array of size cAttributes, stored in aAttributes.

IFilter interface implementations need to store some chunk information when operations other than content indexing occur. IFILTER_INIT_INDEXING_ONLY optimizes the filter for indexing.

For viewing purposes, it can be desirable to search across links as well as in the document and any objects it embeds. IFILTER_INIT_SEARCH_LINKS specifies recursively searching all links.

Certain IFilter interface implementations might generate property values during the content indexing process, and IFILTER_INIT_FILTER_OWNED_VALUE_OK indicates that it is OK to return these values.

Requirements

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
Windows 95/98: Unsupported.
Header: Declared in filter.h.

See Also

IFilter, IFilter::BindRegion, IFilter::GetChunk, IFilter::GetText, IFilter::Init, IFILTER_INIT


Constants

Indexing Service defines many constants for use with interfaces, functions, property sets, and structures. The constants include:

  • CICAT_* Constants
  • CI_STATE_* Constants
  • ISQLANG_* Constants
  • QUERY_* Scope Constants
  • STAT_* Constants


CICAT_* Constants

The CICAT_* constants are used to set and retrieve the state of an Indexing Service catalog. When setting the state, these values represent mutually exclusive states of the catalog and are not meant to be combined.

#define    CICAT_STOPPED     0x1
#define    CICAT_READONLY    0x2
#define    CICAT_WRITABLE    0x4
#define    CICAT_NO_QUERY    0x8
#define    CICAT_GET_STATE   0x10

Remarks

The following list describes the meaning of the constants:

CICAT_STOPPED
Stop the catalog. No querying or indexing can take place.
CICAT_READONLY
Set the catalog to read-only. Querying can take place, but indexing cannot.
CICAT_WRITABLE
Set the catalog to be writable. Both indexing and querying can take place.
CICAT_NO_QUERY
Set the catalog to a no-query state. Indexing can take place but querying cannot.
CICAT_GET_STATE
Retrieve the current state of the catalog.

The following table describes the various states possible for an Indexing Service catalog. You do not have to stop the catalog first to set its state. To retrieve only the current state, use a setting of CICAT_GET_STATE.

Desired State | CICAT_ Setting
Catalog stopped or offline | CICAT_STOPPED
Processing Queries only. | CICAT_READONLY
Querying and Indexing | CICAT_WRITABLE
Indexing only. | CICAT_NO_QUERY

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.

See Also

SetCatalogState


CI_STATE_* Constants

The CI_STATE_* constants reflect the state of the current activities of Indexing Service, including merges, scans, and performance indicators on the computer running the service.

#define CI_STATE_SHADOW_MERGE          0x1
#define CI_STATE_MASTER_MERGE          0x2
#define CI_STATE_CONTENT_SCAN_REQUIRED 0x4
#define CI_STATE_ANNEALING_MERGE       0x8
#define CI_STATE_SCANNING              0x10
#define CI_STATE_RECOVERING            0x20
#define CI_STATE_INDEX_MIGRATION_MERGE 0x40
#define CI_STATE_LOW_MEMORY            0x80
#define CI_STATE_HIGH_IO               0x100
#define CI_STATE_MASTER_MERGE_PAUSED   0x200
#define CI_STATE_READ_ONLY             0x400
#define CI_STATE_BATTERY_POWER         0X800
#define CI_STATE_USER_ACTIVE           0X1000
#define CI_STATE_STARTING              0X2000
#define CI_STATE_READING_USNS          0X4000

Remarks

The following list describes the meaning of the constants. If none of these constants is applicable, the indexing process is up to date and there are no documents in the queue to be indexed.

CI_STATE_SHADOW_MERGE
A shadow merge is in process.
CI_STATE_MASTER_MERGE
A master merge is in process.
CI_STATE_CONTENT_SCAN_REQUIRED
Some documents in the index have changed and Indexing Service needs to determine which have been added, changed, or deleted.
CI_STATE_ANNEALING_MERGE
An annealing merge is in process.
CI_STATE_SCANNING
A scan is in process.
CI_STATE_RECOVERING
The service is starting from the last saved state and is in the process of recovering.
CI_STATE_INDEX_MIGRATION_MERGE
The catalog is in the process of being merged for the purpose of migrating the catalog.
CI_STATE_LOW_MEMORY
Most of the virtual memory of the computer running Indexing Service is in use. The threshold for entering this state depends on the value of the MinWordlistMemory registry entry. In this state, indexing is paused, but queries continue to be accepted.
CI_STATE_HIGH_IO
The level of input/output (I/O) activity on the computer running Indexing Service is relatively high. The threshold for entering this state depends on the value of the MaxWordlistIo registry entry. In this state, indexing is paused, but queries continue to be accepted.
CI_STATE_MASTER_MERGE_PAUSED
The master merge that was in progress has been paused.
CI_STATE_READ_ONLY
The service has been manually paused.
CI_STATE_BATTERY_POWER
The service is paused to conserve battery lifetime. The threshold for entering this state depends on the value of the MinWordlistBattery registry entry.
CI_STATE_USER_ACTIVE
The service is paused due to high activity by the user (keyboard or mouse). The threshold for entering this state depends on the value of the WordlistUserIdle registry entry. In this state, indexing is paused, but queries are still accepted.
CI_STATE_STARTING
The service is starting. Queries can be run, but scanning and notification have not been enabled yet.
CI_STATE_READING_USNS
The service has not read the USN journal from one or more volumes being indexed. The index might not be up to date.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.

See Also

CiState, CI_STATE


ISQLANG_* Constants

The ISQLANG_* constants specify the dialect of the Indexing Service query language to use when creating the command text tree.

#define ISQLANG_V1   0x1
#define ISQLANG_V2   0x2

Remarks

The constants have the following meanings.

ISQLANG_V1
Use Dialect 1 of Indexing Service query language.
ISQLANG_V2
Use Dialect 2 of Indexing Service query language.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.

See Also

CITextToFullTreeEx, CITextToSelectTreeEx


QUERY_* Scope Constants

The QUERY_* scope constants are used to specify scope depths and scope restriction paths. You can combine these flags by choosing one value from the first pair (QUERY_SHALLOW or QUERY_DEEP) and one value from the second pair (QUERY_PHYSICAL_PATH or QUERY_VIRTUAL_PATH).

#define QUERY_SHALLOW        0
#define QUERY_DEEP           1

#define QUERY_PHYSICAL_PATH  0
#define QUERY_VIRTUAL_PATH   2

Remarks

The following list describes the meaning of the constants.

QUERY_SHALLOW
Only files in the scope directory are included in the results. Cannot be combined with QUERY_DEEP.
QUERY_DEEP
Files in the scope directory and all subdirectories are included in the results. Cannot be combined with QUERY_SHALLOW.
QUERY_PHYSICAL_PATH
The scope is a physical directory. Cannot be combined with QUERY_VIRTUAL_PATH.
QUERY_VIRTUAL_PATH
The scope is a virtual (Internet Information Services) directory. Cannot be combined with QUERY_PHYSICAL_PATH.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.

See Also

CiMakeCommand, DBPROPSET_FSCIFRMWRK_EXT


STAT_* Constants

The STAT_* constants indicate the execution (fill) status and the reliability status of a query.

// Bits 00-02:  Fill Status: How query data is being updated, if at all.
#define STAT_BUSY                       ( 0 )
#define STAT_ERROR                      ( 0x1 )
#define STAT_DONE                       ( 0x2 )
#define STAT_REFRESH                    ( 0x3 )

// Bits 03-15:  Reliability: How accurate the query result is.
#define STAT_PARTIAL_SCOPE              ( 0x8 )
#define STAT_NOISE_WORDS                ( 0x10 )
#define STAT_CONTENT_OUT_OF_DATE        ( 0x20 )
#define STAT_REFRESH_INCOMPLETE         ( 0x40 )
#define STAT_CONTENT_QUERY_INCOMPLETE   ( 0x80 )
#define STAT_TIME_LIMIT_EXCEEDED        ( 0x100 )
#define STAT_SHARING_VIOLATION          ( 0x200 )

// Macros for retrieving fill status and reliability status.
#define QUERY_FILL_STATUS(x)            ( ( x ) & 0x7 )
#define QUERY_RELIABILITY_STATUS(x)     ( ( x ) & 0xFFF8 )

Remarks

The STAT_* constants are returned by the MSIDXSPROP_ROWSETQUERYSTATUS property of the DBPROPSET_MSIDXS_ROWSETEXT property set.

The following list describes the meaning of the constants.

STAT_BUSY
The asynchronous query is still running.
STAT_ERROR
The query is in an error state.
STAT_DONE
The query is complete.
STAT_REFRESH
The query is complete, but updates are resulting in additional query computation.
STAT_PARTIAL_SCOPE
The results of the query are incomplete because one or more servers in a multivolume query were unavailable.
STAT_NOISE_WORDS
Noise words were replaced by wildcard characters in the content query.
STAT_CONTENT_OUT_OF_DATE
The results of the query might be incorrect because the query involved modified, but unindexed, files.
STAT_REFRESH_INCOMPLETE
The results of the query might be incorrect because the query involved modified and re-indexed files whose content wasn't included.
STAT_CONTENT_QUERY_INCOMPLETE
The content query was too complex to complete or required enumeration instead of use of the content index.
STAT_TIME_LIMIT_EXCEEDED
The results of the query might be incorrect because the query execution time reached the maximum allowable time.
STAT_SHARING_VIOLATION
The results of the query might be incorrect because a sharing violation occurred on the query result.

Example

This example retrieves the fill and reliability status values for the specified rowset.

XInterface<IRowsetInfo> xIRowsetInfo;
HRESULT hr = xIRowset->QueryInterface( IID_IRowsetInfo,
                                       xIRowsetInfo.GetQIPointer() );

if ( SUCCEEDED( hr ) )
{
    DBPROPID propId = MSIDXSPROP_ROWSETQUERYSTATUS;
    DBPROPIDSET propSet;
    propSet.rgPropertyIDs = &propId;
    propSet.cPropertyIDs = 1;
    const GUID guidRowsetExt = DBPROPSET_MSIDXS_ROWSETEXT;
    propSet.guidPropertySet = guidRowsetExt;

    ULONG cPropertySets = 0;
    DBPROPSET * pPropertySets;

    hr = xIRowsetInfo->GetProperties( 1,
                                      &propSet,
                                      &cPropertySets,
                                      &pPropertySets );

    if ( SUCCEEDED( hr ) )
    {
        DWORD dwStatus = pPropertySets->rgProperties->vValue.ulVal;

        CoTaskMemFree( pPropertySets->rgProperties );
        CoTaskMemFree( pPropertySets );

        DWORD dwFill = QUERY_FILL_STATUS( dwStatus );
        DWORD dwReliability = QUERY_RELIABILITY_STATUS( dwStatus );
    }
}

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in ntquery.h.

See Also

IRowsetInfo, DBPROPSET_MSIDXS_ROWSETEXT


Return Values

Indexing Service produces specific return values and error codes that relate to its processing of documents and catalogs, including filtering, word breaking, and querying. The range of return values for Indexing Service is 0xHHHH1600 to 0xHHHH1850, where HHHH is a hexadecimal value that depends on the severity code and facility code of each individual return value.

The following topics enumerate and describe the return values.

  • Query-Execution Values
  • Query-Parsing Values
  • Content-Indexing Values
  • Hit-Searching Values
  • Filter-Interface Values
  • Word-Breaking Values
  • Helper-Function Values


Query-Execution Values

Values 0xHHHH1600 to 0xHHHH164F are query return values produced when resolving a query string against the set of indexes in a catalog. These values are defined in the header file cierror.h. The following table gives the query-execution values in alphabetical order.

Value | Description
QUERY_E_ALLNOISE 0x80041605 | The query contained only ignored words.
QUERY_E_DIR_ON_REMOVABLE_DRIVE 0x8004160B | Specified directory is on a removable medium.
QUERY_E_DUPLICATE_OUTPUT_COLUMN 0x80041608 | One or more columns in the output column list is a duplicate.
QUERY_E_FAILED 0x80041600 | Call failed for unknown reason.
QUERY_E_INVALID_DIRECTORY 0x8004160A | Invalid directory name.
QUERY_E_INVALID_OUTPUT_COLUMN 0x80041609 | One or more columns in the output column list is not valid.
QUERY_E_INVALIDCATEGORIZE 0x80041604 | An invalid categorization order was requested.
QUERY_E_INVALIDQUERY 0x80041601 | Invalid parameter.
QUERY_E_INVALIDRESTRICTION 0x80041602 | The query restriction could not be parsed.
QUERY_E_INVALIDSORT 0x80041603 | An invalid sort order was requested.
QUERY_E_TIMEDOUT 0x80041607 | The query exceeded its execution time limit.
QUERY_E_TOOCOMPLEX 0x80041606 | The query was too complex to be executed.
QUERY_S_NO_QUERY 0x8004160C | The catalog is in a state where indexing continues, but queries are not allowed.


Query-Parsing Values

Values 0xHHHH1650 to 0xHHHH167F are query-return values produced by utilities in query.lib. These values are defined in the header file cierror.h. The following table gives the query-parsing values in alphabetical order.

Value | Description
QPARSE_E_EXPECTING_BRACE 0x80041666 | Expecting closing square bracket ']'.
QPARSE_E_EXPECTING_COMMA 0x80041671 | Expecting comma.
QPARSE_E_EXPECTING_CURRENCY 0x80041664 | Expecting currency.
QPARSE_E_EXPECTING_DATE 0x80041663 | Expecting date.
QPARSE_E_EXPECTING_EOS 0x80041670 | Expecting end of string.
QPARSE_E_EXPECTING_GUID 0x80041665 | Expecting GUID.
QPARSE_E_EXPECTING_INTEGER 0x80041661 | Expecting integer.
QPARSE_E_EXPECTING_PAREN 0x80041667 | Expecting closing parenthesis ')'.
QPARSE_E_EXPECTING_PHRASE 0x8004166A | Expecting phrase.
QPARSE_E_EXPECTING_PROPERTY 0x80041668 | Expecting property name.
QPARSE_E_EXPECTING_REAL 0x80041662 | Expecting real number.
QPARSE_E_EXPECTING_REGEX 0x8004166C | Expecting regular expression.
QPARSE_E_EXPECTING_REGEX_PROPERTY 0x8004166D | Regular expressions require a property of type string.
QPARSE_E_INVALID_GROUPING 0x80041677 | An unsupported grouping type was specified.
QPARSE_E_INVALID_LITERAL 0x8004166E | Invalid literal.
QPARSE_E_INVALID_QUERY 0x8004167A | Invalid query.
QPARSE_E_INVALID_RANKMETHOD 0x8004167BL | Invalid rank method.
QPARSE_E_INVALID_SORT_ORDER 0x80041675 | An invalid sort order was specified. Only [a] and [d] are supported.
QPARSE_E_NO_SUCH_PROPERTY 0x8004166F | No such property.
QPARSE_E_NO_SUCH_SORT_PROPERTY 0x80041674 | An invalid property was found in the sort specification.
QPARSE_E_NOT_YET_IMPLEMENTED 0x80041669 | Not yet implemented.
QPARSE_E_UNEXPECTED_EOS 0x80041672 | Unexpected end of string.
QPARSE_E_UNEXPECTED_NOT 0x80041660 | Unexpected NOT operator.
QPARSE_E_UNSUPPORTED_PROPERTY_TYPE 0x8004166BL | Unsupported property type.
QPARSE_E_WEIGHT_OUT_OF_RANGE 0x80041673 | Weight must be between 0 and 1000.
QPLIST_E_BAD_GUID 0x80041659 | Invalid GUID.
QPLIST_E_BYREF_USED_WITHOUT_PTRTYPE 0x8004165E | DBTYPE_BYREF must be used with DBTYPE_STR, DBTYPE_WSTR, DBTYPE_GUID or DBTYPE_UI1 types.
QPLIST_E_CANT_OPEN_FILE 0x80041651 | Cannot open file.
QPLIST_E_CANT_SET_PROPERTY 0x8004165B | Failed to set property name.
QPLIST_E_DUPLICATE 0x8004165C | Duplicate property name.
QPLIST_E_EXPECTING_CLOSE_PAREN 0x80041657 | Expecting closing parenthesis.
QPLIST_E_EXPECTING_GUID 0x80041658 | Expecting GUID.
QPLIST_E_EXPECTING_INTEGER 0x80041656 | Expecting integer.
QPLIST_E_EXPECTING_NAME 0x80041653 | Expecting property name.
QPLIST_E_EXPECTING_PROP_SPEC 0x8004165A | Expecting property specifier.
QPLIST_E_EXPECTING_TYPE 0x80041654 | Expecting type specifier.
QPLIST_E_READ_ERROR 0x80041652 | Read error in file.
QPLIST_E_UNRECOGNIZED_TYPE 0x80041655 | Unrecognized type.
QPLIST_E_VECTORBYREF_USED_ALONE 0x8004165D | DBTYPE_VECTOR or DBTYPE_BYREF used alone.
QPLIST_S_DUPLICATE 0x00041679 | Exact duplicate property defined.
QUTIL_E_CANT_CONVERT_VROOT 0x80041676 | Couldn't convert a virtual path to a physical path.
QUTIL_E_INVALID_CODEPAGE 0x80041678 | Invalid CiCodepage variable was specified.


Content-Indexing Values

Values 0xHHHH1680 to 0xHHHH169F and 0xHHHH1730 to 0xHHHH173F are return values produced by the Content-Indexing daemon (CiDaemon) as it filters documents and adds their word lists to the existing indexes in the catalog. These values are defined in the header file cierror.h. The following table gives the content-indexing values in alphabetical order.

Value | Description
FDAEMON_E_CHANGEUPDATEFAILED 0x80041684 | Documents not stored in content index because update of change list failed.
FDAEMON_E_FATALERROR 0x80041682 | A critical error occurred during document filtering. Consult system administrator.
FDAEMON_E_LOWRESOURCE 0x80041681 | The system is running out of one of more resources needed for filtering, usually memory.
FDAEMON_E_NOWORDLIST 0x80041687 | No wordlist is being constructed. May happen after fatal filter error.
FDAEMON_E_PARTITIONDELETED 0x80041683 | Documents not stored in content index because partition has been deleted.
FDAEMON_E_TOOMANYFILTEREDBLOCKS 0x80041688 | During document filtering the limit on buffers has been exceeded.
FDAEMON_E_WORDLISTCOMMITFAILED 0x80041686 | Commit of wordlist failed. Data not available for query.
FDAEMON_W_EMPTYWORDLIST 0x00041685 | Final wordlist was empty.
FDAEMON_W_WORDLISTFULL 0x00041680 | Wordlist has reached maximum size. Additional documents should not be filtered.
FILTER_E_ALREADY_OPEN 0x80041736 | A file is already open. Cannot open another one while file is open.
FILTER_E_CONTENTINDEXCORRUPT 0xC0041734 | The content index is corrupt. A content scan will to be scheduled after chkdsk or autochk is run.
FILTER_E_IN_USE 0x80041738 | The document is in use by another process.
FILTER_E_NO_SUCH_PROPERTY 0x8004173B | There is no property with the given GUID.
FILTER_E_NOT_OPEN 0x80041739 | The document is not opened.
FILTER_E_OFFLINE 0x8004173D | The document is offline.
FILTER_E_PARTIALLY_FILTERED 0x8004173E | The document was too large to filter in its entirety. Portions of the document were not emitted.
FILTER_E_TOO_BIG 0x80041730 | File is too large to filter.
FILTER_E_UNREACHABLE 0x80041737 | The file is not reachable.
FILTER_S_CONTENTSCAN_DELAYED 0x00041733 | A content scan of the disk needs to be scheduled for execution later.
FILTER_S_DISK_FULL 0x00041735 | The disk is getting full.
FILTER_S_FULL_CONTENTSCAN_IMMEDIATE 0x00041732 | A full content scan of the disk needs to be scheduled for immediate execution.
FILTER_S_NO_PROPSETS 0x0004173A | The document has no property sets.
FILTER_S_NO_SECURITY_DESCRIPTOR 0x0004173C | The document has no security descriptor.
FILTER_S_PARTIAL_CONTENTSCAN_IMMEDIATE 0x00041731 | A partial content scan of the disk needs to be scheduled for immediate execution.


Hit-Searching Values

Values 0xHHHH16A0 to 0xHHHH16AF are return values produced when searching for query hits. These values are defined in the header file cierror.h. The following table gives the hit-searching values in alphabetical order.

Value | Description
SEARCH_E_NOMONIKER 0x800416A1 | Retrieval of hits as monikers is not supported (by filter passed into IFilter::Init).
SEARCH_E_NOREGION 0x800416A2 | Retrieval of hits as filter regions is not supported (by filter passed into Init).
SEARCH_S_NOMOREHITS 0x000416A0 | End of hits has been reached.


Filter-Interface Values

Values 0xHHHH1700 to 0xHHHH172F are return values produced when calling the methods of the IFilter interface to extract the text from a document, including any embedded or linked objects within it. These values are defined in the header file filterr.h. The following table gives the filter-interface values in alphabetical order.

Value | Description
FILTER_E_ACCESS 0x80041703 | Unable to access object.
FILTER_E_EMBEDDING_UNAVAILABLE 0x80041707 | Unable to bind IFilter for embedded object.
FILTER_E_END_OF_CHUNKS 0x80041700 | No more chunks of text available in object.
FILTER_E_LINK_UNAVAILABLE 0x80041708 | Unable to bind IFilter for linked object.
FILTER_E_NO_MORE_TEXT 0x80041701 | No more text available in chunk.
FILTER_E_NO_MORE_VALUES 0x80041702 | No more property values available in chunk.
FILTER_E_NO_TEXT 0x80041705 | No text in current chunk.
FILTER_E_NO_VALUES 0x80041706 | No values in current chunk.
FILTER_E_PASSWORD 0x8004170B | File was not filtered due to password protection.
FILTER_E_UNKNOWNFORMAT 0x8004170C | The document format is not recognized by the filter.
FILTER_S_LAST_TEXT 0x00041709 | This is the last text in the current chunk.
FILTER_S_LAST_VALUES 0x0004170A | This is the last value in the current chunk.
FILTER_W_MONIKER_CLIPPED 0x00041704 | Moniker does not cover entire region.


Word-Breaking Values

Values 0xHHHH1780 to 0xHHHH179F are return values produced during word breaking. These values are defined in the header file cierror.h. The following table gives the word-breaking values in alphabetical order.

Value | Description
LANGUAGE_E_DATABASE_NOT_FOUND 0x80041784 | Language database/cache file could not be found.
LANGUAGE_S_LARGE_WORD 0x00041781 | Word larger than maximum length. May be truncated by word sink.
PSINK_E_INDEX_ONLY 0x80041791 | Feature only available in index mode.
PSINK_E_LARGE_ATTACHMENT 0x80041792 | Attachment type beyond valid range.
PSINK_E_QUERY_ONLY 0x80041790 | Feature only available in query mode.
PSINK_S_LARGE_WORD 0x00041793 | Word larger than maximum length. May be truncated by phrase sink.
WBREAK_E_BUFFER_TOO_SMALL 0x80041783 | Buffer too small to hold composed phrase.
WBREAK_E_END_OF_TEXT 0x80041780 | End of text reached in text source.
WBREAK_E_INIT_FAILED 0x80041785 | Initialization of word breaker failed.
WBREAK_E_QUERY_ONLY 0x80041782 | Feature only available in query mode.


Helper-Function Values

Values 0xHHHH1800 to 0xHHHH182F are return values produced by the content-indexing helper functions. These values are defined in the header file cierror.h. The following table gives the content-indexing helper-function values in alphabetical order.

Value | Description
CI_CORRUPT_CATALOG 0xC0041801 | The Content Index meta data is corrupt.
CI_CORRUPT_DATABASE 0xC0041800 | The Content Index is corrupt.
CI_CORRUPT_FILTER_BUFFER 0xC0041807 | The filter buffer is corrupt.
CI_E_ALREADY_INITIALIZED 0x8004180A | The object is already initialized.
CI_E_BUFFERTOOSMALL 0x8004180C | The buffer is too small.
CI_E_CARDINALITY_MISMATCH 0x80041827 | Mismatch in cardinality of machine(s)/catalog(s)/scope(s).
CI_E_CLIENT_FILTER_ABORT 0xC0041824 | Filtering of object was aborted by client.
CI_E_CONFIG_DISK_FULL 0x80041828 | The disk has reached its configured space limit.
CI_E_DISK_FULL 0x80041811 | The disk is full and the specified operation cannot be done.
CI_E_DUPLICATE_NOTIFICATION 0x80041817 | There were two notifications for the same workid.
CI_E_ENUMERATION_STARTED 0xC0041822 | Enumeration has already been started for this query.
CI_E_FILTERING_DISABLED 0x80041810 | Filtering is disabled in this content index.
CI_E_INVALID_FLAGS_COMBINATION 0x80041819 | The combination of flags specified is invalid.
CI_E_INVALID_STATE 0x8004180F | The object is not in a valid state.
CI_E_LOGON_FAILURE 0x8004181C | A logon permission violation caused a failure.
CI_E_NO_CATALOG 0x8004181D | There is no catalog.
CI_E_NOT_FOUND 0x80041815 | The object was not found.
CI_E_NOT_INITIALIZED 0x8004180B | The object is not initialized.
CI_E_NOT_RUNNING 0x80041820 | Service is not running.
CI_E_OUTOFSEQ_INCREMENT_DATA 0x8004181A | The incremental data given to load is not valid. It may be out of sequence.
CI_E_PROPERTY_NOT_CACHED 0x8004180D | The given property is not cached.
CI_E_PROPERTY_TOOLARGE 0xC0041823 | The specified variable length property is too large for the property cache.
CI_E_SHARING_VIOLATION 0x8004181B | A sharing or locking violation caused a failure.
CI_E_SHUTDOWN 0x80041812 | Content Index has been shut down.
CI_E_STRANGE_PAGEORSECTOR_SIZE 0x8004181E | Page size is not an integral multiple of the sector size of the volume where index is located.
CI_E_TIMEOUT 0x8004181F | Service is busy.
CI_E_UPDATES_DISABLED 0x80041818 | A document update was rejected because updates were disabled.
CI_E_USE_DEFAULT_PID 0x80041816 | The passed-in property ID is not supported.
CI_E_WORKID_NOTVALID 0x80041813 | The work ID is not valid.
CI_INCORRECT_VERSION 0xC0041821 | The Content Index data on disk is for the wrong version.
CI_INVALID_INDEX 0xC0041808 | The index is invalid.
CI_INVALID_PARTITION 0xC0041802 | The Content Index partition is invalid.
CI_INVALID_PRIORITY 0xC0041803 | The priority is invalid.
CI_NO_CATALOG 0xC0041806 | There is no catalog.
CI_NO_STARTING_KEY 0xC0041804 | There is no starting key.
CI_OUT_OF_INDEX_IDS 0xC0041805 | The Content Index is out of index ids.
CI_PROPSTORE_INCONSISTENCY 0xC0041809 | Inconsistency in property store detected.
CI_S_CAT_STOPPED 0x00041826 | The catalog has been stopped.
CI_S_END_OF_ENUMERATION 0x00041814 | There are no more documents to enumerate.
CI_S_NO_DOCSTORE 0x00041825 | For administrative connections from client without association to a docstore.
CI_S_WORKID_DELETED 0x0004180E | The workid is deleted.


Registry Entries

Indexing Service uses entries in the Microsoft® Windows® 2000 registry to control many performance and resource variables for indexing and querying. The registry also includes entries with path names for catalogs and their scopes, with names for files needed to process queries and create formatted results, and for flags that influence what information Indexing Service logs in the Windows 2000 event log. The registry also contains language-specific information for the language being indexed.

Indexing Service supplies the SetLongProperty, SetSZProperty, GetLongProperty, and GetSZProperty methods of the AdminIndexServer object for programmatically setting and retrieving Indexing Service registry entries. These methods work in programming environments that support automation, such as Microsoft Visual Basic®, Microsoft Visual Basic Scripting Edition (VBScript), and Microsoft JScript®.

Caution Changing the registry is equivalent to directly editing sectors on a hard disk. You can easily corrupt the configuration of your computer if you make any mistakes, which may in turn require you to reinstall Windows 2000 or Indexing Service. Use the utmost caution when changing registry entries, and try to limit your changes to entries that you cannot adjust through the user interface (UI).

Indexing Service registry entries group by functionality into the following categories.

  • Main Registry Entries. This group includes the majority of the entries. With the exception of the DefaultColumnFile entry, they are found under the key

    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\
    ContentIndex    .

    The DefaultColumnFile entry is found under the key

    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\
    ContentIndexCommon    .

  • Catalog, Property, and Scope Registry Entries. This group includes entries that define the catalog directories and scopes that determine what gets indexed for each catalog and cached properties. These registry entries are found under the key

    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\
    ContentIndex\Catalogs

    and its subkeys, one for each catalog.

  • Language-Specific Registry Entries. This group includes entries that control the parts of the indexing and query processes that are language-specific. These registry entries can be found under the key

    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\
    ContentIndex\Language.


Main Registry Entries

Most of the registry entries for Indexing Service are found under the key

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\
ContentIndex.

The DefaultColumnFile entry is found under the key

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\
ContentIndexCommon.

The main registry entries apply globally to all catalogs unless an entry with the same name exists under the Catalog subkey for a specific catalog. When an entry exists for a specific catalog, it takes precedence over the global, main registry entry. Some main registry entries cannot be overridden, as individually noted, but always apply globally.

The following table is an alphabetical list of the entries in this main registry group.

Entry name | Description
CiCatalogFlags | Controls file-modification notifications for scanning.
DaemonResponseTimeout | Time-out for CiDaemon.EXE, the indexing process, if indexing a corrupt file.
DefaultColumnFile | Full physical path and name of the file to read for column definitions in .asp files and in .idq files. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
DelayedFilterRetries | Number of times Indexing Service tries to index documents that could not be indexed on the first try.
DelayUsnReadOnLowResource | Controls reading the update sequence number (USN) journal during heavy use of resources.
DLLsToRegister | List of dynamic-link libraries (DLLs) that have DllRegisterServer called when Indexing Service starts. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
EventLogFlags | Controls types of events logged to Indexing Service event-message log.
FilterBufferSize | Sets the size in memory for a communication buffer of an Indexing Service filter process.
FilterDelayInterval | Determines time delay for controlling indexing resource use.
FilterDirectories | Controls the indexing of system properties for directories.
FilterFilesWithUnknownExtensions | Controls the indexing of files with unregistered extensions.
FilterIdleTimeout | Time after which unused filter DLLs loaded by the CiDaemon.exe process are released.
FilterRemainingThreshold | Delays when only a few files await filtering in order to control index resource use.
FilterRetries | Maximum retries allowed to index a file.
FilterRetryInterval | Time interval between indexing retries.
ForcedNetPathScanInterval | Time interval between forced scans on directories on paths with no notifications.
ForcePathAlias | Controls the conditions under which path aliasing is applied to query results.
GenerateCharacterization | Controls the creation of an abstract of a file.
IMAPSvcInstance | Instance number of the Internet Mail Access Protocol (IMAP) virtual server with virtual roots to index (Internet Information Services (IIS) only)
IsapiDateTimeFormatting | Specifies what form of date and time formatting is applied to ISAPI queries. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
IsapiDateTimeLocal | Specifies the time zone to use when formatting the date and time for ISAPI queries. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
IsapiDefaultCatalogDirectory | Default Indexing Service catalog name. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
IsapiMaxEntriesInQueryCache | Maximum number of cached queries. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
IsapiMaxRecordsInResultSet | Maximum number of rows that can be returned from a query made using ISAPI. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
IsapiQueryCachePurgeInterval | Time interval during which a query item persists in the cache. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
IsapiRequestQueueSize | Maximum number of query requests to queue when servicing query requests. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
IsapiRequestThresholdFactor | Multiplier for determining the maximum number of threads per server that simultaneously process query requests. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
IsAutoAlias | Controls whether file shares automatically have aliases.
IsEnumAllowed | Determines whether directory-enumeration can be used to execute a query.
IsIndexingIMAPSvc | Configuration flag to index IMAP servers for IIS.
IsIndexingNNTPSvc | Configuration flag to index Network News Transfer Protocol (NNTP) servers for IIS.
IsIndexingW3SVC | Configuration flag to index Web servers.
IsReadOnly | Specifies whether the catalog is query-only and is not updated.
LeaveCorruptCatalog | Specifies whether to clean up a corrupt catalog.
LowResourceCheckInterval | Time interval after which to check resource usage when creating word lists.
LowResourceSleep | Time interval that Indexing Service waits after low-resource conditions occur before retrying the affected processing.
MajorVersion | Indicates major version number of Indexing Service. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
MasterMergeCheckpointInterval | Interval for checkpoints used when master merge is restarted.
MasterMergeTime | Time of day to begin master merge.
MaxActiveQueryThreads | Maximum number of query threads for ISAPI queries.
MaxActiveRequestThreads | Maximum number of request threads. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
MaxAutoAliasRefresh | Frequency at which aliases for file shares are refreshed.
MaxCachedPipes | Maximum number of cached named pipes. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
MaxCatalogs | Maximum number of catalogs that can be open at one time. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
MaxCharacterization | Maximum number of characters in an abstract.
MaxDaemonVmUse | Maximum amount of pagefile space allocated to a swapped-out filter daemon.
MaxFilesizeFiltered | Maximum size of file to filter. If size is exceeded, only the properties of the document are filtered—not the content.
MaxFilesizeMultiplier | Multiplier for the maximum amount of index data allowable from a file before Indexing Service treats the file as invalid.
MaxFreshCount | Maximum number of files for which index data is not included in master index.
MaxFreshDeletes | Maximum number of files deleted from master index before master index is updated.
MaxIdealIndexes | Maximum number of indexes in a well-tuned system.
MaxIndexes | Maximum number of indexes in catalog.
MaxMergeInterval | Wait interval for Indexing Service between merges.
MaxPendingDocuments | Maximum number of documents not yet indexed before marking the index out of date for property queries.
MaxQueryExecutionTime | Maximum execution time for query before an error is reported.
MaxQueryTimeslice | Maximum query execution time for one time slice before another thread may be activated.
MaxQueueChunks | Maximum number of buffers used for unfiltered documents.
MaxRestrictionNodes | Maximum number of query restriction nodes.
MaxRunningWebhits | Maximum number of instances of the WEBHITS.DLL that can run concurrently for use by ISAPI with a Web server. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
MaxShadowFreeForceMerge | Maximum percentage of free disk space used by shadow indexes before a master merge is triggered.
MaxShadowIndexSize | Maximum percentage of disk space used by shadow indexes before a master merge is triggered.
MaxSimultaneousRequests | Maximum number of simultaneous query-request connections supported. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
MaxTextFilterBytes | Maximum amount of information the text filter can process from a single file with a well-known extension.
MaxUsnLogSize | Maximum size of the USN journal.
MaxWebhitsCpuTime | Time-out value for WEBHITS.DLL. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
MaxWordlistIo | Threshold of input/output (I/O) activity above which indexing is delayed.
MaxWordListIoDiskPerf | System I/O threshold above which indexing is delayed when disk-performance counters are enabled.
MaxWordLists | Maximum number of word lists before Indexing Service merges them to the master index.
MaxWordlistSize | Maximum amount of memory for one word list.
MinClientIdleTime | Amount of time a query client connection can be idle before the connection is dropped. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
MinDiskFreeForceMerge | Minimum percentage of free disk space available before a master merge is triggered.
MinDiskSpaceToLeave | Minimum amount of free disk space to leave on a disk.
MinIdleQueryThreads | Minimum number of idle threads available for queries.
MinIdleRequestThreads | Minimum number of idle threads available for indexing. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
MinimizeWorkingSet | Flag to minimize requested working set for Indexing Service. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
MinMergeIdleTime | Minimum percentage of average system idle time to allow annealing merges.
MinorVersion | Minor version of Indexing Service.
MinSizeMergeWordlists | Minimum combined size of word lists to force shadow merge.
MinWordlistBattery | Minimum percentage of battery life required to keep indexing active.
MinWordlistMemory | Minimum free memory available for new word lists.
NNTPSvcInstance | Instance identifier (ID) for the NNTP server.
PropertyStoreBackupSize | Size of memory allocation for primary property-cache backup on disk.
PropertyStoreMappedCache | Maximum number of pages in memory for the primary property cache.
RequestTimeout | For query clients, time to wait before named pipe instance request fails. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
ScanBackoff | Controls the use of system resources by Indexing Service during scans.
SecPropertyStoreBackupSize | Size of memory allocation for secondary property cache backup.
SecPropertyStoreMappedCache | Maximum number of pages in memory for the secondary property cache.
StartupDelay | Delay to let system start before initiating Indexing Service. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
StompLastAccessDelay | Controls updating of the last access time property of a file being indexed.
ThreadClassFilter | Priority class of the indexing process (CiDaemon.exe).
ThreadPriorityFilter | Priority level of the filtering thread within the indexing process.
ThreadPriorityMerge | Priority level of the merge thread within the indexing process.
UsnLogAllocationDelta | Allocation to remove from front of the USN journal to make room to write more entries.
UsnReadMinSize | Specifies the minimum size that the USN journal must attain before processing of change notifications proceeds.
UsnReadTimeout | Specifies the maximum interval of time to wait before processing change notifications in the USN journal.
W3SvcInstance | Instance ID of the World Wide Web (WWW) server being indexed.
WebhitsDisplayScript | Controls whether to include scripting code in hit-highlighting results. Cannot be overridden by an identically named entry under the Catalog subkey for a specific catalog.
WordlistUserIdle | User idle time required before filtering runs.


CiCatalogFlags

The CiCatalogFlags entry controls whether Indexing Service receives file-modification notifications from local or remote hosts.

Summary

Type: | REG_DWORD
Default: | 0x00000000 (Enable all notifications)
Range: | 0x00000000 – 0x00000003

Remarks

The CiCatalogFlags entry enables all notifications when set to 0x00000000. When nonzero, it can be either of the following mask values or the logical OR operation of the two.

Mask Value | Effect on Notifications
0x00000001 | Disable notification processing for all remote universal naming convention (UNC) paths. Set this flag if Indexing Service is configured to index documents on a wide area network (WAN) over slow links.
0x00000002 | Disable notification processing for all local paths.

When either or both of remote and local notification processing is disabled, Indexing Service triggers periodic scans for the disabled paths. The registry entry ForcedNetPathScanInterval controls the frequency of scanning disabled paths.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


DaemonResponseTimeout

The DaemonResponseTimeout entry is a time-out interval that is used to determine whether the CiDaemon.exe indexing process is looping because of a corrupted file.

Summary

Type: | REG_DWORD
Units: | Minutes
Default: | 5
Range: | 1 – 120

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


DefaultColumnFile

The DefaultColumnFile entry is the full physical path and name of the file to read for column definitions in .asp files and in .idq files.

Summary

Type: | REG_SZ
Default: | ""

Remarks

The DefaultColumnFile entry is found under the key

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\
ContentIndexCommon.

If the value of the DefaultColumnFile entry is the default, the columns (properties) available for queries are those given in the topic Default Property Names for a Web Catalog.

If a value other than the default is specified, the specified column definitions file includes one line for each column (or property) that can be used in a query. The content and format of the columns definition file is identical to that given in the topic Names Section of .Idq Files.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


DelayedFilterRetries

The DelayedFilterRetries entry controls the number of times Indexing Service tries to index a document that has been placed in the secondary indexing queue because the first attempt to index it failed.

Summary

Type: | REG_DWORD
Units: | Retries
Default: | 240
Range: | 0 – 32000

See Also

Catalog, Property, and Scope Registry Entries, FilterRetryInterval, Main Registry Entries


DelayUsnReadOnLowResource

The DelayUsnReadOnLowResource entry controls whether the USN journal, also known as the change-notification log, is examined under the following system conditions: low memory, high input/output (I/O), recent user activity, and running on battery power.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 1
Range: | 0, 1

Remarks

Set the value of the DelayUsnReadOnLowResource entry to one to prevent the reading of the USN journal as long as any of the system conditions exist.

Since indexing does not occur during these conditions, there's no point in examining the USN journal unless the journal has a fixed size (MaxUsnLogSize) and is about to become full. When this happens, the data being written to the journal wraps around, and a beginning block (USNLogAllocationDelta) is deleted to make room for more data. As a result, change notifications may be lost. If this seems likely, Indexing Service gives checking the USN journal a higher priority even if you have set this entry.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


DLLsToRegister

The DLLsToRegister entry determines which DLLs Indexing Service registers with a call to DllRegisterServer.

Summary

Type: | REG_MULTI_SZ
Default: | In the system default directory, QUERY.DLL, CIADMIN.DLL, IXSSO.DLL, CIODM.DLL, INFOSOFT.DLL, NLHTML.DLL, and OFFFILT.DLL.
Range: | May include any filter DLLs, including ones supplied by independent software vendors.

Remarks

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


EventLogFlags

The EventLogFlags entry controls the types of events that are logged to the system event message log.

Summary

Type: | REG_DWORD
Default: | 0x00000002
Range: | 0x00000000 – 0x00000003

Remarks

The EventLogFlags entry disables all the relevant event message types when set to 0x00000000. When nonzero, it can be either of the following mask values or the logical OR operation of the two.

Mask Value | Controlled Event
0x00000001 | Reserved.
0x00000002 | One or more embedded objects in a document could not be filtered.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


FilterBufferSize

The value of the FilterBufferSize entry sets the size in memory for a communication buffer of an Indexing Service filter process.

Summary

Type: | REG_DWORD
Units: | Kilobytes
Default: | 128
Range: | 64 – 1024

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


FilterDelayInterval

The FilterDelayInterval entry determines the number of seconds to suspend filtering when the number of documents left to filter equals the value in the FilterRemainingThreshold entry.

Summary

Type: | REG_DWORD
Units: | Seconds
Default: | 20
Range: | 0 – 600

Remarks

The FilterDelayInterval value can prevent Indexing Service from overusing resources while trying to index temporary files created by running applications. Increase the value of this entry if filtering certain files uses more resources than allowed.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


FilterDirectories

The FilterDirectories entry controls whether directories are filtered for system properties.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 1
Range: | 0, 1

Remarks

Set the value of the FilterDirectories entry to zero to have Indexing Service ignore directory properties. Set it to a nonzero value to filter and display the properties of directories in query results.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


FilterFilesWithUnknownExtensions

The FilterFilesWithUnknownExtensions entry determines whether files with extensions that have not been registered will be filtered.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 1
Range: | 0, 1

Remarks

Set the value of the FilterFilesWithUnknownExtensions entry to zero if only registered file types are to be filtered. Set the value to one if unregistered file types are also to be filtered.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


FilterIdleTimeOut

The FilterIdleTimeOut entry controls the time interval after which unused IFilter DLLs loaded by the CiDaemon.exe process are released.

Summary

Type: | REG_DWORD
Units: | Milliseconds
Default: | 900,000 (15 minutes)
Range: | 0 – 4294967295 (0xFFFFFFFF)

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


FilterRemainingThreshold

The FilterRemainingThreshold entry delays filtering if the number of documents to be filtered is less than the number of files set in the value of this registry entry.

Summary

Type: | REG_DWORD
Units: | Files
Default: | 32
Range: | 0 – 320

Remarks

The delay specified by the value of the FilterRemainingThreshold entry prevents Indexing Service from overusing resources while trying to index temporary files created by running applications.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


FilterRetries

The FilterRetries entry determines the maximum number of times Indexing Service will try to filter a file after the initial filtering attempt fails.

Summary

Type: | REG_DWORD
Units: | Retries
Default: | 4
Range: | 1 – 10

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


FilterRetryInterval

The FilterRetryInterval entry is the time interval between attempts to filter the contents of a file that is being used by another process.

Summary

Type: | REG_DWORD
Units: | Minutes
Default: | 30
Range: | 2 – 240

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


ForcedNetPathScanInterval

The ForcedNetPathScanInterval entry is the time interval between forced scans on paths without file-modification notifications.

Summary

Type: | REG_DWORD
Units: | Minutes
Default: | 120
Range: | 10 – 16777215 (0x00FFFFFF)

Remarks

The CiCatalogFlags entry controls whether Indexing Service receives file-modification notifications from local or remote hosts.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


ForcePathAlias

The ForcePathAlias entry controls under what conditions path aliasing is applied to query results.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 0
Range: | 0. 1

Remarks

Set the value of the ForcePathAlias entry to zero if query results are to undergo path aliasing only for remote query clients. Set the value to one if query results are to undergo path aliasing for both local and remote query clients.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


GenerateCharacterization

The GenerateCharacterization entry controls whether Indexing Service automatically generates characterizations (also known as abstracts) for files that it indexes.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 1
Range: | 0, 1

Remarks

The results of setting the GenerateCharacterization entry to a value of zero can also be attained by setting the MaxCharacterization entry to a value of zero.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


IMAPSvcInstance

The IMAPSvcInstance entry is the instance number of the Internet Mail Access Protocol (IMAP) virtual server that contains virtual roots to index.

Summary

Type: | REG_DWORD
Default: | 1
Range: | 1 – 4294967295 (0xFFFFFFFF)

Remarks

The value of the IMAPSvcInstance entry applies only to virtual mail servers of IIS and only if the value of the IsIndexingIMAPSvc entry is set to one.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


IsapiDateTimeFormatting

The IsapiDateTimeFormatting entry specifies which form of date and time formatting is applied for ISAPI queries.

Summary

Type: | REG_DWORD
Default: | 1
Range: | 0 – 2

Remarks

The value of the IsapiDateTimeFormatting entry can be one of the following values.

Value | Formatting
0 | Use the locale of the user issuing the query. This is the default behavior for Index Server 1.x and 2.0.
1 | Use the default locale of the Indexing Service system.
2 | Use a hard-coded, non-configurable format of the form 1999/12/31 23:59:59.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

IsapiDateTimeLocal, Main Registry Entries


IsapiDateTimeLocal

The IsapiDateTimeLocal entry specifies the time zone to use when formatting the date and time for ISAPI queries.

Summary

Type: | REG_DWORD
Default: | 0
Range: | 0 – 1

Remarks

The value of the IsapiDateTimeLocal entry can be one of the following values.

Value | Formatting
0 | Display the date and time as Coordinated Universal Time (UTC). This is the default behavior for Index Server 1.x and 2.0.
1 | Display the date and time in the local time zone of the system that processes the query.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

IsapiDateTimeFormatting, Main Registry Entries


IsapiDefaultCatalogDirectory

The IsapiDefaultCatalogDirectory entry sets the default Indexing Service catalog name as it would be entered in the CiCatalog entry of an .idq file.

Summary

Type: | REG_SZ
Default: | "System"

Remarks

The value of the IsapiDefaultCatalogDirectory entry is also used by the Query object when the Query.Catalog property is not set.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


IsapiMaxEntriesInQueryCache

The IsapiMaxEntriesInQueryCache entry determines the maximum number of cached queries.

Summary

Type: | REG_DWORD
Units: | Queries
Default: | 10
Range: | 0 – 100

Remarks

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries, MaxSimultaneousRequests


IsapiMaxRecordsInResultSet

The IsapiMaxRecordsInResultSet entry is the maximum number of rows in the result set generated when processing a query made using ISAPI.

Summary

Type: | REG_DWORD
Units: | Rows
Default: | 5,000
Range: | 0 – 1000000

Remarks

The value of the IsapiMaxRecordsInResultSet entry applies only to queries made using ISAPI and not to queries made using OLE DB.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


IsapiQueryCachePurgeInterval

The IsapiQueryCachePurgeInterval entry is the time interval during which a query item persists in the cache.

Summary

Type: | REG_DWORD
Units: | Minutes
Default: | 5
Range: | 1 – 120

Remarks

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


IsapiRequestQueueSize

The IsapiRequestQueueSize entry is the maximum number of server query requests to queue while Indexing Service is busy with other queries.

Summary

Type: | REG_DWORD
Units: | Requests
Default: | 16
Range: | 0 – 100000

Remarks

If the number of query requests exceeds the value of the IsapiRequestQueueSize entry, subsequent query requests fail. To allow simultaneous queuing of more queries, increase this value.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

IsapiRequestThresholdFactor, Main Registry Entries


IsapiRequestThresholdFactor

The IsapiRequestThresholdFactor entry is a multiplier for determining the maximum number of threads per server that simultaneously process query requests.

Summary

Type: | REG_DWORD
Default: | 3
Range: | 1 – 100000

Remarks

The maximum number of threads for processing query requests is the product of the value of the IsapiRequestThresholdFactor entry and the number of processors on the server. If the number of threads required exceeds that product, subsequent query requests are queued. To allow simultaneous processing of more queries, increase the value of IsapiRequestThresholdFactor.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

IsapiRequestQueueSize, Main Registry Entries


IsAutoAlias

The IsAutoAlias entry controls whether Indexing Service automatically creates aliases for file shares.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 1
Range: | 0, 1

Remarks

Set the value of the IsAutoAlias entry to one to enable aliasing. Aliasing is a convenience for users accessing remote shares because it allows such users to get a friendly UNC path.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


IsEnumAllowed

The IsEnumAllowed entry determines whether directory enumeration can be used to execute a query.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 1
Range: | 0, 1

Remarks

The value of the IsEnumAllowed entry overrides any value set in a specific query.

Setting the value of this entry to zero reduces the vulnerability of a server to misdirected enumeration queries, since enumeration queries can be slow and can seriously affect the performance of the server.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


IsIndexingIMAPSvc

The IsIndexingIMAPSvc entry determines whether Indexing Service configures itself to work with Internet Mail Access Protocol (IMAP) mail messages.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 0
Range: | 0, 1

Remarks

Set the value of the IsIndexingIMAPSvc entry to one to configure the catalog to work with IMAP mail. Set it to zero to bypass indexing of IMAP mail.

When the value of this entry is set to one, the virtual server specified by the IMAPSvcInstance is indexed.

See Also

Catalog, Property, and Scope Registry Entries, IMAPSvcInstance, Main Registry Entries


IsIndexingNNTPSvc

The IsIndexingNNTPSvc entry determines whether Indexing Service configures itself to work with Network News Transfer Protocol (NNTP) messages.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 0
Range: | 0, 1

Remarks

Set the value of the IsIndexingNNTPSvc entry to one to configure the catalog to work with NNTP messages. Set it to zero to bypass indexing of NNTP messages.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


IsIndexingW3SVC

The IsIndexingW3SVC entry determines whether Indexing Service configures itself to index the files on Web servers.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 1
Range: | 0, 1

Remarks

Set the value of the IsIndexingW3SVC entry to one to configure the catalog to work with Web servers. Set it to zero to bypass indexing of Web servers.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


IsReadOnly

The IsReadOnly entry specifies whether the catalog is query-only.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 0
Range: | 0, 1

Remarks

Setting the value of the IsReadOnly entry to one prevents updates to the catalog, but allows queries against the catalog.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


LeaveCorruptCatalog

The LeaveCorruptCatalog entry specifies whether to clean up a corrupt catalog.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 0
Range: | 0, 1

Remark

The LeaveCorruptCatalog entry is meant primarily for debugging purposes.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


LowResourceCheckInterval

The LowResourceCheckInterval entry is the minimum time interval available for creating wordlists during the indexing process before Indexing Service checks system resources.

Summary

Type: | REG_DWORD
Units: | Seconds
Default: | 60
Range: | 5 – 4294967295 (0xFFFFFFFF)

Remarks

After an interval specified by the value of the LowResourceCheckInterval entry passes, the indexing process checks system resource limitations such as low memory or heavy I/O initiated by the end user.

See Also

Catalog, Property, and Scope Registry Entries, LowResourceSleep, Main Registry Entries


LowResourceSleep

The LowResourceSleep entry is the time interval that Indexing Service waits after low-resource conditions occur before retrying the affected processing.

Summary

Type: | REG_DWORD
Units: | Seconds
Default: | 180
Range: | 5 – 1200

Remarks

When system resource limitations (such as low memory or heavy I/O initiated by the end user) occur, Indexing Service suspends processing for a time interval equal to the value of the LowResourceSleep entry before trying to resume the processing.

See Also

Catalog, Property, and Scope Registry Entries, LowResourceCheckInterval, Main Registry Entries


MajorVersion

The MajorVersion entry indicates the major version number of the installed Indexing Service.

Summary

Type: | REG_DWORD
Default: | 3
Range: | 1 – 4294967295 (0xFFFFFFFF)

Remarks

The complete version of Indexing Service is the value of MajorVersion combined with the value of the MinorVersion entry. For example, if there were a Version 3.1, the value of this entry would be 3.

This entry should not be changed except by installation of an upgraded version of Indexing Service.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


MasterMergeCheckpointInterval

The MasterMergeCheckpointInterval entry is the amount of information indexed before Indexing Service generates a checkpoint for a master merge.

Summary

Type: | REG_DWORD
Units: | Kilobytes
Default: | 2048
Range: | 256 – 4096

Remarks

The value of the MasterMergeCheckpointInterval entry determines how much work (data written to the new master index) needs to be redone if a master merge is paused and restarted.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MasterMergeTime

The MasterMergeTime entry indicates the time (represented as the number of minutes after midnight) at which a master merge will occur.

Summary

Type: | REG_DWORD
Units: | Minutes
Default: | 0
Range: | 0 – 1439

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxActiveQueryThreads

The MaxActiveQueryThreads entry is the maximum number of active threads to process queries made using ISAPI.

Summary

Type: | REG_DWORD
Units: | Threads
Default: | 2
Range: | 1 – 1000

Remarks

The product of the value of the MaxActiveQueryThreads entry and the value of the IsapiRequestThresholdFactor entry establishes the maximum number of concurrently processed asynchronous queries made using ISAPI.

See Also

Catalog, Property, and Scope Registry Entries, IsapiRequestThresholdFactor, Main Registry Entries, MinIdleQueryThreads


MaxActiveRequestThreads

The MaxActiveRequestThreads entry is the maximum number of active threads to process incoming requests to Indexing Service.

Summary

Type: | REG_DWORD
Units: | Threads
Default: | 2
Range: | 1 – 1000

Remarks

Request types include queries, query result retrievals, and administrative operations.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries, MinIdleRequestThreads


MaxAutoAliasRefresh

The MaxAutoAliasRefresh entry is the frequency with which Indexing Service refreshes aliases for file shares.

Summary

Type: | REG_DWORD
Units: | Minutes
Default: | 15
Range: | 0 – 10080 (one week)

See Also

Catalog, Property, and Scope Registry Entries, IsAutoAlias, Main Registry Entries


MaxCachedPipes

The MaxCachedPipes entry is the maximum number of unconnected instances of named pipes that Indexing Service needs to keep cached.

Summary

Type: | REG_DWORD
Units: | Named pipes
Default: | 3
Range: | 0 – 1000

Remarks

Because instances of named pipes take up system resources, only the amount needed should be cached for a short period of time.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


MaxCatalogs

The MaxCatalogs entry is the maximum number of catalogs that Indexing Service can open at one time.

Summary

Type: | REG_DWORD
Units: | Catalogs
Default: | 33
Range: | 1 – 1000

Remarks

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


MaxCharacterization

The MaxCharacterization entry is the number of characters in the automatically generated characterizations (also known as an abstracts) of files that Indexing Service indexes.

Summary

Type: | REG_DWORD
Units: | Characters
Default: | 160
Range: | 0 – 500

Remarks

Setting the value of the MaxCharacterization entry to zero disables the generation of characterizations. This is equivalent to setting the value of the GenerateCharacterization entry to a value of zero.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxDaemonVmUse

The MaxDaemonVmUse entry is the maximum amount of page-file space allocated to virtual memory for a filter daemon.

Summary

Type: | REG_DWORD
Units: | Kilobytes
Default: | 40960 (40 MB)
Range: | 10240 – 4194303 (10 MB to 4 GB - 1 byte)

Remarks

Attempted allocations beyond the value of the MaxDaemonVmUse entry will fail.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxFilesizeFiltered

The MaxFilesizeFiltered entry is the maximum size of a file that the default filter will process for contents.

Summary

Type: | REG_DWORD
Units: | Kilobytes
Default: | 256

Remarks

If the default filter is used for a file that is bigger than the value of the MaxFilesizeFiltered entry, only the file properties are filtered.

This limit does not apply for the filtering of registered file types.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxFilesizeMultiplier

The MaxFilesizeMultiplier entry determines the maximum amount of data that can be generated from a single file, based on its size.

Summary

Type: | REG_DWORD
Default: | 8
Range: | 4 – 4294967295 (0xFFFFFFFF)

Remarks

The value of the MaxFilesizeMultiplier entry is a multiplier, which means that a value of four indicates that a file can generate up to four times its size in Indexing Service data. The use of this value allows a graceful recovery from indexing certain kinds of corrupt files.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxFreshCount

The MaxFreshCount entry is the maximum number of files for which the latest indexed data is not in the master index.

Summary

Type: | REG_DWORD
Units: | Files
Default: | 20000
Range: | 1000 – 4294967295 (0xFFFFFFFF)

Remarks

When the value of the MaxFreshCount entry is reached, a master merge is started.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxFreshDeletes

The MaxFreshDeletes entry is the maximum number of files deleted from the master index before the master index is updated.

Summary

Type: | REG_DWORD
Units: | Files
Default: | 320
Range: | 10 – 4294967295 (0xFFFFFFFF)

Remarks

When the value of the MaxFreshDeletes entry is reached, a merge is started.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxIdealIndexes

The MaxIdealIndexes entry is the maximum number of indexes considered acceptable in a well-tuned system.

Summary

Type: | REG_DWORD
Units: | Indexes
Default: | 5
Range: | 2 – 100

Remarks

When the number of indexes exceeds the value of the MaxIdealIndexes entry and the system is idle, an annealing merge takes place to bring the total count of indexes back to this number or lower.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxIndexes

The MaxIndexes entry is the maximum number of persistent indexes allowed in the catalog.

Summary

Type: | REG_DWORD
Units: | Indexes
Default: | 25
Range: | 10 – 150

Remarks

Usually, a shadow merge combines all existing word lists into a new shadow index. When the total number of indexes exceeds the value of the MaxIndexes entry, a shadow merge is performed to bring the total below this number.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxMergeInterval

The MaxMergeInterval entry is the time interval to wait between merges.

Summary

Type: | REG_DWORD
Units: | Minutes
Default: | 10
Range: | 1 – 60

Remarks

After an interval equal to the value of the MaxMergeInterval entry, Indexing Service determines whether a merge is necessary. When necessary, Indexing Service usually performs an annealing merge, but it may be a shadow merge or master merge.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxPendingDocuments

The MaxPendingDocuments entry is the maximum number of documents waiting to be filtered before the index is considered out-of-date for property queries.

Summary

Type: | REG_DWORD
Units: | Documents
Default: | 32
Range: | 1 – 50000

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxQueryExecutionTime

The MaxQueryExecutionTime entry is the maximum amount of execution time allowed for a query.

Summary

Type: | REG_DWORD
Units: | Milliseconds of CPU time
Default: | 10000 (10 seconds)
Range: | 0 – 4294967295 (0xFFFFFFFF)

Remarks

If a query takes more CPU time than specified by the value of the MaxQueryExecutionTime entry, processing of the query stops and an error status is returned. The value of zero specifies either that there is no limit for Indexing Service processing or that the client specifies the limit.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxQueryTimeslice

The MaxQueryTimeslice entry is the maximum amount of query execution time for a single time slice.

Summary

Type: | REG_DWORD
Units: | Milliseconds of CPU time
Default: | 50
Range: | 1 – 1000

Remarks

If the number of active asynchronous queries is greater than the number of allowed query threads, a query is put back on the pending queue at the end of the time interval specified by the value of the MaxQueryTimeslice entry. The end of a time slice usually occurs only after a matching row is found for the query. For some queries, however, many rows may be examined before a match is found. In these cases, the time slice can be exceeded before the time is checked.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxQueueChunks

The MaxQueueChunks entry is the maximum number of buffers in memory that can be used for keeping track of unfiltered documents.

Summary

Type: | REG_DWORD
Units: | Buffers
Default: | 20
Range: | 10 – 30

Remarks

The larger the value of the MaxQueueChunks entry, the less frequently data needs to be written to disk.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxRestrictionNodes

The MaxRestrictionNodes entry is the maximum number of query restriction nodes that can be created by Indexing Service in a single query.

Summary

Type: | REG_DWORD
Units: | Nodes
Default: | 5000
Range: | 1 – 4294967295 (0xFFFFFFFF)

Remarks

If query normalization creates a query restriction that is greater than the value of the MaxRestrictionNodes entry, the query fails with the status of QUERY_E_TOOCOMPLEX. This status message means the query was too complex to be completed because it surpassed the limit imposed in this registry key. The value of this entry keeps a user from overloading the capacity of the server with a complex query.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxRunningWebhits

The MaxRunningWebhits entry specifies the maximum number of concurrent instances of WEBHITS.DLL for use by ISAPI with a Web server.

Summary

Type: | REG_DWORD
Default: | 20
Range: | 1 – 200

Remarks

Increase the value of the MaxRunningWebhits entry for computers with more memory or processors.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


MaxShadowFreeForceMerge

The MaxShadowFreeForceMerge entry specifies the percentage of available disk space that can be used by shadow indexes on a catalog drive before a master merge is triggered.

Summary

Type: | REG_DWORD
Units: | Percent
Default: | 20
Range: | 5 – 100

Remarks

If the percentage of disk space used by shadow indexes exceeds the value of the MaxShadowFreeForceMerge entry, and if the total free disk space falls below the minimum set in the MinDiskFreeForceMerge, a master merge begins.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, MaxShadowIndexSize


MaxShadowIndexSize

The MaxShadowIndexSize entry is the maximum percentage of total disk space that can be occupied by shadow indexes on the catalog drive before a master merge is triggered.

Summary

Type: | REG_DWORD
Units: | Percent
Default: | 15
Range: | 5 – 25

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, MaxShadowFreeForceMerge, MinDiskFreeForceMerge


MaxSimultaneousRequests

The MaxSimultaneousRequests entry is the maximum number of simultaneous connections for query requests (using named pipes) that Indexing Service supports.

Summary

Type: | REG_DWORD
Units: | Named pipes
Default: | 100
Range: | 1 – 20000

Remarks

The value of this entry should be at least as large as the value of the IsapiMaxEntriesInQueryCache entry, because cached queries keep a connection open for incoming search requests. No more than 50 simultaneous requests can be established because of connection limits in Windows NT Workstation/Windows 2000 Professional.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

IsapiMaxEntriesInQueryCache, Main Registry Entries


MaxTextFilterBytes

The MaxTextFilterBytes entry specifies the maximum amount of information the text filter can process from a single file with a well-known extension.

Summary

Type: | REG_DWORD
Units: | Bytes
Default: | 26214400 (25 MB)
Range: | 1 – 4294967295 (0xFFFFFFFF)

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxUsnLogSize

The MaxUsnLogSize entry is the size of a Unique Synchronization Number (USN) journal to create on an NTFS file system volume when one does not already exist.

Summary

Type: | REG_DWORD
Units: | Bytes
Default: | 8,388,608 (0x800000)
Range: | 0 – 4294967295 (0xFFFFFFFF)

Remarks

The MaxUsnLogSize entry has no effect if a volume already has a USN journal.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxWebhitsCpuTime

The MaxWebhitsCpuTime entry specifies the length of the time-out interval for WEBHITS.dll in CPU seconds.

Summary

Type: | REG_DWORD
Units: | Seconds of CPU time
Default: | 30
Range: | 5 – 7200

Remarks

If WEBHITS.dll does not process a document in the amount of time specified by the value of the MaxWebhitsCpuTime entry, it returns an error message indicating that the allowed time has been exceeded.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


MaxWordlistIo

The MaxWordlistIo entry specifies the system I/O threshold above which indexing (word-list creation) is delayed.

Summary

Type: | REG_DWORD
Units: | Kilobytes/second
Default: | 410 (approximately 2 MB in 5 seconds)
Range: | 100 – 4294967295 (0xFFFFFFFF)

Remarks

The value of the MaxWordlistIo entry provides one method of fine-tuning Indexing Service. Checking the I/O usage by the system is one of the ways Indexing Service limits its resource use so that it can remain an unobtrusive process.

When the disk-performance counters are enabled in the DISKPERF.exe process, the value of the MaxWordlistIoDiskPerf entry is used instead of the value of this entry.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, MaxWordlistIoDiskPerf


MaxWordListIoDiskPerf

The MaxWordListIoDiskPerf entry specifies the system I/O threshold above which indexing (word-list creation) is delayed when disk-performance counters are enabled.

Summary

Type: | REG_DWORD
Units: | Percent
Default: | 10
Range: | 1 – 100

Remarks

The value of the MaxWordListIoDiskPerf entry is enabled only if counters in the DISKPERF.exe process are enabled. When the disk-performance counters are enabled, the value of this entry is used instead of the value of the MaxWordlistIo entry.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, MaxWordlistIo


MaxWordLists

The MaxWordLists entry is the maximum number of word lists that can exist.

Summary

Type: | REG_DWORD
Units: | Word lists
Default: | 20
Range: | 10 – 30

Remarks

Exceeding the limit specified in the value of the MaxWordLists entry triggers a shadow merge to the master index.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MaxWordlistSize

The MaxWordlistSize entry is the maximum amount of memory consumed by an individual word list.

Summary

Type: | REG_DWORD
Units: | 128 Kilobytes
Default: | 20 (2.5 MB)
Range: | 10 – 30

Remarks

When the limit specified by the value of the MaxWordlistSize entry is reached, only the document being filtered is added to the current word list. Additional documents are queued and later placed in another word list.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MinClientIdleTime

The MinClientIdleTime entry is the amount of time a query client can remain idle before it is a candidate for being dropped by the query process.

Summary

Type: | REG_DWORD
Units: | Seconds
Default: | 600 (10 minutes)
Range: | 600 – 4294967295 (0xFFFFFFFF)

Remarks

When a query client is idle for longer than the value specified by the MinClientIdleTime entry, it only becomes a candidate for being dropped. The query process drops a query client only if it runs out of connections to process new queries.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


MinDiskFreeForceMerge

The MinDiskFreeForceMerge entry is the minimum percentage of free space that must be available on the catalog drive to keep Indexing Service from beginning a master merge.

Summary

Type: | REG_DWORD
Units: | Percent
Default: | 15
Range: | 5 – 25

Remarks

If the free space falls below the value specified by the MinDiskFreeForceMerge entry and the disk space occupied by the shadow indexes exceeds MaxShadowFreeForceMerge, a master merge is started.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, MaxShadowIndexSize


MinDiskSpaceToLeave

The MinDiskSpaceToLeave entry is the minimum amount of free disk space to leave on a disk.

Summary

Type: | REG_DWORD
Units: | Megabytes
Default: | 20
Range: | 0 – 4294967295 (0xFFFFFFFF)

Remarks

When the amount of free disk space falls below the value specified by the MinDiskSpaceToLeave entry, additional attempts to extend the allocation for catalog files fail.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MinIdleQueryThreads

The MinIdleQueryThreads entry is the minimum number of idle threads that must be kept available to process incoming queries.

Summary

Type: | REG_DWORD
Units: | Threads
Default: | 1
Range: | 0 – 1000

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, MaxActiveQueryThreads


MinIdleRequestThreads

The MinIdleRequestThreads entry is the minimum number of idle threads that must be kept available to process incoming requests to Indexing Service.

Summary

Type: | REG_DWORD
Units: | Threads
Default: | 1
Range: | 0 – 1000

Remarks

Request types include queries, query result retrievals, and administrative operations.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries, MaxActiveRequestThreads


MinimizeWorkingSet

The MinimizeWorkingSet entry controls whether to minimize the size of the working set (the set of memory pages in physical RAM memory visible to a process) when Indexing Service is idle.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 1 on Windows NT Workstation/Windows 2000 Professional, 0 on Windows NT Server/Windows 2000 Server
Range: | 0, 1

Remarks

If the value of the MinimizeWorkingSet entry is nonzero, the working set for Indexing Service is kept to a minimum to keep the indexing process unobtrusive.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


MinMergeIdleTime

The MinMergeIdleTime entry is the minimum percentage of CPU processing time that must be idle during a merge-check period before Indexing Service can initiate an annealing merge.

Summary

Type: | REG_DWORD
Units: | Percent
Default: | 90
Range: | 10 – 100

Remarks

Indexing Service uses the value of the MinMergeIdleTime entry to delay merges until there are no other heavy demands on the processor.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MinorVersion

The MinorVersion entry indicates the minor version number of the installed Indexing Service.

Summary

Type: | REG_DWORD
Default: | 0
Range: | 0 – 4294967295 (0xFFFFFFFF)

Remarks

The complete version of Indexing Service is the value of MajorVersion combined with the value of the MinorVersion entry. For example if there were a Version 3.1, the value of the entry would be 1. This entry should not be changed except by installation of an upgraded version of Indexing Service.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


MinSizeMergeWordlists

The MinSizeMergeWordlists entry is the minimum combined size of word lists that will force a shadow merge.

Summary

Type: | REG_DWORD
Units: | Kilobytes
Default: | 1024
Range: | 1024 – 10240

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MinWordlistBattery

The MinWordlistBattery entry is the minimum percentage of battery life remaining to keep indexing active on the computer.

Summary

Type: | REG_DWORD
Units: | Percent
Default: | 100 (never run indexing on batteries)
Range: | 0 – 100

Remarks

To prevent indexing from occurring for battery-powered computers, use the default value of 100 percent. Indexing Service continues to process queries even when not indexing files.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


MinWordlistMemory

The MinWordlistMemory entry is the minimum amount of free memory required for word-list creation.

Summary

Type: | REG_DWORD
Units: | Megabytes
Default: | 5
Range: | 1 – 100

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


NNTPSvcInstance

The NNTPSvcInstance entry identifies the instance of the Network News Transfer Protocol (NNTP) server whose virtual directories are indexed by the catalog.

Summary

Type: | REG_DWORD
Default: | 1
Range: | 1 – 4294967295 (0xFFFFFFFF)

Remarks

The NNTPSvcInstance entry is effective only when the value of the IsIndexingIMAPSvc entry is set to one.

Different virtual servers are identified by different values of an NNTPSvcInstance entry.

See Also

Catalog, Property, and Scope Registry Entries, IsIndexingIMAPSvc, Main Registry Entries


PropertyStoreBackupSize

The PropertyStoreBackupSize entry determines the number of system pages held on disk to back up the primary property cache.

Summary

Type: | REG_DWORD
Units: | Pages
Default: | 1024 (x86 processors), 512 (RISC processors)
Range: | 32 – 500000 (x86 processors), 16 – 250000 (RISC processors)

Remarks

The page size is 4 kilobytes (KB) on x86 (486 and higher) computers and 8 KB on RISC (Alpha) computers. The larger the page file, the less often the property cache needs to be written to disk. The fewer times you write the cache to disk, the faster indexing proceeds. The range of values of the PropertyStoreBackupSize entry allows the PROPSTOR.BKP file to range in size from about 128 KB to about 2 gigabytes (GB).

The SecPropertyStoreBackupSize entry serves the same function for the secondary property cache.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, SecPropertyStoreBackupSize


PropertyStoreMappedCache

The PropertyStoreMappedCache entry is the maximum number of pages from the primary property cache that should be kept in memory at any one time.

Summary

Type: | REG_DWORD
Units: | Pages
Default: | 16
Range: | 0 – –4294967295 (0xFFFFFFFF)

Remarks

The SecPropertyStoreMappedCache entry serves the same function for the secondary property cache.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, SecPropertyStoreMappedCache


RequestTimeout

The RequestTimeout entry is the amount of time a query client should wait before it returns a failure to connect to a named pipe instance in Indexing Service.

Summary

Type: | REG_DWORD
Units: | Milliseconds
Default: | 10000 (10 seconds)
Range: | 0 – 1000000000

Remarks

If Indexing Service is not running, the client immediately returns a failure to connect.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


ScanBackoff

The ScanBackoff entry controls the relative use of system resources by Indexing Service when performing scans.

Summary

Type: | REG_DWORD
Default: | 3
Range: | 0 – 20 (11 – 20 reserved for future use)

Remarks

A value of zero for the ScanBackoff entry specifies full use of the allowable system resources when Indexing Service is doing a scan. A value of 10 specifies very conservative use of system resources during the scan. Values in the range 11 – 20 are reserved for future use.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


SecPropertyStoreBackupSize

The SecPropertyStoreBackupSize entry determines the number of system pages held in memory to back up the secondary property cache.

Summary

Type: | REG_DWORD
Units: | Pages
Default: | 1024 (x86 processors), 512 (RISC processors)
Range: | 32 – 500000 (x86 processors), 16 – 250000 (RISC processors)

Remarks

For more details, see the PropertyStoreBackupSize entry, which serves the same function for the primary property cache.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, PropertyStoreBackupSize


SecPropertyStoreMappedCache

The SecPropertyStoreMappedCache entry is the maximum number of pages from the secondary property cache that are to be kept in memory at any one time.

Summary

Type: | REG_DWORD
Units: | Pages
Default: | 16
Range: | 0 – 4294967295 (0xFFFFFFFF)

Remarks

The PropertyStoreMappedCache entry serves the same function for the primary property cache.

For more details, see PropertyStoreBackupSize.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, PropertyStoreBackupSize, PropertyStoreMappedCache


StartupDelay

The StartupDelay entry controls the time delay after a system startup before Indexing Service, an automatic system service, starts any scanning or indexing work.

Summary

Type: | REG_DWORD
Units: | Milliseconds
Default: | 480000 (8 minutes)
Range: | 0 – 4294967295 (0xFFFFFFFF)

Remarks

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


StompLastAccessDelay

The StompLastAccessDelay entry determines whether Indexing Service updates the last access time of a file after indexing it.

Summary

Type: | REG_DWORD
Units: | Days
Default: | 7
Range: | 0 – 1000000000

Remarks

Files with last access times before the time determined by the value of the StompLastAccessDelay entry don't have their last access times modified by the filter daemon. When you rely on storage management systems (for example, backup utilities) that use Hierarchical Storage Management (HSM), the decision of which files to copy to secondary storage depends on the last access time. Not updating the last access time when an "old" file is filtered keeps such a file from unnecessarily being backed up.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


ThreadClassFilter

The ThreadClassFilter entry is the priority class of the CiDaemon.exe process.

Summary

Type: | REG_DWORD
Default: | 0x40 (IDLE_PRIORITY_CLASS)
Range: | 0x20 (NORMAL_PRIORITY_CLASS), 0x40 (IDLE_PRIORITY_CLASS), 0x80 (HIGH_PRIORITY_CLASS)

Remarks

The combination of the value of the ThreadClassFilter entry and the value of the ThreadPriorityFilter entry determines the scheduling priority of the filtering process.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, ThreadPriorityFilter


ThreadPriorityFilter

The ThreadPriorityFilter entry is the priority level of the filtering thread within the CiDaemon.exe process.

Summary

Type: | REG_DWORD
Default: | 1 (THREAD_PRIORITY_ABOVE_NORMAL)
Range: | -2 (THREAD_PRIORITY_LOWEST), -1 (THREAD_PRIORITY_BELOW_NORMAL), 0 (THREAD_PRIORITY_NORMAL), 1 (THREAD_PRIORITY_ABOVE_NORMAL), 2 (THREAD_PRIORITY_HIGHEST)

Remarks

The combination of the value of the ThreadPriorityFilter entry and the value of the ThreadClassFilter entry controls the scheduling priority of the filtering process.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, ThreadClassFilter


ThreadPriorityMerge

The ThreadPriorityMerge entry is the priority level of the merge thread.

Summary

Type: | REG_DWORD
Default: | -2 (THREAD_PRIORITY_LOWEST)
Range: | -2 (THREAD_PRIORITY_LOWEST), -1 (THREAD_PRIORITY_BELOW_NORMAL), 0 (THREAD_PRIORITY_NORMAL), 1 (THREAD_PRIORITY_ABOVE_NORMAL), 2 (THREAD_PRIORITY_HIGHEST)

Remarks

The value of the ThreadPriorityMerge entry is the only registry entry for controlling the scheduling priority of the merge process.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


UsnLogAllocationDelta

The UsnLogAllocationDelta entry is the size allocated for the next entry to the USN journal.

Summary

Type: | REG_DWORD
Units: | Bytes
Default: | 1048576 (1 MB)
Range: | 1 – 4294967295 (0xFFFFFFFF)

Remarks

If, during NTFS file system checkpoints, the journal has grown to its maximum allocation, the number of bytes specified by the value of the UsnLogAllocationDelta entry is removed from the front of the file to make room for more entries.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


UsnReadMinSize

The UsnReadMinSize entry is the minimum size that the USN journal must attain before processing of change notifications can proceed.

Summary

Type: | REG_DWORD
Units: | Bytes
Default: | 4096
Range: | 1 – 524288

Remarks

The processing of change notifications proceeds when either the size of the USN journal reaches the value of the UsnReadMinSize entry or an interval of time equal to the value of the UsnReadTimeout entry has passed (and there are entries in the USN journal).

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, UsnReadTimeout


UsnReadTimeout

The UsnReadTimeout entry is the maximum interval of time for the indexing process to wait before processing change notifications in the USN journal.

Summary

Type: | REG_DWORD
Units: | Seconds
Default: | 300 (5 minutes)
Range: | 0 – 43200 (12 hours)

Remarks

The processing of change notifications proceeds when either an interval of time equal to the value of the UsnReadTimeout entry has passed (and there are entries in the USN journal) or the size of the USN journal reaches the value of the UsnReadMinSize entry.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries, UsnReadMinSize


W3SvcInstance

The W3SvcInstance entry identifies the instance of the WWW server whose virtual directories are indexed by the catalog.

Summary

Type: | REG_DWORD
Default: | 1
Range: | 1 – 4294967295 (0xFFFFFFFF)

Remarks

The W3SvcInstance entry is effective only when the value of the IsIndexingW3Svc entry is set to one.

Different virtual servers are identified by different values of the W3SvcInstance entry. You can set those values by setting each individual Catalog subkey entry to override the main registry entry.

See Also

Catalog, Property, and Scope Registry Entries, IsIndexingW3Svc, Main Registry Entries


WebhitsDisplayScript

The WebhitsDisplayScript entry determines whether scripting code is returned in hit-highlighting results when a query searches a virtual directory that has read access and contains script files.

Summary

Type: | REG_DWORD
Default: | 1
Range: | 0, 1, 2

Remarks

Setting the value of the WebhitsDisplayScript entry to zero directs the system not to return hit highlights. Setting the value of this entry to one specifies the display only of those files written in scripts with recognized filters. For example, the HTML filter allows hit highlights to be displayed for .asp files. No content is displayed for script files written in Perl.

Setting the value of this entry to two specifies the return of hit highlights for all scripts searched. Only the HTML portion of a script file is returned, and the raw code remains unavailable to hit-highlighting.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

Main Registry Entries


WordlistUserIdle

The WordlistUserIdle entry determines whether the filtering process is suspended while the keyboard or mouse is in use and determines when filtering will resume.

Summary

Type: | REG_DWORD
Units: | Seconds
Default: | 120
Range: | 0 – 1200

Remarks

The process of filtering pauses until both input devices are idle for the set amount of time. Set the value of this entry to zero if you don't want filtering to stop while you are using the mouse or keyboard.

See Also

Catalog, Property, and Scope Registry Entries, Main Registry Entries


Catalog, Property, and Scope Registry Entries

Catalogs on the system are included as subkeys of the key

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\
ContentIndex\Catalogs.

The subkey for each catalog contains the following entries.

Registry Name | Description
CatalogInactive | Controls whether a catalog is active.
Location | Path to the catalog directory.
Properties | Subkey that contains a list of entries that are combinations of property set identifiers and property names or identifiers, each specifying information for a property to cache.
Scopes | Subkey that contains a list of strings, each containing one scope definition for the catalog.

Each catalog subkey can include an alternative entry with a name identical to many in the Main Registry Entries. When an alternative entry occurs in a catalog subkey, the value of that entry takes precedence over the value of the global, main registry entry.


CatalogInactive

The CatalogInactive entry controls whether a catalog is active in Indexing Service.

Summary

Type: | REG_DWORD
Units: | Boolean
Default: | 0
Range: | 0, 1

Remarks

The value of the CatalogInactive entry deactivates specific catalogs. Setting the value to one specifies that the catalog is not opened when Indexing Service is started. Setting the value to zero specifies that the catalog is opened when Indexing Service is started.

See Also

Catalog, Property, and Scope Registry Entries


Location

The Location entry indicates the full path to the catalog.

Summary

Type: | REG_SZ
Default: | "%SystemDrive%\System Volume Information"

Remarks

The catalog for Windows 2000 that is named System defaults to the value of the Location entry if there is enough space on that drive. If that location does not exist, the catalog is put in the root directory of the disk. If %SystemDrive% does not have sufficient space available, Indexing Service looks for a suitable volume with sufficient space.

Reading the value of this entry allows you to check where the catalog is located.

See Also

Catalog, Property, and Scope Registry Entries


Properties

The Properties entry is a subkey containing a list of entries that are combinations of property set IDs and property names or IDs, each specifying information for a property to cache.

Summary

Type: REG_SZ

Remarks

Each entry under the Properties subkey names a cached property using one of the following forms: PropertySetID PropertyName, or PropertySetID PropertyID, where a space character separates the PropertySetID and the PropertyName or PropertyID parts of the name.

Each entry also specifies a value of: PropertyVarType,SizeInBytes,StorageLevel,Modifiability, where a comma separates the parts of the value.

The following table gives the meaning of the parts of the name and value of an entry.

Value | Meaning
PropertySetID | GUID of the property set of the cached property.
PropertyName | Property name of the cached property.
PropertyID | Property ID of the cached property.
PropertyVarType | Data type of the cached property. For a list of the correspondence between numeric and symbolic variant types, see the PROPVARIANT structure.
SizeInBytes | Size in bytes allocated for the cached property. A value of 0 signifies that the property should be deleted from the property cache.
StorageLevel | Storage level in the property cache. A value of 0 signifies the Primary Cache, and a value of 1 signifies the Secondary Cache.
Modifiability | Modifiability of the cached property. A value of 0 signifies that the property entry can't be modified once cached, and a value of 1 signifies that the other parts of the cached property (such as SizeInBytes) can be modified once the property is cached.

An example Property entry is the following.

Name
D5CDD502-2E9C-101B-9397-08002B2CF9AE 2
Value
30,10,1,1

This entry is for the Category property of the DocumentSummaryInformation property set. The data type of the property is VT_LSTR, 10 bytes of storage are allocated for the property in the Secondary Cache, and the property entry is modifiable.

Property entries usually don't occur in the registry until you enter them using the Microsoft Management Console (MMC). If a property is not previously cached, its name and value are added to the registry. If a property is already cached, the value is changed to the newly specified value. Newly cached properties are not available until Indexing Service is restarted.

See Also

Caching Value-Type Properties, Catalog, Property, and Scope Registry Entries


Scopes

The Scopes entry is a subkey that contains a list of strings, each containing one scope definition (directory paths to index or to ignore) for the catalog.

Summary

Type: REG_SZ

Remarks

If IIS is running, the Scopes entry does not list directories picked up from IIS when the IsIndexingW3SVC key is set to zero.

For example, the list can be:

c:\MyDocuments
c:\CompanyDocuments\MyDepartment
d:\Favorites

Each entry under the Scopes subkey names the scope to be indexed and specifies a value of fixup,domain\user,bitmask. The fixup parameter is a prefix for a path that will be substituted for the scope when a remote client sends a query. The domain\user parameter identifies the remote client when Indexing Service indexes the files in the scope. The bitmask parameter specifies characteristics about the scope and can be a logical OR operation of the possible values. The following table gives the possible bitmask parameter values and their effects.

Bitmask Value | Scope Characteristic
0x0 | Not indexed, not virtual, and not physical
0x1 | Indexed
0x2 | Virtual
0x4 | Physical

Example

The following example shows a sample registry setting when Indexing Service is running with IIS.

ContentIndex
    GenerateCharacterization   1
    IsIndexingW3Svc   1
    Catalogs
        web
             Location "C:\InetPub"
        correspondence
             GenerateCharacterization  0
             IsIndexingW3Svc   0
             Location "C:\"
             Scopes
                   D:\Memos  "\\Dept05\Memos"
                   \\Corp1\Reports  ",Corp\IISManager"
                   D:\Memos\Confidential  ",,0"

A remote user queries a Web site on the computer named Dept05, and the file REPORT1.TXT is returned on the results page. This file is on drive D: of server Dept05, in the Memos directory. The file name and the Uniform Naming Convention (UNC) path is returned on the results page, (for example, \\Dept05\Memos\Report1.txt). The UNC path allows the user to find the file on the server. However, if a local client makes a query on the server, the physical path on the local drive is returned (D:\Memos\Report1.txt).

Because it has a bitmask parameter value of zero, the scope D:\Memos\Confidential is ignored and is not indexed.

Note The main registry entries can be overridden for each catalog. For example, the Correspondence catalog in the previous example does not generate abstracts.

See Also

Catalog, Property, and Scope Registry Entries


Language-Specific Registry Entries

Language-specific registry entries contain the word breaker, stemmer, and noise-word list appropriate for a given language. They also contain the HTML error pages returned in response to invalid user and administrator actions.

Language-specific registry entries are found as language-specifier subkeys under the key

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\
ContentIndex\Language\Language_Dialect.

The name of the Language_Dialect key has two parts: the name of the language (Language) and the dialect or secondary language (Dialect). The combination of language and dialect can have any of the possibilities made using the MAKELANGID macro. For example, if the primary language is French and the dialect (secondary language) is Belgian, the name of the Language_Dialect key is French_Belgian. Although the language-specifier subkeys contain the registry entries appropriate for the language and dialect, the Locale entry contains the actual value that specifies which language and dialect to use.

Each language-specifier subkey can include the following entries. The ISAPI* entries are for the ISAPI implementation under IIS. None of the ISAPI* entries can be overridden by an identically named entry under the Catalog subkey for a specific catalog.

Registry Name | Short Description
ISAPIDefaultErrorFile | Full virtual path to the generic error template.
ISAPIHTXErrorFile | Full virtual path to the HTML error template for HTX errors.
ISAPIIDQErrorFile | Full virtual path to the Internet Data Query error template for IDQ errors.
ISAPIRestrictionErrorFile | Full virtual path to the query restriction syntax error template.
Locale | Locale identifier (LCID) of language to use.
NoiseFile | File name of the list of noise words to use.
StemmerClass | Microsoft ActiveX® class identifier (CLSID) for the stemming component.
StemmerDictionary | File name for the stemming dictionary component of certain locales.
WBreakerClass | ActiveX CLSID for the word breaker component.


ISAPIDefaultErrorFile

The ISAPIDefaultErrorFile entry specifies the full virtual path to the generic error template.

Summary

Type: | REG_SZ
Default: | ""

Remarks

The value of the ISAPIDefaultErrorFile is the .htx template to process when none of the specific HTML error pages (ISAPIHTXErrorfile, ISAPIIDQErrorFile, ISAPIRestrictionErrorFile) apply.

If a value for this entry is not specified, a generic error page is used.

The variables CiRestriction, CiErrorMessage, and CiErrorNumber can all be referenced.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

ISAPIHTXErrorfile, ISAPIIDQErrorFile, ISAPIRestrictionErrorFile, Language-Specific Registry Entries


ISAPIHTXErrorFile

The ISAPIHTXErrorFile entry specifies the full virtual path to the HTML error template returned in response to errors in the .htx file.

Summary

Type: | REG_SZ
Default: | ""

Remarks

If a value for the ISAPIHTXErrorFile entry is not specified, the error page specified by the value of the ISAPIDefaultErrorFile entry is used.

The variables CiRestriction, CiErrorMessage, and CiErrorNumber can all be referenced.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

ISAPIDefaultErrorFile, Language-Specific Registry Entries


ISAPIIDQErrorFile

The ISAPIIDQErrorFile entry specifies the full virtual path to the HTML error page returned in response to errors in the .idq file.

Summary

Type: | REG_SZ
Default: | ""

Remarks

If a value for the ISAPIIDQErrorFile entry is not specified, the error page specified by the value of the ISAPIDefaultErrorFile entry is used.

The variables CiRestriction, CiErrorMessage, and CiErrorNumber can all be referenced.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

ISAPIDefaultErrorFile, Language-Specific Registry Entries


ISAPIRestrictionErrorFile

The ISAPIRestrictionErrorFile entry specifies the full virtual path to the HTML error page returned in response to errors in a query restriction (CiRestriction).

Summary

Type: | REG_SZ
Default: | ""

Remarks

The value of the ISAPIRestrictionErrorFile entry is the HTML error page that is most often seen by users.

If a value for this entry is not specified, the error page specified by the value of the ISAPIDefaultErrorFile entry is used.

The variables CiRestriction, CiErrorMessage, and CiErrorNumber can all be referenced.

The value of an identically named entry under the Catalog subkey for a specific catalog cannot override the value of this entry.

See Also

ISAPIDefaultErrorFile, Language-Specific Registry Entries


Locale

The Locale entry specifies the LCID used for the language represented by the language subkey.

Summary

Type: | REG_DWORD
Range: | Any LCID made from a language identifier using the MAKELCID macro.

Remarks

The Indexing Service ISAPI implementation variable CiLocale selects a language subkey to use with a specific query.

See Also

Language-Specific Registry Entries, MAKELCID


NoiseFile

The NoiseFile entry contains the file name of the noise-word list for the locale corresponding to the language specified by the language subkey.

Summary

Type: REG_SZ

Remarks

The value of the NoiseFile entry must be either an absolute path name, or the file must be located in the %SystemRoot% \System32 directory.

See Also

Language-Specific Registry Entries


StemmerClass

The StemmerClass entry specifies the ActiveX CLSID of the class used for stemming words for the locale corresponding to the language specified by the Locale entry.

Summary

Type: REG_SZ

See Also

Language-Specific Registry Entries


StemmerDictionary

The StemmerDictionary entry specifies the name of the file used for looking up stem words for the locale corresponding to the language specified by the Locale entry.

Summary

Type: REG_SZ

Remarks

The StemmerDictionary entry is used by only a few languages.

See Also

Language-Specific Registry Entries


WBreakerClass

The WBreakerClass entry specifies the ActiveX CLSID of the word breaker class used to split phrases for the locale corresponding to the language specified by the Locale entry.

Summary

Type: REG_SZ

See Also

Language-Specific Registry Entries


Query-Language Syntax

Indexing Service APIs support queries on the results of indexing using the following two primary approaches.

  • Query-Language Dialects. Query language designed specially for Indexing Service.
  • SQL Queries and SQL Extensions. Query extensions to structured query language (SQL) for use with Indexing Service and the standard OLE DB query language.

This section presents reference material for the two approaches. For additional information about these query approaches, see Query Languages for Indexing Service.


Query-Language Dialects

Indexing Service accepts queries composed in a language designed especially for Indexing Service. This language has two dialects: Query Dialect 1 is the language used in Index Server 2.0 and earlier versions, and Query Dialect 2 is the language introduced in Indexing Service 3.0. Usually, Dialect 2 is the preferred dialect to use because it is more expressive, flexible, and extensible. The short form of Dialect 2 is compatible with Dialect 1 with a few exceptions. Usually a query submitted as Dialect 2 can employ Dialect 1 syntax.

Microsoft® Visual Basic® and Visual J++® applications and Visual Basic Scripting Edition (VBScript) and JScript® scripts can submit queries in these dialects using the Query Helper functions. Microsoft Visual C++® applications can submit queries in these dialects using the OLE DB Helper functions. IDQ+HTX scripts can submit queries in these dialects using the ISAPI Extensions.

This section describes the syntax of the query-language dialects. The topics include:

  • Description of the EBNF Notation
  • Syntax of Query Language Dialect 1
  • Syntax of Query Language Dialect 2

For details about semantics and use of the query language dialects, see Indexing Service Query Language. For a description of incompatibilities between the two dialects, see Incompatibilities of Dialect 2 with Dialect 1.


Description of the EBNF Notation

Extended Backus-Naur Form (EBNF) notation is a means to specify the syntax of a language succinctly and precisely—in the present case, an Indexing Service query language. The syntax describes the allowable constructs of symbols (characters, or combinations of characters) that the query language recognizes and the query engine processes. The EBNF notation has four types of components:

  • Terminal Symbol
  • Nonterminal Symbol
  • Production Rule
  • Start Symbol

The adopted EBNF notation is ISO/IEC 14977 Extended BNF with these minor modifications:

  • The notation does not use the usual concatenation symbol ",". It assumes implicit concatenation of adjacent symbols.
  • The notation uses the symbol "·" (without the quotes) to represent a required space symbol.
  • The notation uses boldface type (a) to signify terminal symbols rather than quoting them ('a' or "a").


Terminal Symbol

A terminal symbol is one of a set of symbols that appear explicitly in the specified language. A terminal symbol appears in boldface type. Examples of terminal symbols are: A, a, TRUE.


Nonterminal Symbol

A nonterminal symbol acts as a placeholder for other symbols that describe the language. The language specification must contain a production rule that defines what a nonterminal symbol represents. A nonterminal symbol appears in normal (nonboldface) type. Examples of nonterminal symbols are: term, Query.


Production Rule

A production rule defines a nonterminal symbol in terms of other nonterminal symbols and terminal symbols. A production rule has this form:

left side = right side ;

The equal sign (=) separates the definition (right side) from the defined symbol (left side), and a semicolon terminates the rule. As the result of a production rule, right side replaces left side wherever left side appears in a production rule.

To produce a valid instance of a query-language construct, successively (even recursively) apply production rules until only terminal symbols remain.

The definition (right side) consists of a combined sequence of nonterminal and terminal symbols that uses several operators. The following table describes the operators.

Operator | Name | Example | Meaning
| | Alternative | a | b | Either a or b
implicit | Concatenation | a b | a followed by b; ab
- | Except | abc - b | abc less b; ac
* | Occurrences | 5 * a | Five as; aaaaa

There are four bracketing constructs to represent grouping, repetition, and optional inclusion. The following table describes these constructs.

Construct | Name | Example | Meaning
( … ) | Grouped | ( a | b ) c | ac or bc
[ … ] | Optional | [ a ] b | ab or b
{ … } | Repeated zero or more times | a { a } | a, aa, aaa, …
{ … }- | Repeated one or more times | a { a }- | aa, aaa, aaaa, …

There also are two miscellaneous constructs. The following table describes these constructs.

Construct | Name | Example | Meaning
(* … *) | Comment | (* This is a comment. *) | Not part of the syntax specification
? … ? | Special | ? Not defined ? | Not defined by EBNF


Start Symbol

The start symbol is a designated nonterminal symbol. All valid instances of the syntax of the specified language start with the production rule for this symbol.


Syntax of Query Language Dialect 1

The following EBNF production rules define the syntax of the original Indexing Service query language, Query Dialect 1. Terminal symbols are case insensitive: or, OR, Or, and oR are equivalent. The production rules give terminal symbols in lowercase only.

Query = (* start symbol *)
QExpression [ , Query ] ;
QExpression =
QTerm [ ( or { · }- | | ) QExpression ] ;
QTerm =
[ not { · }- | ! ] QProperty [ [ Digits ] ] [ ( and { · }- | & ) QTerm ] ;
QProperty =
( [ @ Property ] QFactor )
| ( # Property [ = ] Regex )
| ( $ Property QPhrase ) ;
QFactor =
QGroup
| ( ( Query ) )
| ( Operator [ ^a | ^s ] Phrase ) ; (* ^a|^s only for vector properties *)
QGroup =
QPhrase [ ( near { · }- | ~ ) QGroup ] ;
QPhrase =
( Phrase [ * | ** ] )
| Regex
| ( " AnyExceptQuote " [ * | ** ] ) ;
Property =
Phrase
| ( { [ { Phrase , } Phrase ] } ) ;
Phrase =
Any (* string phrase *)
| ( [ - ] Digits ) (* integer phrase *)
| ( [ - ] Digits [ . Digits ] ) (* float phrase *)
| ( t | true | false | Any ) (* Bool phrase; Any = false *)
| DatePhrase (* date and time phrase *)
| ( Digits . Digits ) (* currency phrase: dollars.cents *)
| GUIDPhrase ; (* globally unique identifier phrase *)
(* The following rule only prepares for the query engine, which does *)
(* the final parsing. See Pattern-Matching Queries for the full syntax. *)
Regex =
" AnyExceptQuote "
| ( ? Any character sequence preceding · ?)
| ( ? Any character sequence preceding ) not preceded by ! ? ) ;
DatePhrase = (* yyyy/mm/dd hh:mm:ss:msec *)
( - { Digits ( h | n | s | y | m | d | w ) }- )
| ( Digits ( / ) Digits ( / ) Digits [ · Digits : Digits : Digits [ : Digits ] ] )
| ( Digits - Digits - Digits [ · Digits : Digits : Digits [ : Digits ] ] ) ;
GUIDPhrase =
{ 0x 8 * HexDigit , 2 * ( 0x 4 * HexDigit , )
{ 0x 2 * HexDigit 7 * ( , 0x 2 * HexDigit ) } } ;
Operator =
= | != | > | >= | < | <= | ^a | ^s ;
Digits =
{ DecimalDigit }- ;
DecimalDigit =
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ;
HexDigit =
DecimalDigit | a | b | c | d | e | f ;
Any =
? Any character sequence ? - Excluded ;
Excluded =
{ | } | ! | & | | | ~ | * | @ | # | ( | ) | [ | ] | , | = | < | > | \n | " | ^ | $ ;
AnyExceptQuote =
? Any character sequence ? - " ; (* quoted " ( = "" ) is OK *)


Syntax of Query Language Dialect 2

The following EBNF production rules define the syntax of the extensible Indexing Service query language, Query Dialect 2. Terminal symbols are case insensitive: or, OR, Or, and oR are equivalent. The production rules give terminal symbols in lowercase only.

Query = (* start symbol *)
( [ Query ( or { · }- | | )] AndTerm )
| ( not { · }- | ! ) Query ;
AndTerm =
NearTerm
| ( ( not { · }- | ! ) PropTerm )
| ( AndTerm ( and { · }- | & ) [ ( not { · }- | ! ) ] NearTerm ) ;
NearTerm =
CoerceTerm
| ( NearTerm ( {near { · }- | ~ ) CoerceTerm )
| ( NearTerm NearElement } CoerceTerm ) ;
PropTerm =
( Property [ = ] Regex [ {/prop} ] )
| ( Property Operator Value [ {/prop} ] ) ;
CoerceTerm =
( [ Generate ] NestTerm [ {/generate} ] )
| ( [ Generate ] Weight [ Generate ] NestTerm [ {/generate} ] ) ;
NearElement =
White
| ,
| ( dist { · } = { · } Digits )
| ( unit { · } = { · } word ) ;
Property =
[ LongPropName | ShortPropName ] ;
(* The following rule only prepares for the query engine, which does *)
(* the final parsing. See Pattern-Matching Queries for the full syntax. *)
Regex =
( {regex} " [ AnyExceptQuote ] " {/regex} )
| ( {regex} [ AnyExceptCurlyOpen ] {/regex} )
| ( {regex} [ [ AnyExceptNewline ] | [ AnyExceptNewline ] ] {/regex} ) ;
Operator =
= | != | > | >= | < | <= | ^a | ^s
| ( = { · }^s | ^s { · } = )
| ( != { · } ^s | ^s { · } != )
| ( > { · } ^s | ^s { · } > )
| ( >= { · } ^s | ^s { · } >= )
| ( < { · } ^s | ^s { · } < )
| ( <= { · } ^s | ^s { · } <= )
| ( ^s { · } ^a )
| ( ^s { · } ^s )
| ( ^a { · } = )
| ( ^a { · } != )
| ( ^a { · } > )
| ( ^a { · } >= )
| ( ^a { · } < )
| ( ^a { · } <= )
| ( ^a { · } ^a )
| ( ^a { · } ^s ) ;
Value =
Phrase
| Freetext
| VectorValue ;
Generate =
( {generate { · }- method { · } = { · } prefix { · } } )

| ( {generate { · }- method { · } = { · } inflect { · } } ) ;

NestTerm =
VectorTerm
| Term
| ( ( Query ) ) ;
Weight =
{weight { · }- value { · } = { · } ( 0 | 1 | ( 0. { DecimalDigit } ) | ( 1. { 0 } ) | ( . { DecimalDigit }- ) ) ;
LongPropName =
( {prop { · }- name { · } = { · } " [ AnyExceptQuote ] " { · } } )
| ( {prop { · }- name { · } = { · } AnyExceptQuoteCurlyCloseSpace [ AnyExceptCurlyClose ] } ) ;
ShortPropName =
( ( @ | $ | # ) " AnyExceptQuote " )
| ( ( @ | $ | # ) AnyExceptExcluded ) ;
Phrase =
( LongPhrase | ShortPhrase ) [ * | ** ] ;
Freetext =
( LongFreetext | ShortFreetext ) [ * | ** ] ;
VectorValue =
EmptyVector
| SingletVector
| MultiVector ) ;
LongPhrase =
( {phrase} { · } " [ AnyExceptQuote ] " { · } {/phrase} )
| ( {phrase} [ AnyExceptCurlyOpen ] {/phrase} ) ;
ShortPhrase =
( " [ AnyExceptQuote ] " )
| ( AnyExceptMany [ AnyExceptOp ] [ · ] ) ;
LongFreetext =
( {freetext} { · } " [ AnyExceptQuote ] " { · } {/freetext} )
| ( {freetext} [ AnyExceptCurlyOpen ] {/freetext} ) ;
ShortFreetext =
AnyExceptMany [ AnyExceptOp ] [ · ] ;
VectorTerm =
VectorSpec {/vector} ;
Term =
PropTerm
| ( Property [ contains { · }- ] Phrase [ {/prop} ] )
| ( Property [ contains { · }- ] Generate Phrase [ {/generate} ] [ {/prop} ) ]
| ( Property [ contains { · }- ] Query )
| ( Property [ contains { · }- ] Freetext [ {/prop} ] ) ;
EmptyVector =
( ) ;
SingletVector =
( ( Phrase ) )
| ( ( Freetext ) ) ;
MultiVector =
( VectorElement VectorElement )
| ( MultiVector VectorElement ) ;
VectorSpec =
( VectorMethod {ve} Query )
| ( VectorSpec {ve} Query ) ;
VectorElement =
White
| ;
| ( " [ AnyExceptQuote ] " )
| ( AnyExceptVector [ AnyExceptSemiClose ] ( ; | ) ) ) ;
VectorMethod =
( {vector { · }- rankmethod { · } = { · } " [ AnyExceptQuote ] " { · } } )
| ( {vector { · }- rankmethod { · } = [ AnyExceptCurlyClose ] } ) ;
Digits =
{ DecimalDigit }- ;
DecimalDigit =
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ;
White =
· | \t | \n | \f | \r ;
AnyExceptQuote =
? Any character sequence ? - " ; (* quoted " ( = "" ) is OK *)
AnyExceptNewline =
? Any character sequence ? - \n ;
AnyExceptCurlyOpen =
? Any character sequence ? - { ;
AnyExceptCurlyClose =
? Any character sequence ? - } ;
AnyExceptSemiClose =
? Any character sequence ? - ( ; | ) ) ;
AnyExceptQuoteCurlyCloseSpace =
? Any character sequence ? - ( " | } | · ) ;
AnyExceptVector =
? Any character sequence ? - ( " | ; | · ) ;
AnyExceptOp =
? Any character sequence ? - ( & | ~ | | | { | ) | · ) ;
AnyExceptExcluded =
? Any character sequence ? - ( " | · | < | > | = | ! | & | | | ~ | ^ ) ;
AnyExceptMany =
? Any character sequence ? - ( # | $ | @ | ~ | & | | | < | > | = | ! | ^| * | " | ( | ) | { | · ) ;


SQL Queries and SQL Extensions

Indexing Service accepts queries composed in structured query language (SQL). Indexing Service uses a SQL syntax which contains extensions to the subset of SQL-92 and SQL3 queries for relational database systems.

Visual Basic and Visual J++ applications and VBScript and JScript scripts can submit SQL queries using the methods of ActiveX Data Objects (ADOs). Visual C++ applications can submit SQL queries using the interfaces of OLE DB Provider for Indexing Service.

This section describes the syntax of SQL queries for Indexing Service. The statements and clauses, in their usual order of use, include the following:

  • SET statement
  • CREATE VIEW statement
  • SELECT statement
  • FROM clause
  • WHERE clause
  • ORDER BY clause
  • Batched statements

For details about the semantics and use of SQL queries, see SQL Query Language.


Batched Statements

Batched statements allow you to set and execute SQL statements, optionally separated by semicolons ( ; ), as one command. You can batch SET statements with CREATE VIEW statements and, optionally, with a single following SELECT statement.

SET_Statement | CREATE_VIEW_Statement
[ [;]  SET_Statement | CREATE_VIEW_Statement ] ...
[ SELECT_Statement ]

Parameters

SET_Statement
For details about SET_Statement, see SET Statement.
CREATE_VIEW_Statement
For details about CREATE_VIEW_Statement, see CREATE VIEW Statement.
SELECT_Statement
For details about SELECT_Statement, see SELECT Statement.

Remarks

The duration of batched SET and CREATE VIEW statements is the length of the session with Indexing Service.

If included, a SELECT statement must appear as the last item in the batch.

Example

The following example represents a batched SET, CREATE VIEW, and SELECT statement.

SET PROPERTYNAME 'D5CDD502-2E9C-101B-9397-08002B2CF9AE'
    PROPID 14 AS MyProperty
    TYPE DBTYPE_STR;
CREATE VIEW #MyView AS
    SELECT FileName, MyProperty
        FROM SCOPE('"/CheckIn"');
SELECT * FROM #MyView

See Also

CREATE VIEW Statement, SELECT Statement, SET Statement


CREATE VIEW Statement

The CREATE VIEW statement defines and stores (for the duration of a session with Indexing Service) a set of frequently used properties. The name associated with this set of properties can be used with subsequent SELECT statements.

CREATE VIEW #View_Name
  AS SELECT Select_List
            FROM_Clause

Parameters

View_Name
Specifies the name for the view. The view name must be preceded by a number sign (#) to indicate that it is a temporary definition.
Select_List
Specifies the list of column aliases (properties) making up the table (rowset) that is returned as a result of the query.
FROM_Clause
Specifies the files on which to perform the search. For details about this parameter, see FROM Clause.

Remarks

You can create a temporary view or use one of several predefined views supplied with the SQL extensions. Predefined views include the following.

  • Indexing Service Predefined Views
  • Site Server Predefined Views

Creating a view allows you to use SELECT * queries, which normally cannot be performed in Indexing Service. Without a view, you would have to specify the full list of columns each time you want to run such a query.

Note It is possible to issue a SELECT statement against a view where the Select_List is a subset of the columns in the view definition.

Once you have associated a name with a view definition by means of the CREATE VIEW statement, you cannot associate it with another view definition. For example, if you execute the following two CREATE VIEW statements in succession, the second CREATE VIEW statement is an attempt to redefine the view, and it will fail.

CREATE VIEW #MyView1 AS SELECT DocAuthor FROM SCOPE()
CREATE VIEW #MyView1 AS SELECT FileName FROM SCOPE()

The view name, along with its view definition, is implicitly associated with the catalog active at the time you define the view. If you switch catalogs, that view will not be found and you must redefine it. Consider the following pseudocode flow.

<default catalog is cat1>

CREATE VIEW #MyView1 AS SELECT DocAuthor, size FROM SCOPE()

<set current catalog to cat2>

SELECT * FROM #MyView1

The preceding SELECT statement will result in an error since #MyView1 has not been defined for cat2.

<set current catalog back to cat1>

SELECT * FROM #MyView1

The preceding SELECT statement will return hits if there are files within the specified scope.

Because there is no support for a DROP VIEW statement, once a view is created, it persists for the duration of the Indexing Service session.

Examples

Suppose you often query using the following properties and scope:

  • DocAuthor, FileName, size, and last file access date.
  • Query a scope of /specs/database/integration (deep traversal) and /current/specs (shallow traversal).

The following CREATE VIEW statement stores that information in a view and eliminates the need to reenter it for SELECT * queries.

CREATE VIEW #MySpecView  AS SELECT DocAuthor, FileName, size, access  FROM SCOPE(' DEEP TRAVERSAL OF "/specs/database/integration" ',  SHALLOW TRAVERSAL OF "/current/specs" ')

As a result, all future queries can be expressed in a simpler manner. For example, you can issue the following queries:

SELECT * FROM #MySpecView
  WHERE size > 100000
SELECT * FROM #MySpecView
  WHERE CONTAINS (' "index search" ')
SELECT FileName, size FROM #MySpecView
  WHERE FREETEXT ('how do I search with Indexing Service')
  AND FileName LIKE 'm%.doc'

See Also

Batched Statements , Indexing Service Predefined Views, Site Server Predefined Views


Indexing Service Predefined Views

The SQL extensions include several predefined views that you can use without writing an explicit CREATE VIEW statement. Because the predefined view names are permanent, they do not need to be preceded by the number sign (#).

The following table lists the predefined views for Indexing Service, which are always available, regardless of the catalog you are currently using.

Predefined View | Properties | Description
FILEINFO | path, FileName, size, write, attrib | Standard file result list
FILEINFO_ABSTRACT | path, FileName, size, write, attrib, Characterization | Standard file result list plus abstract
EXTENDED_FILEINFO | path, FileName, size, write, attrib, DocTitle, DocAuthor, DocSubject, DocKeywords, Characterization | Extended file result list
WEBINFO | Vpath, path, FileName, size, write, attrib, Characterization, DocTitle | Standard Web results
EXTENDED_WEBINFO | Vpath, path, FileName, size, Characterization, write, DocAuthor, DocSubject, DocKeywords, DocTitle | Extended Web results

Example

The following example shows a conceptual SQL statement that defines the FILEINFO predefined view. All predefined views are constructed using the default scope.

CREATE VIEW FILEINFO AS
  SELECT path, FileName, size, write, attrib
  FROM SCOPE()

Without creating the FILEINFO view (it is predefined), you can issue queries such as the following.

SELECT * FROM FILEINFO
  WHERE size > 20000
SELECT path, FileName, attrib
  FROM FILEINFO
  WHERE attrib = ALL ARRAY [0x820]
  OR FileName LIKE 'arch%.xls'

See Also

CREATE VIEW Statement, Site Server Predefined Views


Site Server Predefined Views

The SQL extensions include several predefined views that you can use without writing an explicit CREATE VIEW statement. Because the predefined view names are permanent, they do not need to be preceded by the number sign (#).

The following table lists the predefined views for Site Server, which are always available, regardless of the catalog you are currently using.

Predefined View | Properties | Description
SSWEBINFO | URL, DocTitle, Rank, size, write | Standard Site Server results
SSEXTENDED_WEBINFO | URL, DocTitle, Rank, HitCount, DocAuthor, Characterization, size, write | Extended Site Server results

See Also

CREATE VIEW Statement, Indexing Service Predefined Views


FROM Clause

The FROM clause defines the query scope by specifying the files on which to perform the search. The FROM clause is a required part of the SELECT statement.

SELECT Select_List | *
       FROM {[Server_Name.][Catalog_Name..]Predefined_View_Name |
             [Server_Name.][Catalog_Name..]View_Name |
             [Server_Name.][Catalog_Name..]SCOPE(['Scope_Arguments']) |
            (TABLE [Server_Name.][Catalog_Name..]SCOPE(['Scope_Arguments'])
             UNION ALL TABLE [Server_Name.][Catalog_Name..]SCOPE(['Scope_Arguments'])
            [UNION ALL TABLE [Server_Name.][Catalog_Name..]SCOPE(['Scope_Arguments'])
             ...])}
       [WHERE_Clause]
       [ORDER_BY_Clause]

Parameters

Select_List
Specifies the list of column aliases (properties) making up the table (rowset) that is returned as a result of the query.
* (asterisk)
Specifies all columns. This option is valid only when the FROM_Clause parameter references a predefined view or a temporary view.
Server_Name
Specifies the name of the server on which the query will be run. A Server_Name parameter can't be specified for a query that uses a temporary view because a temporary view is specified only for the current catalog. A Server_Name parameter can be specified for a query that uses a predefined view.
Catalog_Name
Specifies the catalog to use. A catalog is the highest-level unit of organization in Indexing Service. Each catalog is a completely self-contained unit containing an index and cached properties for one or more scopes (virtual or physical directories). If a query does not specify the Catalog_Name parameter, the default catalog "system" is used.
Scope_Arguments
The SCOPE function, which is the main component of the FROM clause, can take zero or more comma-separated Scope_Arguments parameters.

If Scope_Arguments is an empty list (for example, FROM SCOPE()), this specifies that the physical root is to be used as the default path.

If not empty, Scope_Arguments specifies the paths or virtual roots to be searched and how they will be traversed. Each Scope_Argument must be enclosed in single quotes. The syntax of each Scope_Argument is:

'[Traversal_Type] ("Path"[, "Path", ...])'

Traversal_Type can be either of these options:

DEEP TRAVERSAL OF
Searches the paths specified plus all directories beneath them.
SHALLOW TRAVERSAL OF
Searches the specified paths only.

You can group a set of directories or virtual roots for deep or shallow traversal. See the following Examples section.

If you do not specify Traversal_Type, the default option is DEEP TRAVERSAL OF.

Path can be specified either as physical directories, such as "d:\reports\year\97", or as virtual roots, like "/annual/corporate". A scope definition can include multiple physical paths and multiple virtual roots. Enclose each Path parameter with double quotes (to accommodate spaces in paths). If you specify more than one path, they must be separated by commas.

Predefined_View_Name
Specifies one of a set of Indexing Service predefined views or Site Server predefined views of often-queried properties.
View_Name
Specifies a nonpersistent view defined with the CREATE VIEW statement.

Although the SCOPE function restricts the lifetime of the virtual-table definition to the current query, you can use a CREATE VIEW statement to define combinations of properties and scope for use in subsequent queries. For more information, see the CREATE VIEW Statement.

WHERE_Clause
Specifies the search condition for selecting rows in the virtual table defined by the FROM_Clause parameter. The matching rows make up the resulting rowset. This clause is optional. For details about this parameter, see WHERE Clause.
ORDER_BY_Clause
Specifies the ordering of the resulting rowset. This clause is optional. For details about this parameter, see ORDER BY Clause.

Remarks

When using one or more periods (.) to separate the Server_Name, Catalog_Name, SCOPE(), Predefined_View_Name, and View_Name parameters, do not include any spaces.

If some, but not all, of the paths you specify do not exist, these invalid paths are ignored and the query is made using only the valid paths. If all the paths you specify are invalid, then the result set is always empty.

Examples

The following example defines a deep traversal search (default scope). It searches for the word smith in the DocAuthor property for all files, starting from the physical root directories in the catalog.

SELECT DocAuthor, DocTitle
  FROM SCOPE()
  WHERE CONTAINS(DocAuthor, 'smith')

The following example defines a shallow traversal of \Contracts\open on drive D (the top directory only) and all the subdirectories at /reports/year 97 from a specific catalog called Contracts.

SELECT DocAuthor, size,  DocTitle,  write
  FROM Contracts..SCOPE(' SHALLOW TRAVERSAL OF "D:\Contracts\open" ',
             ' DEEP TRAVERSAL OF "/Reports/Year 97" ')
  WHERE CONTAINS(DocTitle, '"Contract Expenses"')

Because DEEP TRAVERSAL OF is the default traversal selection, its inclusion is optional. You may want to use it to increase readability of the statement. Notice that single quoted strings are used to associate traversal type to a specific path or set of paths.

The following example statements are equivalent, but the FROM clause in the latter is more verbose than in the former. In the second example, extra parentheses are added around the paths to enhance readability. Also, the examples demonstrate the syntax for querying a remote server.

SELECT DocAuthor, size,  DocTitle,  write
  FROM SpecServer.Specs..SCOPE(' "D:\Word97\specs", "E:\DAPI\specs"  ' )
  WHERE CONTAINS(Contents, '"content search"')
SELECT DocAuthor, size,  DocTitle,  write
  FROM SpecServer.Specs..SCOPE(' DEEP TRAVERSAL OF ( "D:\Word97\specs",    "E:\DAPI\specs" ) ')
  WHERE CONTAINS(Contents, '"content search"')

The following example demonstrates a query against multiple catalogs. It returns results for matches that contain the phrase "content search" from the Specs catalog and the default catalog.

SELECT DocAuthor, size,  DocTitle,  write
  FROM (TABLE Specs..SCOPE()
        UNION ALL TABLE SCOPE())
  WHERE CONTAINS(Contents, '"content search"')

The following example specifies a Server_Name but not a Catalog_Name, which defaults to "System".

SELECT DocAuthor, FileName
  FROM MyServer...SCOPE()

The preceding example is therefore equivalent to the following example.

SELECT DocAuthor, FileName
  FROM MyServer.System..SCOPE()

If the Server_Name or Catalog_Name parameter contains any non-alphanumeric characters, the name must be double-quoted as in the following example.

SELECT DocAuthor, FileName
  FROM "My-Server".System..SCOPE()

See Also

ORDER BY Clause, SELECT Statement, WHERE Clause


ORDER BY Clause

The ORDER BY clause sorts the rows returned in the rowset according to a specified set of criteria. The ORDER BY clause is an optional part of the SELECT statement.

SELECT Select_List | *
       FROM_Clause
       [WHERE_Clause]
       [ORDER BY Sort_Column [ASC | DESC]
               [,Sort_Column [ASC | DESC]]
                 ... ]

Parameters

Select_List
Specifies the list of column aliases (properties) making up the table (rowset) that is returned as a result of the query.
* (asterisk)
Specifies all columns. This option is valid only when the FROM_Clause parameter references a predefined view or a temporary view.
FROM_Clause
Specifies the files on which to perform the search. For details about this parameter, see FROM Clause.
WHERE_Clause
Specifies the search condition for selecting rows in the virtual table defined by the FROM_Clause parameter. The matching rows make up the resulting rowset. This clause is optional. For details about this parameter, see WHERE Clause.
Sort_Column
Specifies the name of the column to be sorted or the ordinal position of the column.
ASC | DESC
Specifies the sorting order, either ascending (ASC) or descending (DESC). If you do not specify the sort order, the columns are sorted in ascending order. However, if a column is explicitly marked ascending or descending, succeeding columns will use that same sort order until another column in the list is explicitly marked in the other order.

Examples

Notice the order in the columns in the following example:

  • Col1 is ascending (by default).
  • Col2 is descending (explicitly stated).
  • Col3 and Col4 is descending (implicit, same as last keyword).
  • Col5 is ascending (explicitly stated).
SELECT Col1, Col2, Col3, Col4, Col5
  FROM SCOPE()
  WHERE Col1 > 10
  ORDER BY Col1, Col2 DESC, Col3, Col4, Col5 ASC

The following example is equivalent to the previous example, but it refers to the columns by their ordinal position.

SELECT Col1, Col2, Col3, Col4, Col5
  FROM SCOPE()
  WHERE Col1 > 10
  ORDER BY 1, 2 DESC, 3, 4, 5 ASC

See Also

FROM Clause, SELECT Statement, WHERE Clause


SELECT Statement

The SELECT statement retrieves rows by specifying the columns of interest, the scope (the set of files) for the search, and the search criteria. If the results must be ordered, you can add an additional ORDER BY clause to return the rows in ascending or descending order.

SELECT Select_List | *
       FROM_Clause
       [WHERE_Clause]
       [ORDER_BY_Clause]

Parameters

Select_List
Specifies the list of column aliases (properties) making up the table (rowset) that is returned as a result of the query. A column alias can be either a well known Indexing Service friendly name or a new friendly name (regular_identifier) as defined by a SET PROPERTYNAME statement.

Note: Do not use "true" SQL expressions, such as: "SIZE + 500", and LENGTH(DocAuthor), in the Select_List parameter. These expressions are not supported.

* (asterisk)
Specifies all columns. This option is valid only when the FROM_Clause parameter references a predefined view or a temporary view.
FROM_Clause
Specifies the files on which to perform the search. For details about this parameter, see FROM Clause.
WHERE_Clause
Specifies the search condition for selecting rows in the virtual table defined by the FROM_Clause parameter. The matching rows make up the resulting rowset. This clause is optional. For details about this parameter, see WHERE Clause.
ORDER_BY_Clause
Specifies the ordering of the resulting rowset. This clause is optional. For details about this parameter, see ORDER BY Clause.

Remarks

If the Select_List parameter specifies a column more than once, only one instance of that column appears in the result set.

SQL-92 specifies both the ALL and DISTINCT set quantifiers. Because Indexing Service retrieves all rows including duplicate rows, the ALL set quantifier is assumed and does not have to be specified. DISTINCT is not supported.

Examples

The following query returns the author, size, title, and the last time the file was modified for all files in the physical root directory that contain the phrase "Indexing Service".

SELECT DocAuthor, size, DocTitle, write
  FROM SCOPE()
  WHERE CONTAINS(Contents, '"Indexing Service"')

Suppose #MyDocView has been defined with a CREATE VIEW statement containing the properties DocAuthor, FileName, size, and access. Use of an asterisk selects all the properties in that view. The following statement returns DocAuthor, FileName, size, and access values for all rows where the file size is greater than 100000.

SELECT * FROM #MyDocView
  WHERE size > 100000

See Also

CREATE VIEW Statement, FROM Clause, ORDER BY Clause, WHERE Clause


SET Statement

The SET statement maps column names to property IDs and GUIDs (SET PROPERTYNAME) or selects a ranking method for content searches (SET RANKMETHOD) for the duration of a session with Indexing Service.

SET Set_Property_Name_Clause | Set_Rank_Method_Clause

Parameters

Set_Property_Name_Clause
Specifies an association of a property set with a friendly name (column alias) and a data type. For details about this parameter, see SET PROPERTYNAME.
Set_Rank_Method_Clause
Sets the ranking method to use when issuing Weighted Match (ISABOUT) queries. For details about this parameter, see SET RANKMETHOD.

Remarks

You typically use a series of SET statements to define your friendly names for columns and the ranking method, prior to executing subsequent SELECT statements.

The assigning of aliases done with SET is similar to that in the [Names] section of the Indexing Service Internet Data Query (.idq) files, where you can define "friendly" column names for use in queries.

See Also

Batched Statements, SET PROPERTYNAME, SET RANKMETHOD


SET PROPERTYNAME

The SET PROPERTYNAME statement associates a property set with a friendly name (column alias) and a data type for the duration of an active connection. The property is identified by a GUID and a property ID, which can be either a number or a string.

SET PROPERTYNAME 'GUID' PROPID {'Property_Name' | Property_ID}
    AS Friendly_Name [TYPE dbtype]

Parameters

GUID
Specifies the globally unique identifier (GUID). The GUID must be written in the following format, enclosed in single quotes:
  • One 8-hex-character sequence, followed by a minus sign
  • Three 4-hex-character sequences, each followed by a minus sign
  • One 12-hex-character sequence
Property_Name
Specifies the name of the property within the ActiveX property name space.
Property_ID
Specifies the property ID as a decimal or hexadecimal number. If you use a hexadecimal number, precede the number with "0x".
Friendly_Name
Specifies the friendly name (column alias). It is possible to set different (multiple) friendly names to the same property. For example, the friendly name "author" may be also known as "auteur" in a community where both English and French are spoken. However, it is important to note that these two friendly names cannot be used in the same query.
dbtype
Specifies the type of data being used. The dbtype parameter is optional for Indexing Service. You need to specify the parameter in situations when the data type is not a string, which is the default. For example, in the following piece of code, Indexing Service needs to know whether to interpret the value as a string or a date:
WHERE MyProperty = '1996-10-10'

If the data type is not provided, DBTYPE_WSTR (Unicode string) is assumed. See Names Section of .Idq Files for further information.

Remarks

Once a property name has been used in a view, it cannot be redefined.

Example

The following is an example of the SET PROPERTYNAME statement.

SET PROPERTYNAME 'D5CDD502-2E9C-101B-9397-08002B2CF9AE'  PROPID 0xE AS DocManager

See Also

SET RANKMETHOD, SET Statement


SET RANKMETHOD

The SET RANKMETHOD statement sets the ranking method you want to use when issuing queries.

SET RANKMETHOD Method

Parameters

Method
Specifies the ranking algorithm to use to evaluate the rank of a vector query match for content searching. The algorithm can be one of the following:
  • JACCARD COEFFICIENT (default)
  • DICE COEFFICIENT
  • INNER PRODUCT
  • MINIMUM
  • MAXIMUM

Remarks

The method specified by the SET RANKMETHOD statement lasts the duration of a session with Indexing Service unless a subsequent SET RANKMETHOD statement changes the method.

If the Method parameter specifies an algorithm that is not in the list of supported algorithms, the default algorithm (JACCARD COEFFICIENT) is used.

Example

The following is an example of the SET RANKMETHOD statement.

SET RANKMETHOD DICE COEFFICIENT

See Also

SET PROPERTYNAME, SET Statement


WHERE Clause

The WHERE clause specifies the search condition for selecting rows in the virtual table defined by the FROM clause. The matching rows constitute the resulting rowset. The WHERE clause is an optional part of the SELECT statement. However, if the WHERE clause is absent, the resulting rowset can be extremely large because all rows of the virtual table defined by the FROM clause are returned in the resulting rowset.

SELECT Select_List | *
       FROM_Clause
       [WHERE Search_Conditions]
       [ORDER_BY_Clause]

Parameters

Select_List
Specifies the list of column aliases (properties) making up the table (rowset) that is returned as a result of the query.
* (asterisk)
Specifies all columns. This option is valid only when the FROM_Clause parameter references a predefined view or a temporary view.
FROM_Clause
Specifies the files on which to perform the search. For details about this parameter, see FROM Clause.
Search_Conditions
One or more predicates combined with AND, OR, and NOT. It specifies the conditions that rows must satisfy to belong to the resulting rowset. The rowset only includes rows in which all the predicates evaluate to TRUE.
ORDER_BY_Clause
Specifies the ordering of the resulting rowset. This clause is optional. For details about this parameter, see ORDER BY Clause.

Remarks

The composition of search conditions has two parts: Boolean operators and predicates.

Boolean Operators

Boolean operators are AND, OR, and NOT. When using these operators together, precedence rules determine the order of evaluation of the conditions. When the search condition consists of statements enclosed in parentheses, expressions in parentheses are evaluated first. After the parenthetical expressions are evaluated, the following rules apply:

  • NOT is evaluated before AND. NOT can only occur after AND (as in AND NOT; the combination OR NOT is not allowed).
  • AND is evaluated before OR.
  • AND expressions are associative and can be applied in any order. For example, A AND B AND C, is the same as (A AND B) AND C, which is the same as A AND (B AND C).
  • OR expressions are associative and can be applied in any order.

Note It is not valid to place NOT before content query predicates (CONTAINS and FREETEXT). The following statement is not valid.

SELECT FileName FROM SCOPE()
  WHERE NOT CONTAINS ('search')

The following statement is valid.

SELECT FileName FROM SCOPE()
  WHERE CONTAINS ('search') AND NOT CONTAINS ('light')

Predicates

A predicate is an expression that makes a factual assertion about values.

  • If the expression evaluates to TRUE, the associated condition is satisfied.
  • If the expression evaluates to FALSE, the condition is not satisfied.

The following table lists the predicate types you can use with the WHERE clause and summarizes each.

Predicate Type | Description
ARRAY | Performs comparisons of two arrays using logical operators.
Comparison | Uses arithmetic operators to compare column data to a literal value.
CONTAINS | Specifies certain Boolean, proximity and stemming conditions for matching text.
FREETEXT | Specifies searching for the best match for the words and phrases.
LIKE | Performs queries using pattern matching with wildcard characters.
MATCHES | Performs queries using pattern matching with regular expressions.
NULL | Determines whether a column in a selected row is defined.

See Also

FROM Clause, ORDER BY Clause, SELECT Statement


ARRAY Predicate

The ARRAY (or Vector) predicate performs comparisons of two arrays using logical operators. This predicate is an optional part of the optional WHERE clause of the SELECT statement.

SELECT Select_List | *
       FROM_Clause
       [WHERE Column_Reference Comparison_Operator [ALL | SOME] ARRAY [Array_Parameters]]
       [ORDER_BY_Clause]

Parameters

Select_List
Specifies the list of column aliases (properties) making up the table (rowset) that is returned as a result of the query.
* (asterisk)
Specifies all columns. This option is valid only when the FROM_Clause parameter references a predefined view or a temporary view.
FROM_Clause
Specifies the files on which to perform the search. For details about this parameter, see FROM Clause.
Column_Reference
Specifies the column name (alias). Its data type must be compatible with the format of the specified Array_Parameters parameter. A column reference can have multiple values, such as in a vector property or file attribute bitmask.
Comparison_Operator
Specifies the arithmetic operator to use to compare the Array_Parameters parameter.

Comparison_Operator can be any of the following:

  • Equals (=) and not equals (!=).
  • Greater than (>) and greater than or equals (>=).
  • Less than (<) and less than or equals (<=).
ALL | SOME
Specifies the ways to quantify the Array_Parameters parameter. You can use either the ALL or SOME quantifier. If you specify ALL, each parameter on the left side of the expression is tested by using each parameter on the right side. If you specify SOME, at least one parameter on the left side is tested by using at least one parameter of the right side.

For example, the following test fails because parameter 1 on the left side is less than parameter 2 on the right side.

[1,2,3] > ALL ARRAY [1,2]

The following test passes because parameter 2 on the left side is greater than parameter 2 on the right side (and parameter 3 on the left side is greater than parameters 1 and 2 on the right side, but one passed test is sufficient).

[1,2,3] > SOME ARRAY [2,1]

If the ALL or SOME quantifier is absent, each parameter in the vector value on the left side of the operator is compared to its right-side counterpart at the same ordinal position. The test begins with the leftmost parameters and progresses left to right. A test passes if all the individual tests pass. For example, if vectors A[a1, a2, a3] and B[b1, b2, b3] are used, then

A > B

passes if and only if a1 > b1, a2 > b2, and a3 > b3.

If the first m parameters of the vector value on the right match the first m parameters on the right side of the comparison operator, then comparisons actually begin with the (m+1)th parameters where the values on the two sides differ. If all parameters match, then comparison is determined by cardinality, and the one with the higher cardinality is considered greater. The following vector tests all pass.

ARRAY [2,3,4] > ARRAY [1,2]
ARRAY [2,3,4] > ARRAY [1,2,3]
ARRAY [2,3,4] > ARRAY [1,2,3,4]
ARRAY [2,3,4] > ARRAY [1,2,5]
ARRAY [2,3,4] > ARRAY [2,3,3]
ARRAY [2,3,4] > ARRAY [2,3]
ARRAY [2,3,4] < ARRAY [2,3,4,5]
ARRAY [2,3,4]!= ARRAY [2,3,4,5]
Array_Parameters
Specifies the parameters in the array. You must include the square brackets when you specify the array parameters.

It is legal to have an empty array. For example, you can use:

SELECT search FROM SCOPE()
  WHERE bar = ARRAY[]
ORDER_BY_Clause
Specifies the ordering of the resulting rowset. This clause is optional. For details about this parameter, see ORDER BY Clause.

Examples

The following example finds all the compressed files with the archive bit set to ON.

... WHERE attrib = ARRAY [0X820]

The following example finds the files with the archive bit set to ON or the compressed bit set to ON.

... WHERE attrib = SOME ARRAY [0X820]

The following example finds ActiveX documents with a vectorprop property value of [10,15,20].

... WHERE vectorprop = ARRAY [10, 15, 20]

The following example finds ActiveX documents where at least one vectorprop property value is 15.

... WHERE vectorprop = SOME ARRAY [15]

The following example finds files that must be printed by printers named HP3 or HP4.

... WHERE printerprop = SOME ARRAY ['HP4' , 'HP3']

See Also

Comparison Predicate, CONTAINS Predicate, FREETEXT Predicate, LIKE Predicate, MATCHES Predicate, NULL Predicate, WHERE Clause


Comparison Predicate

A comparison predicate uses arithmetic operators to compare column data to a literal value. For a row to be selected, the predicate must evaluate to TRUE. (Indexing Service queries that use such predicates are called relational property queries.) This predicate is an optional part of the optional WHERE clause of the SELECT statement.

SELECT Select_List | *
       FROM_Clause
       [WHERE Column_Reference Arithmetic_Operator Literal
             [Boolean_Operator Column_Reference Arithmetic_Operator Literal ...]]
       [ORDER_BY_Clause]

Parameters

Select_List
Specifies the list of column aliases (properties) making up the table (rowset) that is returned as a result of the query.
* (asterisk)
Specifies all columns. This option is valid only when the FROM_Clause parameter references a predefined view or a temporary view.
FROM_Clause
Specifies the files on which to perform the search. For details about this parameter, see FROM Clause.
Column_Reference
Specifies the column name (alias). Its data type must be compatible with the format of the literal specified.
Arithmetic_Operator
Specifies the arithmetic operator to use to compare the column reference data to a literal value. The following table lists the operators, their symbols, and examples.
Operator | Symbol | Example
Equals = WHERE DocAuthor = 'John Doe'
Not equals | != or <> | WHERE DocTitle != 'Finance'
Less than < WHERE WordCount < 1000
Greater than > WHERE WordCount > 500
Less than or equal to <= WHERE WordCount <= 500
Greater than or equal to >= WHERE WordCount >= 500

Literal
Specifies a constant data value that complies with the constraints of its data type. The following table lists the literal types that are supported.
Literal Type | Description and Examples
Basic String The basic string literal can be an ANSI string constant or a Unicode string constant. Since strings are surrounded by single quotes, to specify a quote character as part of the string, use two single quotes. An empty string is denoted by two single quotes in succession (''). Examples:
'Once upon a time'
'John''s children'
Exact Numeric An exact numeric literal can be an integer or a number with a decimal point. When an exact numeric literal is an integer, it can be one, two, four, or eight bytes in size. Examples:
-300           (2 byte integer)
67000          (4 byte integer)
5000000000     (8 byte integer)
.55
-366.12
Approximate Numeric An approximate numeric literal is composed of a mantissa and a signed or unsigned exponent. Examples:
2.5E-5
-.5E20
Hexadecimal A hexadecimal literal is an integer expressed in hexadecimal notation. The hexadecimal expression has to be prefixed with "0x". Example:
0x2F456
Boolean | A Boolean literal can only have the values TRUE or FALSE.
Absolute Date/Time The absolute date/time literal can be expressed as a date string or as a timestamp string. Note that the "/" (slash) and the "-" (dash) are interchangeable. Examples:
'1996/01/25'
'1996/01/25 02:05:00'
'1996-02-28 10:59:03'

Note The Indexing Service engine requires dates to be in terms of file times based on Greenwich Mean Time (GMT).
Relative Date/Time The relative date/time literal expresses a date relative to the current date.

The syntax for the DATEADD() function is:

DATEADD( Time,  Relative_Interval,
{ Relative_Date/Time | GETGMTDATE()) }

Time has the following values:

  • year or yy
  • quarter or qq
  • month or mm
  • day or dd
  • week or wk
  • hour or hh
  • minute or mi
  • second or ss

The GETGMTDATE() function is modeled after the GETDATE() function in Microsoft® SQL Server™, but GETGMTDATE() indicates the current GMT rather than the current time on the local computer.

Use the following format to specify the relative date/time:

For example, to express an Indexing Service relative time value of -2 years, enter:

DATEADD(year, -2, GETGMTDATE())

To express a relative time value of - 3 years, 24 days, and 5 hours, enter:

DATEADD(hh, -5, DATEADD(dd, -24, DATEADD(yy, -3, GETGMTDATE())))

Note Positive (future) dates are not supported. The Indexing Service engine requires dates to be in terms of file times based on GMT.
NULL A NULL literal is an undefined literal.

Note When determining whether a literal is defined, use IS and IS NOT instead of the equals operator ( = ).

Boolean_Operator
Specifies the Boolean operator to use to combine the comparison predicates. For details about the Boolean operators and precedence rules, see the Remarks section of WHERE Clause.
ORDER_BY_Clause
Specifies the ordering of the resulting rowset. This clause is optional. For details about this parameter, see ORDER BY Clause.

Examples

The following example returns all the files that have the phrase Financial Data as the title of their document.

... WHERE DocTitle = 'Financial Data'

The following example returns all the files that have the phrase Financial Data as the title of their document or that have John James as the author.

... WHERE DocTitle = 'Financial Data'      OR DocAuthor = 'John James'

The following example returns all the files that have a size less than 10,0000 or a word count less than or equal to 800.

... WHERE size < 10000
      OR DocWordCount <= 800

See Also

ARRAY Predicate, CONTAINS Predicate, FREETEXT Predicate, LIKE Predicate, MATCHES Predicate, NULL Predicate, WHERE Clause


CONTAINS Predicate

The CONTAINS predicate provides several text-matching options for building queries. Typically, you use this predicate to query the Contents property— the text contents of a file. You can also query other textual properties with content, such as DocTitle, DocSubject, or a user-defined property. This predicate is an optional part of the optional WHERE clause of the SELECT statement.

SELECT Select_List | *
       FROM_Clause
       [WHERE CONTAINS ([Column_Reference, ] 'Content_Search_Conditions')
       [ORDER_BY_Clause]

Parameters

Select_List
Specifies the list of column aliases (properties) making up the table (rowset) that is returned as a result of the query.
* (asterisk)
Specifies all columns. This option is valid only when the FROM_Clause parameter references a predefined view or a temporary view.
FROM_Clause
Specifies the files on which to perform the search. For details about this parameter, see FROM Clause.
Column_Reference
Specifies the column alias. If you do not specify a column reference, the default is the Contents property. For example, the following two clauses are equivalent:
... WHERE CONTAINS (Contents, 'European')
... WHERE CONTAINS ('European')
Content_Search_Conditions
Specifies one or more search terms. When using more than one search term, connect the terms with AND, AND NOT or OR operators. When specifying Boolean operators, both the text ( AND , OR , NOT ) and symbolic (&, |, ! ) forms are acceptable.

Note Always place spaces around the text Boolean operators.

When the content search condition consists of statements enclosed in parentheses, expressions in parentheses are evaluated first. After the parenthetical expressions are evaluated, the following rules apply:

  • NOT is evaluated before AND.
  • NOT can only occur after AND (as in AND NOT; the combination OR NOT is not allowed).
  • AND is evaluated before OR.
  • AND expressions are associative and can be applied in any order. For example, A AND B AND C, is the same as (A AND B) AND C, which is the same as A AND (B AND C).
  • OR expressions are associative and can be applied in any order.

Note It is illegal to place a NOT operator before content query predicates (CONTAINS and FREETEXT) unless the NOT operator is preceded by an AND operator.

ORDER_BY_Clause
Specifies the ordering of the resulting rowset. This clause is optional. For details about this parameter, see ORDER BY Clause.

Remarks

Index Server 1.x and 2.0 required a > 0 comparison operation at the end of the CONTAINS predicate; for example, CONTAINS( … ) >0. Beginning with Indexing Service 3.0, the comparison operation is neither required nor recommended, but is supported for compatibility with earlier versions.

The CONTAINS predicate uses string literals, so certain conventions must be followed when using single and double quotes. In addition there are several types of quoted material, which produce different types of matches.

Quotes in Basic String Literals

The CONTAINS predicate uses the following conventions when dealing with single and double quotes in basic string literals.

  • If a basic string literal contains spaces, always use double quotes as delimiters. For example:
    '"Phrase With Spaces"'
  • If a basic string literal with no spaces contains a single quote, use two single quotes to specify the single-quote character. For example:
    'Phrase''Without''Spaces'
  • If a basic string literal with spaces contains a single quote, use double quotes as delimiters. For example:
    '"Phrase 'With' Spaces"'
  • If a basic string literal with no spaces contains a double quote, two double quotes are not necessary. For example:
    'Phrase"Without"Spaces'
  • If a basic string literal with spaces contains a double quote, use two double quotes to specify the double-quote character. For example:
    '"Phrase ""With"" Spaces"'

Types of CONTAINS Matches

The following table lists the types of matches along with descriptions of how they work.

Match Type | Description
Simple Match | Matches the specified word or phrase.
Word Prefix Match | Uses the wildcard character "*" to match words containing the same prefix.
Proximity Match | Searches for words that are close to one another.
Linguistic Generation Match | Matches various tenses of verbs, plural, or singular of nouns.
Weighted Match | Returns rows that match a weighted list of words.

Simple Match

In a simple match, the word or phrase must be an exact match; however, the matching is not case sensitive. Multiple consecutive words are treated as a single phrase, and must appear in exactly the same order in the matching document. If a phrase contains blank spaces between words or punctuation marks, it must be enclosed in double quotes.

CONTAINS ([Column_Reference,]
          '"Word_or_Phrase"
          [ Boolean_Operator "Word_or_Phrase"]
           ... ')

Parameters

Column_Reference
Specifies the column name (alias). Its data type must be compatible with the format of the Word_or_Phrase parameter specified.
Word_or_Phrase
Specifies the literal of type Basic String to match.
Boolean_Operator
Specifies the Boolean operator to use, following the precedence rules previously stated, that combines the comparison predicates.

Examples

The following example searches the DocAuthor property of all files from the default scope, and retrieves rows consisting of the DocTitle property for any file in which the DocAuthor is Smith or Jones.

SELECT DocTitle
  FROM SCOPE()
  WHERE CONTAINS(DocAuthor,'"Smith" OR "Jones"')

The following example searches the contents of all files from the default scope, and retrieves rows consisting of the DocTitle and DocAuthor properties for any file containing the phrases "telecommunications industry" and "United Kingdom".

SELECT DocTitle, DocAuthor
  FROM SCOPE()
  WHERE CONTAINS('"telecommunications industry" AND "United Kingdom"')

The following example finds documents with, for example, the following contents:

  • "John Doe has always loved ice hockey."
  • "John Doe on Ice: Hockey at Its Best."
  • "Last night, John Doe fell on the ice!! Hockey fans are concerned…"
SELECT DocTitle
  FROM SCOPE()
  WHERE CONTAINS('"John Doe" AND "ice hockey"')

Word Prefix Match

A word-prefix match is similar to a simple match, except that the wildcard character asterisk (*) is used to represent the variable component of a word or phrase. The matching is not case sensitive. Multiple consecutive words are treated as a single phrase, and must appear in exactly the same order in the matching document. If a phrase contains blank spaces between words or punctuation marks, it must be enclosed in double quotes.

CONTAINS ([Column_Reference,]'"Word_or_Phrase*"
          [ Boolean_Operator "Word_or_Phrase"]
           ... ')

Parameters

Column_Reference
Specifies the column name (alias). Its data type must be compatible with the format of the Word_or_Phrase parameter specified.
Word_or_Phrase
Specifies the literal of type Basic String to use as the prefix.
Boolean_Operator
Specifies the Boolean operator to use, following the precedence rules previously stated, that combines the comparison predicates.

Example

The following example searches the contents of all files from the default scope and retrieves rows for any file that has a DocTitle property consisting of words such as "wine", "winery", "wineries", and so forth.

SELECT DocTitle
  FROM SCOPE()
  WHERE CONTAINS('"wine*"')

The following example searches the contents of all files from the default scope and retrieves rows for any file that has a DocSubject property containing phrases such as "locating test heaven", "locate tester heaven", "locate tester heavy areas", and so forth.

SELECT DocTitle
  FROM SCOPE()
  WHERE CONTAINS(DocSubject,'"locat test heav*"')

Proximity Match

In a proximity match, the query returns a row only if the locations of two or more words in a property are close to each other.

CONTAINS ([Column_Reference,]
          '"Word_or_Phrase" {NEAR | ~}
           "Word_or_Phrase" [{NEAR | ~} "Word_or_Phrase"]
           ... ')

Parameters

Column_Reference
Specifies the column name (alias). Its data type must be compatible with the format of the specified Word_or_Phrase parameter.
Word_or_Phrase
Specifies the literal of type Basic String to match.
NEAR | ~
Specifies the proximity relationship between adjacent words or phrases. (You can also use the tilde (~) instead of NEAR.) Currently, NEAR uses words as the unit of measurement and a value of approximately 50 words as the proximity distance; therefore, if the two phrases are within approximately 50 words, a row is returned.

Remarks

Index Server 1.x and 2.0 required a parenthesis pair after the NEAR operator; for example, NEAR( ). Beginning with Indexing Service 3.0, the parenthesis pair is neither required nor recommended, but is supported for backward compatibility.

You can also use a proximity match to query for more than two words that are near each other.

Examples

The following example returns files where wordA is near wordB, which is near wordC.

... WHERE CONTAINS ('"wordA" NEAR "wordB" NEAR "wordC"')

The following example returns files where Indexing is within approximately 50 words of the word Services:

... WHERE CONTAINS(DocSubject,'"Indexing" ~ "Services"')

The following example returns files containing the word Microsoft, and where the word Indexing is close to the word Service:

... WHERE CONTAINS(DocSubject,'"Microsoft" AND "Indexing" NEAR "Service"')

Linguistic Generation Match

A linguistic generation match is a type of fuzzy search in which the target of the search is expanded to include variations of the word. Currently, the SQL extensions support inflectional morphology generation, in which the search expands to include verb tenses, and the singular or plural of nouns.

CONTAINS ([Column_Reference,]
          'FORMSOF(INFLECTIONAL, "Generation_Term")')

Parameters

Column_Reference
Specifies the column name (alias). Its data type must be compatible with the format of the Word_or_Phrase parameter specified.
Generation_Term
Specifies the literal of type Basic String to expand.

Example

The following example returns files that contain words such as "driving", "driven", and "drives".

... WHERE CONTAINS('FORMSOF(INFLECTIONAL, "drive")')

Weighted Match

The SQL extensions support queries based on matching a group of words or phrases. Also called vector space queries, these queries work by weighting each of the match terms, or vector components. The rank of each returned row indicates how well it matches the query. Rows returned do not have to match every listed word or phrase. The matching algorithm uses all the weighted components together when determining a match.

CONTAINS ([Column_Reference, ]
          'ISABOUT(Vector_Term [WEIGHT(Value)] [,Vector_Term [WEIGHT(Value)]]
          ...')

Parameters

Column_Reference
Specifies the column name (alias). Its data type must be compatible with the format of the Vector_Term parameter specified.
Vector_Term
Specifies the terms to match. The term is one of the following types: Simple, Word Prefix, Proximity, or Linguistic Generation.
Value
Specifies the weight of the Vector_Term parameter. If you specify a weight for a term, you must enclose the term in double quotes. You can specify Value in the range of 0.0 to 1.0.

Example

The following example queries the Contents property for the words "railroad", "transportation", and "locomotive". Files whose Contents include the word "heavy" near the word "locomotive" will be weighted higher in the results ranking. Since the term "transportation" is ranked lower than the other two terms, files containing only that term are ranked lower than files containing either "railroad" or "locomotive".

... WHERE CONTAINS
      ('ISABOUT (railroad, "transportation" WEIGHT(0.5),
        "heavy near locomotive" WEIGHT(0.9))')

See Also

ARRAY Predicate, Comparison Predicate, FREETEXT Predicate, LIKE Predicate, MATCHES Predicate, NULL Predicate, WHERE Clause


FREETEXT Predicate

The FREETEXT predicate performs a best match of the specified words and phrases by finding rows in which the terms and phrases match the meaning, rather than the exact wording of the query. This predicate is an optional part of the optional WHERE clause of the SELECT statement.

SELECT Select_List | *
       FROM_Clause
       [WHERE FREETEXT([ Column_Reference,] 'Free_Text_String')
       [ Boolean_Operator FREETEXT([Column_Reference,] 'Free_Text_String') ]
        ... ]
       [ORDER_BY_Clause]

Parameters

Select_List
Specifies the list of column aliases (properties) making up the table (rowset) that is returned as a result of the query.
* (asterisk)
Specifies all columns. This option is valid only when the FROM_Clause parameter references a predefined view or a temporary view.
FROM_Clause
Specifies the files on which to perform the search. For details about this parameter, see FROM Clause.
Column_Reference
Specifies the column name (alias). Its data type must be compatible with the format of the Free_Text_String parameter specified.
Free_Text_String
Specifies the literal of type Basic String from which to match the meaning.
Boolean_Operator
Specifies the Boolean operator to use, following the precedence rules previously stated, that combines the FREETEXT predicates.
ORDER_BY_Clause
Specifies the ordering of the resulting rowset. This clause is optional. For details about this parameter, see ORDER BY Clause.

Remarks

Index Server 1.x and 2.0 required a > 0 comparison operation at the end of the FREETEXT predicate; for example, FREETEXT( … ) >0. Beginning with Indexing Service 3.0, the comparison operation is neither required nor recommended, but is supported for backward compatibility.

A FREETEXT query ignores Boolean, proximity, and wildcard operators.

Note It is not valid to place NOT before a FREETEXT predicate that begins with a WHERE clause.

Examples

The following example returns files in which the Contents property mentions Microsoft Excel, printing worksheets, and pasting worksheets.

... WHERE FREETEXT('how do I print in Microsoft Excel')
      OR FREETEXT('how can I paste a worksheet into another file')

See Also

ARRAY Predicate, Comparison Predicate, CONTAINS Predicate, LIKE Predicate, MATCHES Predicate, NULL Predicate, WHERE Clause


LIKE Predicate

The LIKE predicate performs queries using wildcard-character pattern matching. This predicate is an optional part of the optional WHERE clause of the SELECT statement.

SELECT Select_List | *
       FROM_Clause
       [WHERE Column_Reference [NOT] LIKE 'String_Pattern']
       [ORDER_BY_Clause]

Parameters

Select_List
Specifies the list of column aliases (properties) making up the table (rowset) that is returned as a result of the query.
* (asterisk)
Specifies all columns. This option is valid only when the FROM_Clause parameter references a predefined view or a temporary view.
FROM_Clause
Specifies the files on which to perform the search. For details about this parameter, see FROM Clause.
Column_Reference
Specifies the column name (alias). Its data type must be compatible with the format of the String_Pattern parameter specified.
String_Pattern
Specifies the literal of type Basic String to use as the pattern. You can use any combination of string literals along with the valid wildcard characters shown in the following table.
Wildcard Character Symbol Description
Percent % Matches one or more characters.
Underscore _ Matches one character.
Square brackets [ ] Matches any single character in the range or set specified within the brackets.
Caret ^ Matches any single character not within the specified range or set.

ORDER_BY_Clause
Specifies the ordering of the resulting rowset. This clause is optional. For details about this parameter, see ORDER BY Clause.

Remarks

In a LIKE search pattern, to use the percent sign ( % ), underscore ( _ ),and left square bracket ( [ ) as literal characters rather than as wildcard characters, surround the characters with square brackets. The right square bracket ( ] ) matches itself unless preceded by a left square bracket. The range character ( - ) matches itself unless it is inside square brackets and preceded and followed by a single character.

The following table shows patterns that illustrate using wildcard characters as literal characters.

Pattern | Meaning
LIKE 'd%' | d followed by any string of 0 or more characters
LIKE 'd[%]' | d%
LIKE '_n' | an, in, on, etc.
LIKE '[_]n' | _n
LIKE '[a-cdf]' | a, b, c, d, or f
LIKE '[-acdf]' | -, a, c, d, or f
LIKE '[[]' | [
LIKE ']' | ]
LIKE '[ab]cd]e' | acd]e, or bcd]e

Examples

The following example returns rows consisting of the DocAuthor, DocTitle, and size properties for all files under the virtual roots "/contracts" and "/legal", written by authors whose names are "Smith", "Smyth", "Smythe", and so on, where the comment field of those documents does not contain words starting with "real", such as "realty" or "realtor".

SELECT DocAuthor, DocTitle, size
  FROM SCOPE('"/contracts", "/legal"')
  WHERE DocAuthor LIKE 'SM_TH%'
    AND DocComments NOT LIKE 'REAL%'

The following example returns rows consisting of the DocTitle and size properties for all files under the virtual roots "/contracts" and "/legal", written by authors whose names begin with any characters except "A" through "F".

SELECT DocTitle, size
  FROM SCOPE('"/contracts", "/legal"')
  WHERE DocAuthor LIKE '[^a-f]%'

See Also

ARRAY Predicate, Comparison Predicate, CONTAINS Predicate, FREETEXT Predicate, MATCHES Predicate, NULL Predicate, WHERE Clause


MATCHES Predicate

The MATCHES predicate performs queries using regular-expression pattern matching, which is more powerful than the wildcard pattern matching available with the LIKE predicate. This predicate is an optional part of the optional WHERE clause of the SELECT statement.

SELECT Select_List | *
       FROM_Clause
       [WHERE MATCHES(Column_Reference, ' {Grouped_Search_Pattern | Counted_Search_Pattern} ') ]
       [ORDER_BY_Clause]

Parameters

Select_List
Specifies the list of column aliases (properties) making up the table (rowset) that is returned as a result of the query.
* (asterisk)
Specifies all columns. This option is valid only when the FROM_Clause parameter references a predefined view or a temporary view.
FROM_Clause
Specifies the files on which to perform the search. For details about this parameter, see FROM Clause.
Column_Reference
Specifies the column name (alias). Its data type must be compatible with the format of the Search_Pattern parameter specified.
Grouped_Search_Pattern
Specifies matches against multiple patterns.
Counted_Search_Pattern
Specifies searches for repetitions of the same pattern. You can request:
  • Exactly m matches: "m"
  • At least m matches: "m,"
  • Between m and n occurrences of the search pattern: "m,n"
ORDER_BY_Clause
Specifies the ordering of the resulting rowset. This clause is optional. For details about this parameter, see ORDER BY Clause.

Remarks

Index Server 1.x and 2.0 required a > 0 comparison operation at the end of the MATCHES predicate, for example, MATCHES( … ) >0. Beginning with Indexing Service 3.0, the comparison operation is neither required nor recommended, but it is supported for backwards compatibility.

A grouped or counted search pattern is formed like a literal of type Basic String but consists of a combination of characters and regular expressions (match symbols). Indexing Service is not case sensitive to characters in a search pattern other than the match symbols. The following table lists and describes the regular expressions that you can use with the MATCH predicate:

Name | Symbol | Description
Asterisk | * | Matches 0 or more occurrences of the search pattern.
Question mark | ? | Matches 0 or 1 occurrence of the preceding pattern.
Plus sign | + | Matches 1 or more occurrences of the preceding pattern.
Parentheses | ( ) | Used to delimit search patterns > 1 character.
Curly braces | { } | Used to delimit a counted match.
Square Brackets | [ ] | Used to specify a range of characters in a pattern.
Vertical bar | | | Used as an escape character that must precede any of the above symbols. Commas separating OR clauses in the matching terms must also be preceded by the escape character.

Examples

The following example uses a grouped match. The pattern matches text with the strings "McAlister", and "McAllister" (strings such as "McAlllister", if they existed, would also be matched). Note how the vertical-bar escape character precedes the embedded regular-expression symbols.

... WHERE MATCHES (Contents, 'McAl|+ister' )

The following example matches any string in which exactly three instances of the pattern "Bora" occur.

... WHERE MATCHES (Contents, '|(Bora|)|{3|}' )

The following example matches any string in which at least two instances of the pattern "Bora" occurs.

... WHERE MATCHES (Contents, '|(Bora|)|{2,|}' )

The following example matches any string in which between two and three instances of the pattern "Bora" occurs.

... WHERE MATCHES (Contents, '|(Bora|)|{2,3|}' )

See Also

ARRAY Predicate, Comparison Predicate, CONTAINS Predicate, FREETEXT Predicate, LIKE Predicate, NULL Predicate, WHERE Clause


NULL Predicate

The NULL predicate determines whether a column in a selected row is defined. This predicate is an optional part of the optional WHERE clause of the SELECT statement.

SELECT Select_List | *
       FROM_Clause
       [WHERE Column_Reference IS [NOT] NULL]
       [ORDER_BY_Clause]

Parameters

Select_List
Specifies the list of column aliases (properties) making up the table (rowset) that is returned as a result of the query.
* (asterisk)
Specifies all columns. This option is valid only when the FROM_Clause parameter references a predefined view or a temporary view.
FROM_Clause
Specifies the files on which to perform the search. For details about this parameter, see FROM Clause.
Column_Reference
Specifies the column name (alias).
ORDER_BY_Clause
Specifies the ordering of the resulting rowset. This clause is optional. For details about this parameter, see ORDER BY Clause.

Remarks

In the NULL predicate, you must use the IS operator. The syntax WHERE Column_Reference = NULL is invalid.

Example

The following example retrieves rows consisting of the FileName and DocAuthor properties for all files under the virtual root "/contracts", where DocAuthor is defined.

SELECT FileName, DocAuthor FROM SCOPE('"/contracts"') WHERE DocAuthor IS NOT NULL

See Also

ARRAY Predicate, Comparison Predicate, CONTAINS Predicate, FREETEXT Predicate, LIKE Predicate, MATCHES Predicate, WHERE Clause


Dynamic ADO Properties

OLE DB and the OLE DB Provider for Indexing Service provide a number of dynamic properties for use when submitting queries with the ActiveX Data Objects (ADO) API. This includes the following properties.

  • Command Object Dynamic Properties
  • Connection Object Dynamic Properties
  • Recordset Object Dynamic Properties


Command Object Dynamic Properties

The following table includes dynamic properties for use with the ADO Command object.

Property Names | Value | Read/Write | Defined By
Blocking Storage Objects | False | RO | OLE DB
Include Bookmark Data | False | RW | OLE DB
Skip Deleted Bookmarks | False | RO | OLE DB
Bookmark Type | 1 | RO | OLE DB
Fetch Backwards | False | RO | OLE DB
Hold Rows | False | RW | OLE DB
Scroll Backwards | False | RO | OLE DB
Column Privileges | False | RO | OLE DB
Command Time Out | 30 | RW | OLE DB
Literal Bookmarks | False | RO | OLE DB
Literal Row Identity | False | RO | OLE DB
Maximum Open Rows | 0 | RO | OLE DB
Maximum Rows | 0 | RO | OLE DB
Memory Usage | 0 | RW | OLE DB
Bookmarks Ordered | False | RO | OLE DB
Others' Inserts Visible | False | RO | OLE DB
Others' Changes Visible | False | RO | OLE DB
Quick Restart | False | RO | OLE DB
Reentrant Events | False | RO | OLE DB
Remove Deleted Rows | True | RO | OLE DB
Row Privileges | True | RO | OLE DB
Row Threading Model | 1 | RO | OLE DB
Server Cursor | True | RO | OLE DB
Strong Row Identity | False | RO | OLE DB
Updatability | 0 | RO | OLE DB
IAccessor | True | RO | OLE DB
IColumnsInfo | True | RO | OLE DB
IConnectionPointContainer | False | RO | OLE DB
IConvertType | True | RO | OLE DB
IRowset | True | RO | OLE DB
IRowsetIdentity | False | RO | OLE DB
IRowsetInfo | True | RO | OLE DB
Bookmarkable | False | RW | OLE DB
IRowsetScroll | False | RW | OLE DB
ISupportErrorInfo | True | RO | OLE DB
Always use Content Index | False | RW | Specific to OLE DB Provider for Indexing Service
Defer scope and security testing | False | RW | Specific to OLE DB Provider for Indexing Service
Return PROPVARIANT structures in variant binding | False | RW | Specific to OLE DB Provider for Indexing Service
SQL Content Query Locale String | EN | RW | Specific to OLE DB Provider for Indexing Service
Query Restriction | "" | RW | Specific to OLE DB Provider for Indexing Service


Connection Object Dynamic Properties

The following table includes dynamic properties for use with the ADO Connection object.

Property Names | Value | Read/Write | Defined By
Data Source | system | RW | OLE DB
Locale Identifier | 1033 | RW | OLE DB
Location | . | RW | OLE DB
Active Sessions | 0 | RO | OLE DB
Pass By Ref Accessors | False | RO | OLE DB
Column Definition | 0 | RO | OLE DB
Read-Only Data Source | True | RO | OLE DB
DBMS Name | Indexing Service | RO | OLE DB
DBMS Version | 03.00.0000 | RO | OLE DB
Data Source Object Threading Model | 1 | RO | OLE DB
GROUP BY Support | 0 | RO | OLE DB
Heterogeneous Table Support | 0 | RO | OLE DB
Maximum Open Chapters | 0 | RO | OLE DB
Maximum Row Size | 0 | RO | OLE DB
Maximum Tables in SELECT | 1 | RO | OLE DB
Multiple Parameter Sets | False | RO | OLE DB
Multiple Results | 0 | RO | OLE DB
Multiple Storage Objects | False | RO | OLE DB
NULL Collation Order | 4 | RO | OLE DB
OLE Object Support | 0 | RO | OLE DB
ORDER BY Columns in Select List | False | RO | OLE DB
Output Parameter Availability | 1 | RO | OLE DB
Persistent ID Type | 2 | RO | OLE DB
Provider Name | Microsoft OLE DB Provider for Indexing Service | RO | OLE DB
OLE DB Version | 02.00 | RO | OLE DB
Provider Version | x.xx.xxxx | RO | OLE DB
Rowset Conversions on Command | True | RO | OLE DB
SQL Support | 1 | RO | OLE DB
Structured Storage | 0 | RO | OLE DB
Subquery Support | 0 | RO | OLE DB
Transaction DDL | 0 | RO | OLE DB
Isolation Levels | 256 | RO | OLE DB
Isolation Retention | 0 | RO | OLE DB
Current Catalog | system | RW | OLE DB


Recordset Object Dynamic Properties

The dynamic properties of the Recordset object include the following types:

  • Extended Query Properties
  • Query Status Properties


Extended Query Properties

The following table includes dynamic properties for use with extended queries using the ADO Recordset object.

Property | Data Type | Property Group | Read/Write | Description
Always use content index (DBPROP_USECONTENTINDEX) | DBTYPE_BOOL | DBPROPFLAGS_ROWSET | RW | Default is FALSE. When set to TRUE, indicates that the search will always use Content Index.
Defer scope and security testing (DBPROP_DEFERNONINDEXEDTRIMMING) | DBTYPE_BOOL | DBPROPFLAGS_ROWSET | RW | Default is FALSE. When set to TRUE, indicates that the search will defer scope and security testing.
Return PROPVARIANTs in variant binding (DBPROP_USEEXTENDEDDBTYPES) | DBTYPE_BOOL | DBPROPFLAGS_ROWSET | RW | Default is FALSE. When set to TRUE, returns PROPVARIANT structures in variant binding.


Query Status Properties

The following table includes dynamic properties for determining the status of queries using the ADO Recordset object.

Property | Data Type | Property Group | Read/Write | Description
Rowset Query Status (DBPROP_RowsetQueryStatus) | DBTYPE_I4 | DBPROPFLAGS_ROWSET | RO | Indicates the rowset query status.

The status can be any of the following values.

Status | Value
STAT_BUSY | ( 0 )
STAT_ERROR | ( 0x1 )
STAT_DONE | ( 0x2 )
STAT_CONTENT_OUT_OF_DATE | ( 0x20 )
STAT_CONTENT_QUERY_INCOMPLETE | ( 0x80 )
STAT_TIME_LIMIT_EXCEEDED | ( 0x100 )


Glossary

Indexing Service uses many terms and concepts from information retrieval technology. Terms in this documentation, however, carry very specific meanings with respect to the Indexing Service implementation. Familiarizing yourself with terms listed in this glossary will help you understand how Indexing Service functions.

A | C | D | E | F | H | I | L | M | N | O | P | Q | R | S | U | W


A

ADO
ActiveX Data Objects. A collection of automation objects that expose the methods and properties used to communicate with an OLE DB data source.
annealing merge
A special case of a shadow merge that includes both existing shadow indexes and word lists in the merge process into shadow indexes. This reduces the number of shadow indexes and increases the efficiency of querying without having to perform a master merge. An annealing merge can occur only when a system is idle.


C

catalog
The catalog is the highest-level unit of organization in Indexing Service. It consists of the content and property indexes and other files that contain the indexed information for the set of files covered by the catalog scopes. By default in Windows 2000, the "System" catalog exists in the path named "System Volume Information\Catalog.wci", which is hidden when Indexing Service first creates it. The "Web" catalog exists in the path named "Inetpub\Catalog.wci", which is also hidden.
code page
A set of typographical characters used to represent text, which can differ by language or locale.
COM
Component Object Model. An architecture that defines interfaces and interactions among objects. The interfaces provide standard ways of using the objects with a minimum amount of internal knowledge of the object necessary.
content
The text (text-type properties) found within a file, as contrasted with the value-type properties that constitute formatted information about the file.


D

dialect
A syntactic or semantic variation of a query language.


E

enumerated query
A query that does not use the Content Index, but rather searches files in the scope to resolve the query.
event log
The result of a Windows® 2000 process that records an audit entry whenever certain events occur. Indexing Service, for example, records an entry when indexing is started and stopped and when a master merge occurs.


F

filtering
The process of extracting text from a file without any formatting or graphic information and, possibly, also extracting value-type properties. Filtering is part of the indexing process.
friendly name
A string that acts as an alias for a property that is defined by a globally unique identifier (GUID).
full-text indexing
Creating an index of all words in a document.


H

hierarchical storage management
The progression of, for example, data storage from memory to hard disk to backup tape. In each step of the hierarchical progression, the amount of storage usually becomes greater, but slower.


I

IMAP
Internet Message Access Protocol. A method for accessing mail and news items from mail servers.
index
In Indexing Service, the "index" includes the stored content index and property index that provide fast access to all files with specified content or properties.
indexing
The process of retrieving text from file filters, creating word lists, processing the word lists for language-specific locales, and merging the word lists into one master index for a given catalog.


L

locale
Indicates language information. For example, a Web server may have a locale variable that indicates the default language used on that server. A server in Los Angeles will probably have a locale of EN-US (U.S. English), whereas a server in Berlin might have a locale of DE (German or Deutsch). Web browsers can also specify locale to indicate the language comprehensible to the user of that browser. In addition, documents and Web pages can specify a locale to indicate the language in which the text is written.


M

master index
The master index is the final destination of all Indexing Service "index" data. It is persistent, disk-resident, highly compressed, and optimized for querying. All indexed content eventually is merged into the master index.
master merge
Combines shadow indexes with the master index to form a new master index.
multi-language support
Multilingual indexing and querying features that are a standard feature of Indexing Service. The indexing system can switch between languages as required, and the query system can dynamically load and unload language-specific utilities. These utilities include word breakers and stemmers.


N

NNTP
Network News Transport Protocol. An application layer Internet protocol for the submission, relay, and retrieval of messages intended for news group discussions, rather than for specific recipients.


O

OLE DB
A set of COM interfaces that provide applications with uniform access to data stored in diverse information sources. The OLE DB interfaces also permit implementation of additional database services.


P

Perfmon
Performance Monitor, a Windows 2000 software tool that allows you to watch certain variables that reflect the activity of a process such as indexing or querying.
predicate
A predicate is an expression that makes a factual assertion about values. If the expression evaluates to TRUE, the associated condition is satisfied. If the expression evaluates to FALSE, the condition is not satisfied.
properties
Text (text-type properties) or other data (value-type properties) associated with a file. Properties can be information stored separately from a file, information available about the file from the operating system, information specially tagged by the software that creates the file, or customized information tagged by the IFilter implementation for that file type.
property indexing
Creating an index of (value-type) properties of a document, including author, subject, type, word count, printed page count, and any other properties produced by the filter that processes a document.


Q

query languages
One of several means of expressing a search for desired information. Indexing Service supports structured query language (SQL) and two dialects of the Indexing Service query language.
query types
Queries can seek different types of information. A content query searches for text (text-type properties) of documents, and a property query searches for properties (value-type properties) in documents. A property query can be either a relational query or a pattern-matching query.
querying
In Indexing Service, the process of searching for specific data in a set of files and returning links to the files containing that data.


R

restriction
A description of what to look for in a query. A restriction narrows the focus of a query.


S

scanning
The process of examining a directory or set of directories to see if any files have been added, deleted, or updated since the last time the directory was indexed.
scope
A query scope specifies the set of documents that must be searched. Typically, scopes are specified by a directory path on a storage volume, such as D:\Docs. Indexing Service can also use virtual roots to indicate scope.
searching
In Indexing Service, the process of searching through a file for a given text or expression.
shadow index
Shadow indexes are an intermediate part of the Indexing Service index that are persistent, disk-resident, and highly compressed. They result from word lists and eventually merge with the master index.
shadow merge
When the number of word lists exceeds the maximum allowable number, Indexing Service performs a shadow merge, which transforms word lists into shadow indexes, to reduce memory usage.
SQL
Structured Query Language. An ANSI-standard database query and programming language that is widely used for accessing data, querying, updating, and managing relational database systems.
stemming
Creating a list of possible word forms for a given word, commonly a verb. Stemming occurs when preparing words in a query string for all possible forms before passing the string to the query processor. For example, stemming the word "swim" produces a list of word forms including "swimming" and "swam".


U

USN journal
Update Sequence Number journal. A log that records changes in directory objects. It is available only for NTFS file systems.


W

word breaker
A piece of software unique to each language or language dialect that splits a phrase into individual words. Both the query string and the content and properties pass through a word breaker.
word list
The first stage of the Indexing Service index, where words are placed along with the containing document name, word location, and locale. Word lists eventually merge to form shadow indexes.


OLE DB Provider for Indexing Service

The Microsoft® OLE DB Provider for Indexing Service supplies programmatic read-only access to Indexing Service content and property indexes. All programmatic access to Indexing Service occurs through this OLE DB provider, which allows you to access the Indexing Service index files as a data source object. Indexing Service supports all the OLE DB interfaces required for an OLE DB provider. The provider is free-threaded and Unicode-enabled.

Applications written in Microsoft Visual C++ can access the OLE DB Provider directly using its interfaces, or they can use the OLE DB Helper API. Applications written in Visual Basic or Visual J++ and scripts written in VBScript or JScript can access the OLE DB Provider using the Query Helper API or the ActiveX Data Objects API.

This section describes the OLE DB Provider for Indexing Service with the following topics.

  • About OLE DB Provider for Indexing Service
  • Using OLE DB Provider for Indexing Service
  • OLE DB Provider for Indexing Service Reference


About OLE DB Provider for Indexing Service

OLE DB is a set of ActiveX® interfaces that abstract how an application retrieves data from data sources and how it presents such information in table form to clients. In OLE DB, a component can be a data consumer (retrieving data from a data source) or a data provider (supplying data to a data consumer). The same component can take on both roles at different times in its process.

In order to manage the roles of data consumer and data provider, OLE DB provides an object model that includes data source objects (DSOs) and session objects. The data source object constant (CLSID_INDEX_SERVER_DSO) identifies Indexing Service as a data source object. Once connected to this specific DSO, a client can create a session object that, in turn, can create command objects to execute queries against the data source and rowset objects to hold the results of a query. In addition, accessors map the text in a command to the columns in the retrieved rowset object for retrieving query results.

This section gives an overview of the OLE DB Provider for Indexing Service. It includes the following topics.

  • OLE DB Objects Used by Indexing Service
  • Command Representation of Queries
  • Command Trees
  • Command Properties
  • Memory Allocation

For more information about OLE DB objects, see the OLE DB Programmer's Reference in the Platform SDK. For an example of how to connect the Indexing Service data source provider, see Using OLE DB Provider for Indexing Service. For sample applications that show how to use these objects, see the Querying Samples in the samples directory of the Platform SDK.


OLE DB Objects Used by Indexing Service

The OLE DB Provider for Indexing Service uses the following OLE DB objects.

  • Data Source Object (DSO)

    DSOs connect to Indexing Service as a data source and allow the creation of Session objects.

  • Session Object

    Session objects establish the context for sessions and allows the creation of Command objects and Rowset objects.

  • Command Object

    Command objects represent commands given to the data source to allow execution of a text command. The result of executing a text command for Indexing Service is a Rowset object. For a list of interfaces implemented for Command objects, refer to the Interfaces section. Note that the ICommandTree interface, unique to this OLE DB provider, allows you to express queries in a hierarchical fashion similar to the ICommandText features.

  • Rowset Object

    Rowset objects represent data in a table. For a list of interfaces implemented for Rowset objects, refer to the Interfaces section.

  • Error Object

    Error objects represent errors that occur during an operation on any of the other objects.

Simply put, Indexing Service uses the OLE DB object model to manipulate the indexes as a data source. The query string is similar to command text in a hierarchical form to facilitate matching hits against the index. The resulting hits are displayed as rows in a table that can support a variety of navigation movements, including scrolling forward and backward, and direct positioning with bookmarks. The IAccessor interface on the Rowset object allows you to map command text variables to the resulting Rowset columns.


Command Representation of Queries

OLE DB uses a tree format to represent commands associated with the Command object. For Indexing Service, the command represents a query. A typical query involves the following steps, where the terms in brackets suggest actions familiar to database users:

  • Step 1 [PROJECT]: Choose the columns you want to display in the search results table and copy the appropriate values from the files that had hits.
  • Step 2 [SELECT]: Define a search on the content and property indexes for some values you specify. The query languages supported allow you to express property-value queries as relational queries or pattern-matching queries in addition to expressing content queries. For each part of the search expression, indicate the values that should be searched for in specific properties (including the contents property) for a file. Execute the query.
  • Step 3 [SORT]: Sort the results by one or more columns in the specified order.

When creating a machine-readable command structure to represent these steps, Indexing Service uses a DBCOMMANDTREE structure, which is an array of zero or more nodes, each describing a part of one of the steps. Nodes include an operation field, a data type identifier field, a data field, and links to other nodes that are children or siblings of this node.

DBCOMMANDTREE structures that represent queries as described in Step 2 are known as select trees. DBCOMMANDTREE structures that represent all three steps are known as full trees.

A full tree contains nodes that represent all three steps but in reverse order. Trees are processed upward from the base with final operations occurring at the top. A typical query tree contains a SELECT node that creates a results table, a PPROJECT node that copies values from the results table to the results display table, and a SORT node that specifies how the results-display table gets sorted before being available for display.

An example of a full tree is shown in Example of Command Tree.


Command Trees

Command trees in Indexing Service represent query strings and query restrictions. Command trees use data definition language (DDL) and data manipulation language (DML) statements to represent the SORT, PROJECT and SELECT parts of the query, as described in Command Representation of Queries. DDL statements define tables and grant access privileges, while DML statements populate tables or delete rows.

The following topics describe the command tree in greater detail.

  • Form of Command Tree
  • Example of Command Tree


Form of Command Tree

A command tree is made up of zero or more command-tree nodes. A command-tree node is a DBCOMMANDTREE structure with the following members.

op
An operator from Data Manipulation Operators that defines the operation that will take on the associated field.
wKind
A value that defines the data type of the associated field, a member of DBVALUEKIND. This type tags the value so that the command processor knows how to interpret it.
pctFirstChild
A link to the first child of this node.
pctNextSibling
A link to the next sibling of this node.
value
A union to hold the value for every data type supported by this OLE DB provider. For any union member that holds 8 bytes or less, the value itself is stored here. Otherwise, value is a pwszValue member, a pointer to the data.

For a list of the types of nodes that can exist, see Catalog of DML Nodes.


Example of Command Tree

Understanding the output from the Simple sample (QSample) in the samples directory of the Platform SDK helps to explain how Indexing Service resolves a query through its OLE DB interfaces.

For example, the following query, which is the default query run against the "SYSTEM" catalog, uses the system default locale LCID (0x409 = 1033 = "US-EN"=United States' English) and returns columns "Size" and "Path" with no sorting and no custom properties. The output of the sample is the following.

op: (15) DBOP_sort
wKind: (0) DBVALUEKIND_EMPTY
first child:
  op: (52) DBOP_project
  wKind: (0) DBVALUEKIND_EMPTY
  first child:
    op: (50) DBOP_select
    wKind: (0) DBVALUEKIND_EMPTY
    first child:
      op: (10) DBOP_table_name
      wKind: (130) DBVALUEKIND_WSTR: 'Table'
      next sibling:
        op: (144) DBOP_content
        wKind: (259) DBVALUEKIND_CONTENT: 'Indexing', method 0, weight 1000, lcid 0x409
        first child:
          op: (5) DBOP_column_name
          wKind: (258) DBVALUEKIND_ID: b725f130-47ef-101a-a5f1-02608c9eebac 19
    next sibling:
      op: (183) DBOP_project_list_anchor
      wKind: (0) DBVALUEKIND_EMPTY
      first child:
        op: (184) DBOP_project_list_element
        wKind: (0) DBVALUEKIND_EMPTY
        first child:
          op: (5) DBOP_column_name
          wKind: (258) DBVALUEKIND_ID: 49691c90-7e17-101a-a91c-08002b2ecda9 3
        next sibling:
          op: (184) DBOP_project_list_element
          wKind: (0) DBVALUEKIND_EMPTY
          first child:
            op: (5) DBOP_column_name
            wKind: (258) DBVALUEKIND_ID: b725f130-47ef-101a-a5f1-02608c9eebac 12
          next sibling:
            op: (184) DBOP_project_list_element
            wKind: (0) DBVALUEKIND_EMPTY
            first child:
              op: (5) DBOP_column_name
              wKind: (258) DBVALUEKIND_ID: b725f130-47ef-101a-a5f1-02608c9eebac 11
  next sibling:
    op: (191) DBOP_sort_list_anchor
    wKind: (0) DBVALUEKIND_EMPTY
    first child:
      op: (192) DBOP_sort_list_element
      wKind: (265) DBVALUEKIND_SORTINFO: fDesc 1, lcid 0x409
      first child:
        op: (5) DBOP_column_name
        wKind: (258) DBVALUEKIND_ID: 49691c90-7e17-101a-a91c-08002b2ecda9 3

The following figure depicts the output as a tree for easier understanding.


Command Properties

The properties of Command objects provide a way to pass on information that is necessary when the command is executing. Command properties for OLE DB objects usually identify properties that must be supported by the rowsets that are created as a result of executing the command text. In Indexing Service, the command properties specify where the query is to be executed: which machine name, catalog name, and the scope within the catalog to use. Other properties can be identified to further control the query resolution process. The additional properties include the following.

DBPROP_USEEXTENDEDDBTYPES
Resulting rowsets should use PROPVARIANT types.
DBPROP_USECONTENTINDEX
Force use of content (and not property) index only.

For other properties, see Extended OLE DB Properties.

Helper functions CICreateCommand and CIMakeICommand create Command objects and set their properties. The Simple sample (QSample) has additional examples of command property use.


Memory Allocation

Ownership of command trees may be transferred by means of several different methods in OLE DB. A transfer of ownership occurs when a component that allocates a command tree is no longer responsible for freeing the allocated resources. For example, command trees may be obtained by data consumers by means of the ICommandTree::GetCommandTree method. In order for this transfer to succeed, a standard for allocation and de-allocation must be identified.

In general, the standard OLE task allocator interface (IMalloc), obtained by calling CoGetMalloc, should be used for allocating and releasing the memory. DBCOMMANDTREE nodes and the values embedded therein are allocated using IMalloc::Alloc and released by means of IMalloc::Free, with the following exceptions:

  • BSTR functions: SysAllocString, SysFreeString family of functions
  • OLE interfaces: IUnknown::AddRef, IUnknown::Release
  • SafeArrays: SafeArrayAllocData, SafeArrayDestroy family of functions.

All other pointers embedded in a command tree are assumed to have been dynamically allocated with IMalloc::Alloc and will be released with IMalloc::Free.

When allocating a tree that will not change ownership, you can use any method of allocation except in the three cases above, because those values also have special copy functions.


Using OLE DB Provider for Indexing Service

This section describes several aspects of using OLE DB Provider for Indexing Service and gives examples of its use. The topics include the following.

  • Accessing OLE DB with the OLE DB Provider for Indexing Service
  • Setting a Command Property
  • Allocating a DBCOMMANDTREE Structure
  • Setting Up a Condition Subtree


Accessing OLE DB with the OLE DB Provider for Indexing Service

This section includes information on how to access OLE DB through the OLE DB Provider for Indexing Service.

Indexing Service supports command-tree extensions for OLE DB, which are a part of OLE DB 2.5. To enable command-tree definitions in oledb.h, define the constant OLEDBVER in program source files before including oledb.h:

#define OLEDBVER 0x250

For more information on property sets supported by this provider, see Property Sets and Property Groups.

The OLE DB provider for Indexing Service provides read-only access to the content and property indexes created by the indexing process. Clients of Indexing Service are OLE DB consumers of the Indexing Service data source object (DSO) that represents the content and property indexes.

The class identifier (CLSID) for the Indexing Service DSO is CLSID_INDEX_SERVER_DSO. Consumers use the CLSID to create instances of provider DSOs that expose the initialization interfaces that allow the consumers to connect to the underlying Indexing Service indexes.

The following example illustrates this.

#include "ntquery.h"
IDBInitialize *pIDBInit;
HRESULT hr;

hr = CoCreateInstance( CLSID_INDEX_SERVER_DSO,
                       0,
                       CLSCTX_INPROC_SERVER,
                       IID_IDBInitialize,
                       (void **) &pIDBInit );
If (FAILED(hr))
(
  // Display error
)


Setting a Command Property

The following example demonstrates how to set an OLE DB property for the ICommand interface. The example declares the SetUseContentIndex function, which sets Indexing Service's DBPROP_USECONTENTINDEX property to VARIANT_TRUE.

HRESULT SetUseContentIndex( ICommand * pICommand )
{
  static const DBID dbcolNull = { {0,0,0,{0,0,0,0,0,0,0,0}},DBKIND_GUID_PROPID,0 };
  static const GUID guidQueryExt = DBPROPSET_QUERYEXT;

  DBPROP aProp[1];
  aProp[0].dwPropertyID = DBPROP_USECONTENTINDEX;
  aProp[0].dwOptions = DBPROPOPTIONS_SETIFCHEAP;
  aProp[0].dwStatus = 0;
  aProp[0].colid = dbcolNull;
  aProp[0].vValue.vt = VT_BOOL;
  aProp[0].vValue.boolVal = VARIANT_TRUE;

  DBPROPSET aPropSet[1];
  aPropSet[0].rgProperties = &aProp[0];
  aPropSet[0].cProperties = 1;
  aPropSet[0].guidPropertySet = guidQueryExt;

  ICommandProperties * pICommandProperties;
  HRESULT hr = pICommand->QueryInterface( IID_ICommandProperties,
                                          (IUnknown **) &pICommandProperties );
  if ( FAILED( hr ) )
    return hr;

  hr = pICommandProperties->SetProperties( 1, aPropSet );
  pICommandProperties->Release();

  return hr;
}


Allocating a DBCOMMANDTREE Structure

The following example declares a function PctAllocNode to allocate a new DBCOMMANDTREE structure. An additional example in Setting Up a Condition Subtree uses the function.

DBCOMMANDTREE* PctAllocNode(
  DBOP op,
  DBVALUEKIND eKind,
  ULONG cbValueSize
  )
{
  DBCOMMANDTREE* pct;
  //get the OLE IMalloc interface
  IMalloc* pim;
  HRESULT hr = CoGetMalloc(MEMCTX_TASK, &pim);
  if (FAILED(hr))
    return NULL;

  // Allocate fixed size part of the node
  pct = (DBCOMMANDTREE*)pim->Alloc((sizeof DBCOMMANDTREE));

  //initialize fields
  pct->op = op;
  pct->pctFirstChild = NULL;
  pct->pctNextSibling = NULL;
  pct->hrError = S_OK;
  pct->dwKind = eKind;

  // Allocate variable size part of the node
  if ( 0 != cbValueSize )
    pct.value.pvValue = (void *) pim->Alloc(cbValueSize);

  //Initialize value space
  if (0 != cbValueSize)
    memset(pct->value.pvValue, 0, cbValueSize);

  return pct;
}


Setting Up a Condition Subtree

The following example illustrates how to set up a condition subtree representing content search restriction. It uses the PctAllocNode function declared in Allocating a DBCOMMANDTREE Structure. The condition searches for the occurrence of the word "Database" within a column named "Text".

DBCOMMANDTREE *pct1, pct2;
DBCONTENT* pdbc;

//Allocate content node
pct1 = PctAllocNode(DBOP_content, DBVALUEKIND_CONTENT, (sizeof DBCONTENT));

//set up value field
pdbc = (DBCONTENT*)(pct1->value.pvValue);
pdbc->dwGenerateMethod = GENERATE_METHOD_PREFIX;
pdbc->lWeight = 200;
pdbc->lcid = DEFAULT_LCID;
pdbc->pwszPhrase = L"Database";

//allocate column node
pct2 = PctAllocNode(DBOP_simple_name, DBVALUEKIND_WSTR,
  (sizeof LPWSTR));
pct2->value.pwszValue = L"Text";

//Make the column node a child of the Content node
pct1->pctFirstChild = pct2;


OLE DB Provider for Indexing Service Reference

This section contains reference information for low-level API elements provided by the OLE DB Provider for Indexing Service. These programming elements make up the OLE DB Provider API.

For information about high-level Indexing Service API elements, see the Indexing Service Reference.

The reference material is divided into the following categories:

  • Interfaces
  • Properties
  • Structures
  • Enumerated Types
  • Constants
  • Other Types
  • Command-Tree Nodes and Operators
  • Error Messages


Interfaces

The OLE DB Provider for Indexing Service implements the following interfaces for Command objects. This section contains reference information for these provider-specific interfaces.

  • ICommandTree
  • IQuery

The OLE DB Provider for Indexing Service supports the following standard OLE DB interfaces for Command objects.

  • IAccessor
  • IColumnsInfo
  • ICommand
  • ICommandProperties
  • IConvertType
  • ISupportErrorInfo

The OLE DB Provider for Indexing Service supports the following standard OLE DB interfaces for Rowset objects.

  • IAccessor
  • IColumnsInfo
  • IConvertType
  • IRowset
  • IRowsetIdentity
  • IRowsetInfo
  • IRowsetLocate
  • IRowsetScroll
  • ISupportErrorInfo


ICommandTree

The ICommandTree interface is optional for providers that support commands. It contains methods for manipulating query trees. Providers that support command trees must also support specifying the same functionality through the ICommandText interface.

A command object can have only one command; that command can be in the form of a command tree (specified in ICommandTree) or a text command (specified in ICommandText). Thus, if a command is specified through the ICommandTree::SetCommandTree or ICommandText::SetCommandText methods, it replaces the command of the command object, whether that command was in text or tree form. If a command is retrieved through ICommandTree::GetCommandTree or ICommandText::GetCommandText, it is retrieved in the specified form, regardless of how the command was set. Thus, the GetCommandText method must be able to convert a command tree into command text, and the GetCommandTree method must be able to convert command text into a command tree. Note that in the latter conversion, the provider should return a navigable command tree representation of the text, which is not necessarily in optimized form. If the provider cannot create a full representation, the command tree can consist of a single text node.

Most providers will not permit an ICommandTree method to set a new command tree while there is a rowset open that was created by the command object. (The rowset directly reflects the result table of the original command tree). Some providers, however, may support this operation even while a rowset is open. If so, the output schema (set of columns) of the new command tree must include all columns for which there currently are accessors, and the accessors for all rowsets must remain valid. Open rowsets must be modified dynamically to reflect the result table of the new command tree. Return row handles (hRows) remain valid. This means that a new sort order or a new selection predicate are not effective for those rows, and that all accessors created after the command-tree modification will work with hRows obtained before the command-tree modification. If an error occurs while replacing or modifying a command tree with open rowsets, the command object, its command tree, the rowsets, hRows, and accessors remain unchanged.

Methods in Vtable Order

IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

ICommandTree methods | Description
FindErrorNodes | Finds the error nodes on a tree.
FreeCommandTree | Deallocates DBCOMMANDTREE structures on a tree.
GetCommandTree | Echoes a command as a command tree.
SetCommandTree | Sets the command tree of a command object.


ICommandTree::FindErrorNodes

The ICommandTree::FindErrorNodes method traverses a command tree and returns an array of nodes with errors in them.

HRESULT FindErrorNodes(
  const DBCOMMANDTREE * pRoot,
  ULONG * pcErrorNodes,
  DBCOMMANDTREE *** prgErrorNodes
);

Parameters

pRoot
[in] Pointer to the root of the command tree.
pcErrorNodes
[out] Pointer to memory in which to return the number of nodes containing errors.
prgErrorNodes
[out] Pointer to memory in which to return an array of pointers to nodes that contain errors. The command object allocates memory for this array and returns the address to this memory; the consumer releases this memory with IMalloc::Free when it no longer needs the array. If *pcErrorNodes is 0 on output, the provider does not allocate any memory and thus ensures that *prgErrorNodes is a null pointer on output.

Return Value

S_OK
The method succeeded.
E_FAIL
A provider-specific error occurred.
E_INVALIDARG
pRoots, pcErrorNodes, or prgErrorNodes was a null pointer.
E_OUTOFMEMORY
The provider was unable to allocate sufficient memory in which to return the array of pointers to nodes containing errors.


ICommandTree::FreeCommandTree

The ICommandTree::FreeCommandTree method traverses a command tree and deallocates all DBCOMMANDTREE node structures, as well as all variants in those structures. It then sets the root pointer to a null pointer.

HRESULT FreeCommandTree(
  DBCOMMANDTREE ** ppRoot
);

Parameters

ppRoot
[in] Pointer to a variable that receives the pointer to the root of the command tree on successful exit.

Return Value

S_OK
The method succeeded.
E_FAIL
A provider-specific error occurred.
E_INVALIDARG
The ppRoot parameter was a null pointer.
DB_E_CANNOTFREE
The consumer called the ICommandTree::SetCommandTree method with fCopy = FALSE, thereby relinquishing ownership of the memory to the provider.

Remarks

The FreeCommandTree method can be used by a consumer to free its copy of the command tree constructed locally or obtained by ICommandTree::GetCommandTree. It does not free the copy of the tree owned by the command object. When a consumer calls SetCommandTree with fCopy = FALSE, the consumer relinquishes ownership of the memory to the provider. Therefore, if the consumer calls FreeCommandTree after having called SetCommandTree with fCopy = FALSE, FreeCommandTree returns a DB_E_CANNOTFREE error code, meaning the consumer does not have ownership of the tree and is unable to free it.


ICommandTree::GetCommandTree

The ICommandTree::GetCommandTree method echoes the current command as a tree, including all post-processing operations that have been added.

HRESULT GetCommandTree(
  DBCOMMANDTREE ** ppRoot
);

Parameters

ppRoot
[out] The command object allocates memory for the command tree and returns the address to this memory; the consumer releases this memory with IMalloc::Free, one node at a time, when it no longer needs the command tree. The provider sets ppRoot to a null pointer if an error occurs.

Return Value

S_OK
The method succeeded.
DB_S_ERRORSINTREE
The provider discovered nonfatal errors in the command text previously set by ICommandText::SetCommandText while building the command tree.
E_FAIL
A provider-specific error occurred.
E_INVALIDARG
The ppRoot parameter was a null pointer.
E_OUTOFMEMORY
The provider was unable to allocate sufficient memory in which to return the command tree.
DB_E_CANTTRANSLATE
The provider cannot represent the command text previously set by ICommandText::SetCommandText as a tree.

Remarks

The returned tree reflects exactly the command set by the last invocation of ICommandTree::SetCommandTree or ICommandText::SetCommandText, as modified by subsequent calls to IQuery::AddPostProcessing. If the command is stored as a tree, the returned tree is a copy of the one stored in the command object. If a tree node was passed with text, it is also echoed as text. If the command is stored as text, the provider should return a "navigable" command-tree representation of the text, which is not necessarily in optimized form. If the provider cannot create a full representation, the command tree can consist of a single text node. For example, if the tree can be represented as a DBOP_SQL_select node, and the provider supports that node, it must be returned in that format. However, if the tree cannot be represented as a DBOP_SQL_select node, but can be represented in a nontrivial command tree (that is, in a type other than DBOP_text_command), the provider must return it as that nontrivial tree. The provider may only return the tree as the trivial DBOP_text_command node, if that is the only command node it supports. Otherwise, it must return a valid, non-trivial navigable tree or return DB_E_CANTTRANSLATE if the text cannot be represented in such a tree. At this time, the provider should not make any unnecessary validation, such as binding, but if in the course of parsing the provider discovers nonfatal errors in building the tree, it should put the error information in the tree and return DB_S_ERRORSINTREE.

This method does not reveal a provider's internal, optimized translation (which may be different from a DBCOMMANDTREE structure) of text to (non-text) tree operations.


ICommandTree::SetCommandTree

The ICommandTree::SetCommandTree method sets a command object's command tree, replacing the existing one or replacing a text command specified with the ICommandText interface. The provided command tree is copied into or transferred to, depending on the fCopy parameter, the command object. Thus, the consumer may delete the original tree or text without affecting the command object. Most error checking is deferred until one of the validation methods, optimization (see ICommandPrepare), or the ICommand::Execute method is invoked. This method only verifies that the command tree can indeed be copied into the command object's space.

HRESULT SetCommandTree(
  DBCOMMANDTREE ** ppRoot,
  DBCOMMANDREUSE dwCommandReuse,
  BOOL fCopy
);

Parameters

ppRoot
[in] Pointer to the address of the root of the command tree.
dwCommandReuse
[in] A mask of type DBCOMMANDREUSE from the DBCOMMANDREUSEENUM enumeration that specifies whether a state from the previous command is retained. If a state that was not previously specified is marked for reuse, the flag is ignored and no error occurs. Only DBCOMMANDREUSE_NONE is currently supported.
fCopy
[in] If TRUE, the command tree is copied, and the caller retains ownership of the command tree's memory. If FALSE, the provider takes the entire tree, without copying, and sets the caller's root pointer to a null pointer. When the command object needs to deallocate the tree, it will call IMalloc::Free once for each node in the tree.

If fCopy is FALSE, the consumer must not change the command tree without another call to the SetCommandTree method. The effect of any such change is undefined. In particular, the provider can assume that the command tree has not changed between the calls that use the tree, such as SetCommandTree, ICommandPrepare::Prepare, and ICommand::Execute.

Return Value

S_OK
The method succeeded.
E_FAIL
A provider-specific error occurred.
E_INVALIDARG
Either the pRoot parameter was a null pointer or the dwCommandReuse parameter was invalid.
DB_E_OBJECTOPEN
A rowset was open on the command object.

Remarks

The following example shows how to build and set a simple command.

hr = pICreateCommand->CreateCommand(0, IID_ICommand,
                                    (IUnknown **) &pICommand);
pICreateCommand->Release();

// Build a command for the following query:
//   SELECT * FROM CUSTOMERS ORDER BY CITY
CreateSelectNode(&pctSelect);
CreateProjectListAnchor(&pctPLListAnchor);

pctSelectNode->pctFirsChild = pctPLListAnchor;

CreateProjectListNode("*", &pctPLListNode);
CreateFromListAnchor(&pctFListAnchor);
CreateFromListNode("CUSTOMERS", &pctFLNode);

pctPLListAnchor->pctFirstChild = pctPLListNode;
pctPLListAnchor->pctNextSibling = pctFListAnchor;

CreateSortListAnchorNode(&pctSLAnchor);
CreateSortListElementNode("ascending",&pctSLNode);
CreateScalarIdNode("CITY", &pctScalar);

pctFListAnchor->pctFirstChild = pctFLNode;
pctFListAnchor->pctNextSibling = pctSLAnchor;

pctSLAnchor->pctFirstChild = pctSLNode;
pctSLNode->pctFirstChild = pctScalar;

// Get ICommandTree Interface
hr = pICommand->QueryInterface(IID_ICommandTree,
                               (IUnknown **) &pICommandTree);

// Set Command Tree in Command Object
pICommandTree->SetCommandTree(&pctSort, DBCOMMANDREUSE_NONE, FALSE);
pICommandTree->Release();

The functions used to create the various nodes (such as CreateSelectNode) are simple wrappers that set values in the DBCOMMANDTREE structure. They are not part of the OLE DB specification. For example, the code for CreateFromListNode might be the following.

void CreateFromListNode(
  PWSTR            szFromList,
  DBCOMMANDTREE ** ppctFLNode);
{
  // Allocate DBCOMMANDTREE structure. Place pointer to it in
  // *ppctFLNode. Code not shown.

  *ppctFLNode->op             = DBOP_from_list;
  *ppctFLNode->hrOperatorOk   = S_OK;
  *ppctFLNode->hrContextOk    = S_OK;
  *ppctFLNode->pctFirstChild  = NULL;
  *ppctFLNode->pctNextSibling = NULL;
  *ppctFLNode->eKind          = DBVALUEKIND_NAME;
  *ppctFLNode->pwszName       = szFromList;
}


IQuery

The IQuery interface is reserved for future use.

The IQuery interface is derived from the ICommandTree interface.

Methods in Vtable Order

IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

ICommandTree methods | Description
FindErrorNodes | Finds the error nodes on a tree.
FreeCommandTree | Deallocates DBCOMMANDTREE structures on a tree.
GetCommandTree | Echoes a command as a command tree.
SetCommandTree | Sets the command tree of a command object.

IQuery methods | Description
IAddPostProcessing | Reserved for future use.
GetCardinalityEstimate | Reserved for future use.

See Also

ICommandTree, IUnknown


IQuery::AddPostProcessing

The IQuery::AddPostProcessing method is reserved for future use.

HRESULT AddPostProcessing(
  DBCOMMANDTREE ** ppRoot,
  BOOL fCopy
);

Parameters

ppRoot
[in] Reserved for future use.
fCopy
[in] Reserved for future use.

See Also

IQuery, IQuery::GetCardinalityEstimate


IQuery::GetCardinalityEstimate

The IQuery::GetCardinalityEstimate method is reserved for future use.

HRESULT GetCardinalityEstimate(
  DBORDINAL * pulCardinality,
);

Parameters

pulCardinality
[out] Reserved for future use.

See Also

IQuery, IQuery::AddPostProcessing


Properties

The OLE DB Provider for Indexing Service uses the following properties.

  • Standard OLE DB Properties
  • Extended OLE DB Properties


Standard OLE DB Properties

The OLE DB Provider for Indexing Service supports the standard OLE DB properties in the following table. The provider does not support other OLE DB properties. For a complete description of these properties, refer to the OLE DB Programmer's Reference.

Property | Settable | Default
DBPROP_BLOCKINGSTORAGEOBJECTS | FALSE | VARIANT_FALSE
DBPROP_BOOKMARKS | TRUE | VARIANT_TRUE if the rowset is locatable.
DBPROP_BOOKMARKSKIPPED | FALSE | VARIANT_FALSE
DBPROP_BOOKMARKTYPE | FALSE | Bookmarks are DBPROPVAL_BMK_NUMERIC
DBPROP_CACHEDEFERRED | TRUE | VARIANT_FALSE
DBPROP_CANFETCHBACKWARDS | FALSE | VARIANT_FALSE
DBPROP_CANHOLDROWS | TRUE | VARIANT_TRUE if the rowset is locatable
DBPROP_CANSCROLLBACKWARDS | FALSE | VARIANT_TRUE if the rowset is locatable
DBPROP_COLUMNRESTRICT | FALSE | VARIANT_FALSE
DBPROP_COMMANDTIMEOUT | TRUE | The default is 0, which means no time-out.
DBPROP_DEFERRED | TRUE | VARIANT_FALSE
DBPROP_LITERALBOOKMARKS | FALSE | VARIANT_FALSE
DBPROP_LITERALIDENTITY | FALSE | VARIANT_TRUE if the rowset is locatable
DBPROP_MAXOPENROWS | FALSE | The default is 0, which means no limit.
DBPROP_MAXROWS | TRUE | The default is 0, which means no limit.
DBPROP_MEMORYUSAGE | TRUE | The default is 0, which means no limit. Not implemented.
DBPROP_ORDEREDBOOKMARKS | FALSE | VARIANT_TRUE if the rowset is locatable
DBPROP_OTHERINSERT | FALSE | VARIANT_TRUE if the rowset is asynchronous
DBPROP_OTHERUPDATEDELETE | FALSE | VARIANT_TRUE if the rowset is asynchronous
DBPROP_QUICKRESTART | FALSE | VARIANT_TRUE if the rowset is locatable
DBPROP_REENTRANTEVENTS | FALSE | VARIANT_FALSE
DBPROP_REMOVEDELETED | FALSE | VARIANT_TRUE
DBPROP_ROWRESTRICT | FALSE | VARIANT_TRUE
DBPROP_ROWSET_ASYNCH | TRUE | The default is 0, which means synchronous processing.
DBPROP_ROWTHREADMODEL | FALSE | The default is DBPROPVAL_RT_FREETHREAD.
DBPROP_SERVERCURSOR | FALSE | VARIANT_TRUE
DBPROP_STRONGIDENTITY | FALSE | VARIANT_TRUE if the rowset is locatable
DBPROP_UPDATABILITY | FALSE | The default is 0, which means updates aren't supported.


Extended OLE DB Properties

Indexing Service defines a number of properties for use with the ICommand interface that can be used to customize queries. These properties are specific to Indexing Service and might not apply to other OLE DB providers.

These extended properties are set using OLE DB's ICommandProperties interface. The properties must be set before a query is executed to have an effect on the query.

This section describes the following properties.

  • DBPROP_CI_CATALOG_NAME
  • DBPROP_CI_INCLUDE_SCOPES
  • DBPROP_CI_SCOPE_FLAGS
  • DBPROP_DEFERNONINDEXEDTRIMMING
  • DBPROP_MACHINE
  • DBPROP_USECONTENTINDEX
  • DBPROP_USEEXTENDEDDBTYPES


DBPROP_CI_CATALOG_NAME

The DBPROP_CI_CATALOG_NAME property specifies the names of the catalog(s) over which the query is processed.

Summary

Property Set | DBPROPSET_ FSCIFRMWRK_EXT
Property ID | DBPROP_CI_CATALOG_NAME
Value Type | DBTYPE_ARRAY | DBTYPE_BSTR
Default | None

Remarks

If more than one catalog or machine is specified, the DBPROP_MACHINE, DBPROP_CI_CATALOG_NAME, DBPROP_CI_INCLUDE_SCOPES, and DBPROP_CI_SCOPE_FLAGS properties all must have the same number of entries, or the count of scopes and flags can be either the count of catalogs and machines or 1.

When more than one machine or catalog is specified, the query is executed on multiple machines and the results are merged on the local machine.

The default catalog installed with Windows 2000 is named System.

This property corresponds to the CiCatalog variable in the Internet Data Query Files of Indexing Service.


DBPROP_CI_INCLUDE_SCOPES

The DBPROP_CI_INCLUDE_SCOPES property specifies the names of the file path(s) over which the query is processed.

Summary

Property Set | DBPROPSET_ FSCIFRMWRK_EXT
Property ID | DBPROP_CI_INCLUDE_SCOPES
Value Type | DBTYPE_ARRAY | DBTYPE_BSTR
Default | "\" (the entire catalog)

Remarks

If more than one catalog or machine is specified, the DBPROP_MACHINE, DBPROP_CI_CATALOG_NAME, DBPROP_CI_INCLUDE_SCOPES, and DBPROP_CI_SCOPE_FLAGS properties all must have the same number of entries, or the count of scopes and flags can be either the count of catalogs and machines or 1.

When more than one machine or catalog is specified, the query is executed on multiple machines and the results are merged on the local machine.

The scope "\" covers the entire catalog. The scope "/" covers the entire Microsoft Internet Information Services (IIS) virtual path name space. Scopes can be letter-based paths on the local drive or remote universal naming convention (UNC) paths.

This property corresponds to the CiScope variable in the Internet Data Query Files of Indexing Service.


DBPROP_CI_SCOPE_FLAGS

The DBPROP_CI_SCOPE_FLAGS property specifies attributes of the scopes specified for DBPROP_CI_INCLUDE_SCOPES.

Summary

Property Set | DBPROPSET_FSCIFRMWRK_EXT
Property ID | DBPROP_CI_SCOPE_FLAGS
Value Type | DBTYPE_UI4
Default | QUERY_DEEP | QUERY_PHYSICAL_PATH

Values

QUERY_SHALLOW
Only files in the scope directory are included in the results. Cannot be combined with QUERY_DEEP.
QUERY_DEEP
Files in the scope directory and all subdirectories are included in the results. Cannot be combined with QUERY_SHALLOW.
QUERY_PHYSICAL_PATH
The scope is a physical directory. Cannot be combined with QUERY_VIRTUAL_PATH.
QUERY_VIRTUAL_PATH
The scope is a virtual IIS directory. Cannot be combined with QUERY_PHYSICAL_PATH.

Remarks

When you set a flag using these values, perform the logical OR operation of one of QUERY_SHALLOW or QUERY_DEEP with one of QUERY_PHYSICAL_PATH or QUERY_VIRTUAL_PATH.

If more than one catalog or machine is specified, the DBPROP_MACHINE, DBPROP_CI_CATALOG_NAME, DBPROP_CI_INCLUDE_SCOPES, and DBPROP_CI_SCOPE_FLAGS properties must all have the same number of entries. The exception is that if more than one catalog or machine is specified, the count of scopes and flags can be either the count of catalogs and machines or 1.

When more than one machine or catalog is specified, the query is executed on multiple machines and the results are merged on the local machine.

This property corresponds to the CiFlags variable in the Internet Data Query Files of Indexing Service.


DBPROP_DEFERNONINDEXEDTRIMMING

The DBPROP_DEFERNONINDEXEDTRIMMING property optimizes query execution for a specific type of query.

Summary

Property Set | DBPROPSET_QUERYEXT
Property ID | DBPROP_DEFERNONINDEXEDTRIMMING
Value Type | DBTYPE_BOOL
Default | VARIANT_FALSE

Remarks

If the value is VARIANT_TRUE, a maximum number of rows for the result is specified, and the sort order is by rank descending. Scope and security checking are deferred until the maximum number of rows is reached or the query is completed. This may result in less than the expected number of hits for queries in which scope checks or security trimming remove some results. The default is to optimize for recall; the result set trimming occurs in the course of executing the query.

This flag is best used when the query scope encompasses the entire catalog and all files in the result set have the same security access control lists.

This property corresponds to the CiDeferNonIndexedTrimming variable in the Internet Data Query Files of Indexing Service.

This property corresponds to the OptimizeFor variable in Indexing Service's Query object.


DBPROP_MACHINE

The DBPROP_MACHINE property specifies the names of the computer(s) on which a query is to be processed.

Summary

Property Set | DBPROPSET_CIFRMWRKCORE_EXT
Property ID | DBPROP_MACHINE
Value Type | DBTYPE_ARRAY | DBTYPE_BSTR
Default | "." (the local machine)

Remarks

If more than one catalog or machine is specified, the DBPROP_MACHINE, DBPROP_CI_CATALOG_NAME, DBPROP_CI_INCLUDE_SCOPES, and DBPROP_CI_SCOPE_FLAGS properties must all have the same number of entries, or the count of scopes and flags can be either the count of catalogs and machines or 1.

When more than one machine or catalog is specified, the query is executed on multiple machines and the results are merged on the local machine.

Do not include preceding slashes with machine names. A correct example would be "MyMachine", not "\\MyMachine".

The machine name "." refers to the local machine. If the name of the local machine is specified, the query is treated as a remote query.


DBPROP_USECONTENTINDEX

The DBPROP_USECONTENTINDEX property controls the use of the index when processing queries.

Summary

Property Set | DBPROPSET_QUERYEXT
Property ID | DBPROP_USECONTENTINDEX
Value Type | DBTYPE_BOOL
Default | VARIANT_FALSE

Remarks

If the value is VARIANT_TRUE, the index is always used to resolve the query, even if the index is not up to date. If the value is VARIANT_FALSE and the index is not up to date, the query engine may enumerate the file system to process the query.

This setting affects property value queries such as "@size > 1000".

Enumerating the file system can be disk-intensive and slow.

Content queries always use the index and never enumerate, regardless of the setting of this property.

Certain types of queries require DBPROP_USECONTENTINDEX to be VARIANT_FALSE to return results, for example "#filename *.dl*". These queries require enumeration and cannot use the index even if the index is up to date.

This property corresponds to the CiForceUseCi variable in the Internet Data Query Files of Indexing Service.

This property corresponds to the AllowEnumeration variable in the Query object of Indexing Service .


DBPROP_USEEXTENDEDDBTYPES

The DBPROP_USEEXTENDEDDBTYPES property controls the data type of columns bound by OLE DB accessors.

Summary

Property Set | DBPROPSET_QUERYEXT
Property ID | DBPROP_USEEXTENDEDDBTYPES
Value Type | DBTYPE_BOOL
Default | VARIANT_FALSE

Remarks

If the value is VARIANT_TRUE, accessor column bindings can be based on PROPVARIANT structures. By default, only OLE Automation VARIANT structures and any directory binding are allowed for accessor column bindings.

Many frequently used properties are stored using types that are not OLE Automation VARIANT structures. This causes considerable overhead in the OLE DB accessor used to retrieve the data, since the data must be coerced into a different type.

Clients that can make use of PROPVARIANT structures should set DBPROP_USEEXTENDEDDBTYPES to VARIANT_TRUE and use OLE DB accessors with bindings that use PROPVARIANT types.


Structures

The OLE DB Provider for Indexing Service provides several structures for use with the ICommandTree interface. This section contains information about the following structures.

  • DBBYGUID
  • DBCOMMANDTREE
  • DBCONTENT
  • DBCONTENTPROXIMITY
  • DBCONTENTSCOPE
  • DBCONTENTTABLE
  • DBCONTENTVECTOR
  • DBGROUPINFO
  • DBID
  • DBLIKE
  • DBPARAMETER
  • DBPROBABILISTIC
  • DBRELEVANTDOCUMENT
  • DBSETFUNC
  • DBSORTINFO
  • DBTEXT


DBBYGUID

The DBBYGUID structure supplies supplementary information for a node.

typedef struct tagDBBYGUID {
  BYTE *   pbInfo;  // extra node information, provider-specific
  DBLENGTH cbInfo;  // size of the data in pbInfo
  GUID     guid;    // this node's GUID
} DBBYGUID;

Remarks

The information stored in the pbInfo member is provider-specific, and provides for operation extensibility.


DBCOMMANDTREE

The DBCOMMANDTREE structure is the primary data structure used to represent any node in an OLE DB command tree, as described in the Data Manipulation Operators section of this reference. This structure is used for each data manipulation language (DML) in an OLE DB command tree.

typedef struct tagDBCOMMANDTREE {
  DBCOMMANDOP op;          // Operator identifier (2 bytes)
  WORD        wKind;       // Discriminator for the following union (2 bytes)
  struct tagDBCOMMANDTREE * pctFirstChild;  // Pointer to first child (4 bytes)
  struct tagDBCOMMANDTREE * pctNextSibling; // Pointer to sibling (4 bytes)
  union {  // Union directly represents fields that fit within 8 bytes.
           // Comments list DBVALUEKIND and DBTYPE corresponding to each field.
    __int64                 llValue;      // DBVALUEKIND_I8        (DBTYPE_I8)
    unsigned __int64        ullValue;     // DBVALUEKIND_UI8       (DBTYPE_UI8)
    BOOL                    fValue;       // DBVALUEKIND_BOOL      (DBTYPE_BOOL)
    unsigned char           uchValue;     // DBVALUEKIND_UI1       (DBTYPE_UI1)
    signed char             schValue;     // DBVALUEKIND_I1        (DBTYPE_I1)
    unsigned short          usValue;      // DBVALUEKIND_UI2       (DBTYPE_UI2)
    short                   sValue;       // DBVALUEKIND_I2        (DBTYPE_I2)
    LPOLESTR                pwszValue;    // DBVALUEKIND_WSTR      (DBTYPE_WSTR)
    LONG                    lValue;       // DBVALUEKIND_I4        (DBTYPE_I4)
    ULONG                   ulValue;      // DBVALUEKIND_UI4       (DBTYPE_UI4)
    float                   flValue;      // DBVALUEKIND_R4        (DBTYPE_R4)
    double                  dblValue;     // DBVALUEKIND_R8        (DBTYPE_R8)
    CY                      cyValue;      // DBVALUEKIND_CY        (DBTYPE_CY)
    DATE                    dateValue;    // DBVALUEKIND_DATE      (DBTYPE_DATE)
    DBDATE                  dbdateValue;  // DBVALUEKIND_DBDATE    (DBTYPE_DBDATE)
    DBTIME                  dbtimeValue;  // DBVALUEKIND_DBTIME    (DBTYPE_DBTIME)
    SCODE                   scodeValue;   // DBVALUEKIND_ERROR     (DBTYPE_ERROR)
    BSTR *                  pbstrValue;   // DBVALUEKIND_BSTR      (DBTYPE_BSTR)
    ICommand *              pCommand;     // DBVALUEKIND_COMMAND   (DBTYPE_IUNKNOWN)
    IDispatch *             pDispatch;    // DBVALUEKIND_IDISPATCH (DBTYPE_IDISPATCH)
    IMoniker *              pMoniker;     // DBVALUEKIND_MONIKER   (DBTYPE_MONIKER)
    IRowset *               pRowset;      // DBVALUEKIND_ROWSET    (DBTYPE_ROWSET)
    IUnknown *              pUnknown;     // DBVALUEKIND_IUNKNOWN  (DBTYPE_IUNKNOWN)
    DBBYGUID *              pdbbygdValue;     // DBVALUEKIND_BYGUID
    DBCOLUMNDESC *          pcoldescValue;    // DBVALUEKIND_COLDESC
    DBID *                  pdbidValue;       // DBVALUEKIND_ID
    DBLIKE *                pdblikeValue;     // DBVALUEKIND_LIKE
    DBCONTENT *             pdbcntntValue;    // DBVALUEKIND_CONTENT
    DBCONTENTSCOPE *        pdbcntntscpValue; // DBVALUEKIND_CONTENTSCOPE
    DBCONTENTTABLE *        pdbcntnttblValue; // DBVALUEKIND_CONTENTTABLE
    DBCONTENTVECTOR *       pdbcntntvcValue;  // DBVALUEKIND_CONTENTVECTOR
    DBCONTENTPROXIMITY *    pdbcntntproxValue;// DBVALUEKIND_CONTENTPROXIMITY
    DBGROUPINFO *           pdbgrpinfValue;   // DBVALUEKIND_GROUPINFO
    DBPARAMETER *           pdbparamValue;    // DBVALUEKIND_PARAMETER
    DBPROPSET *             pdbpropValue;     // DBVALUEKIND_PROPERTY
    DBSETFUNC *             pdbstfncValue;    // DBVALUEKIND_SETFUNC
    DBSORTINFO *            pdbsrtinfValue;   // DBVALUEKIND_SORTINFO
    DBTEXT *                pdbtxtValue;      // DBVALUEKIND_TEXT
    DBVECTOR *              pdbvectorValue;   // DBVALUEKIND_VECTOR | *
    SAFEARRAY *             parrayValue;      // DBVALUEKIND_ARRAY | *
    VARIANT *               pvarValue;        // DBVALUEKIND_VARIANT  (DBTYPE_VARIANT)
    GUID *                  pGuid;            // DBVALUEKIND_GUID     (DBTYPE_GUID)
    BYTE *                  pbValue;          // DBVALUEKIND_BYTES    (DBTYPE_BYTES)
    char *                  pzValue;          // DBVALUEKIND_STR      (DBTYPE_STR)
    DB_NUMERIC *            pdbnValue;        // DBVALUEKIND_NUMERIC  (DBTYPE_NUMERIC)
    DBTIMESTAMP *           pdbtsValue;       // DBVALUEKIND_DBTIMESTAMP (DBTYPE_DBTIMESTAMP)
    void *                  pvValue;          // a generic DBVALUEKIND_BYREF
    DBPROBABILISTIC *       pdbprobValue;     // DBVALUEKIND_PROBABILISTIC
    DBRELEVANTDOC *         pdbreldocValue;   // DBVALUEKIND_RELEVANTDOCUMENT
  } value;
  HRESULT   hrError;     // Error indicator, details in Extended Error info (4 bytes)
} DBCOMMANDTREE;

Members

op
A value of type DBCOMMANDOP from the DBCOMMANDOPENUM enumeration. It specifies an operator from the Data Manipulation Operators that defines the operation to take place on the associated field.
wKind
A value of type DBVALUEKIND from the DBVALUEKINDENUM enumerated type. It defines the data type of the associated union member so that the command processor knows how to interpret it.
pctFirstChild
A pointer to the DBCOMMANDTREE structure that represents the first child of this node of the command tree.
pctNextSibling
A pointer to the DBCOMMANDTREE structure that represents the next child of this node of the command tree.
llvalue
A union to hold the value for every data type supported by this OLE DB provider. For any union member data type that holds 8 bytes or less, the value itself is stored here. Otherwise, llvalue is a pwszValue member, a pointer to the data.

A pwszValue member is a string; its interpretation is left to the provider. In other words, the consumer must understand the provider's method of name resolution. For command components "passed through" to another provider, it is left to the receiving provider to interpret the string.

The pMoniker member is used for unresolved linked objects, in particular tables and functions.

The pRowset member is used to reference a currently open rowset as input for a command. Most providers will fail if an IPersist method is invoked while the command tree refers to an open rowset.

The pCommand member references another command object as input for a command. Most providers will fail if an IPersist method is invoked while the command tree refers to a command object that does not support monikers.

Remarks

Many operations create a binding environment. For example, a DBOP_select operation has two inputs — a table and a Boolean predicate. (For more information on this operation, see Operators with Two Variants for Ordered and Non-Ordered Tables.) By virtue of the "select" operation, the table becomes the binding environment for the predicate. That means that the predicate may freely reference column names defined in the table. Note that not all bindings must come from the nearest table operation. For example, there might be multiple table operations within an "exist" expression, and any predicate may reference a column defined outside the "exist" expression. (In SQL, this is called a "correlated subquery.")

The typical size of a DBCOMMANDTREE structure for a node is 24 bytes. However, operators may store some specific information in the value field of the node. For programming convenience, the union field includes branches representing some common types that can fit within 8 bytes. Variable-length types are referenced via a pointer to the corresponding structure (such as DBTEXT). The discriminator for the union is of type WORD rather than DBVALUEKIND so that it is possible to store node values such as DBVALUEKIND_VECTOR | DBVALUEKIND_GUID, DBVALUEKIND_BYREF | DBVALUEKIND_UI4, or DBVALUEKIND_SAFEARRAY | DBVALUEKIND_I4.


DBCONTENT

The DBCONTENT structure represents specific information required by the DBOP_content operator.

typedef struct tagDBCONTENT {
  LPWSTR pwszPhrase;        // text
  DWORD  dwGenerateMethod;  // exact, prefix, stemmed
  LONG   lWeight;           // weight of node
  LCID   lcid;              // locale
} DBCONTENT;

Remarks

For valid values of the dwGenerateMethod member, see Generate Method Constants.

For more information on the DBOP_content operator, see Content Search Operators.


DBCONTENTPROXIMITY

The DBCONTENTPROXIMITY structure represents specific information required by the DBOP_content_proximity operator.

typedef struct  tagDBCONTENTPROXIMITY    {
  DWORD dwProximityUnit;      // words, paras, chapters etc.
  ULONG ulProximityDistance;  // how near is "near"?
  LONG  lWeight;              // weight of the proximity node
} DBCONTENTPROXIMITY;

Remarks

For valid values of the dwProximityUnit member, see Proximity Unit Constants.

For more information on the DBOP_content_proximity operator, see Content Search Operators.


DBCONTENTSCOPE

The DBCONTENTSCOPE structure is used to pass a scope argument in a command tree.

typedef struct tagDBCONTENTSCOPE {
  DWORD      dwFlags;           // flags from DBPROP_CI_SCOPE_FLAGS
  LPOLESTR * rgpwszTagName;     // reserved for future use.
  LPOLESTR   pwszElementValue;  // DBPROP_CI_INCLUDE_SCOPES property for the path
} DBCONTENTSCOPE;


DBCONTENTTABLE

The DBCONTENTTABLE structure represents the machine and catalog names for a command tree.

typedef struct tagDBCONTENTTABLE {
  LPOLESTR pwszMachine;  // machine on which to process query
  LPOLESTR pwszCatalog;  // catalog over which to process query
} DBCONTENTTABLE;


DBCONTENTVECTOR

The DBCONTENTVECTOR structure represents specific information required by the DBOP_content_vector_or operator.

typedef struct tagDBCONTENTVECTOR {
  DWORD dwRankingMethod;  // jaccard, dice, etc.
  LONG  lWeights;         // node weight
} DBCONTENTVECTOR ;

Remarks

For valid values of the dwRankingMethod member, see Vector Rank Constants.

For more information on the DBOP_content_vector operator, see Content Search Operators.


DBGROUPINFO

The DBGROUPINFO structure represents specific information required by grouping operators, such as project_list_ elements used for grouping.

typedef struct tagDBGROUPINFO {
  LCID lcid;  // local ID for text portion of query
} DBGROUPINFO ;


DBID

The DBID structure encapsulates various ways of identifying a database object. It is used by nodes that must represent a column name, such as column_name, index_name, table_name, schema_name, catalog_name, and so forth. (For more information on these nodes, see Catalog of DML Nodes.) This structure is also used to define bindings.

typedef struct tagDBID {
  union {
    GUID   guid;
    GUID * pguid;
  } uGuid;
  DBKIND eKind;
  union {
    LPWSTR pwszName;
    ULONG  ulPropid;
  } uName;
} DBID;

Remarks

The DBID structure identifies the requested columns for a query. Each unique column is represented by a unique combination of GUID and number or GUID and name.


DBLIKE

The DBLIKE structure represents specific information required by the DBOP_like operator.

typedef struct tagDBLIKE {
  LONG lWeight;      // weight on the dbop_like node
  GUID guidDialect;  // system to use for "likeness". E.g. Reg. Ex.
} DBLIKE;

Remarks

For more information about the DBOP_like operator, see Operators for Scalars.


DBPARAMETER

The DBPARAMETER structure is used to define values for scalar parameters.

typedef struct tagDBPARAMETER {
  LPWSTR       pwszName;     // parameter name
  ITypeInfo *  pTypeInfo;    // if not a null pointer, type is described
                             // by the ITypeInfo
  DBNUMERIC *  pNum;         // Structure describing the
                             // precision, scale and value of
                             // the numeric value.
  DBLENGTH     cbMaxLength;  // the maximum length of the parameter
  DBPARAMFLAGS dwFlags;      // bitmask describing parameter characteristics
  DBTYPE       wType;        // type of the parameter
} DBPARAMETER;

Remarks

Note that there is no entry for the ordinal position of the parameter. The assumption is that the ordinal position will be determined by the provider after evaluating the tree as a whole, and not by assigning a specific value to an individual member within the tree. Data consumers can determine the ordinal position based on the name using ICommandWithParameters::MapParameterNames. For more information about the interface, see ICommandWithParameters.


DBPROBABILISTIC

The DBPROBABILISTIC structure is reserved for future use.

typedef struct tagDBPROBABILISTIC {
  LONG  lWeight;
  float flK1;
  float flK2;
  float flK3;
  float flB;
} DBPROBABILISTIC;


DBRELEVANTDOCUMENT

The DBRELEVANTDOCUMENT structure is reserved for future use.

typedef struct tagDBRELEVANTDOCUMENT {
  LONG    lWeight;
  VARIANT vDocument;
} DBRELEVANTDOCUMENT;


DBSETFUNC

The DBSETFUNC structure specifies the aggregation function to use in a select operation.

typedef struct tagDBSETFUNC {
  DWORD dwSetQuantifier;  // which aggregation method to use
} DBSETFUNC;

Remarks

For valid values of the dwSetQuantifier member, see Aggregate Function Constants.


DBSORTINFO

The DBSORTINFO structure stores the order in which a column will be sorted (that is, ascending or descending). This information is stored inside a DBOP_sort_list_element node.

typedef struct  tagDBSORTINFO {
  BOOL fDesc;  // TRUE = ascending, FALSE = descending
  LCID lcid;   // locale identifier
} DBSORTINFO;

Remarks

The locale identifier (LCID) specifies a set of user preference information related to the user's language. It determines how times are formatted, how items are alphabetically sorted, and how strings are compared.

For additional information on LCIDs see Locales.


DBTEXT

The DBTEXT structure is used by the DBOP_text_command node. It stores the dialect to use to interpret the string stored in the pwszText member. The error locator is filled in by the provider, that is, the first offending token is indicated as the index into the text array, together with its length.

typedef struct tagDBTEXT {
  LPWSTR pwszText;
  ULONG  ulErrorLocator;  // set by validation routines
  ULONG  ulTokenLength;   // length of offending token
  GUID   guidDialect;     // GUID of the language and dialect
} DBTEXT;

Remarks

For additional information about the guidDialect parameter, see the description of DBOP_text_command in Special Operators.


Enumerated Types

The OLE DB Provider for Indexing Service provides several enumerated types for use with interfaces. This section describes the following enumerated types for a command tree.

  • DBCOMMANDOPENUM
  • DBCOMMANDREUSEENUM
  • DBKINDENUM
  • DBVALUEKINDENUM


DBCOMMANDOPENUM

The DBCOMMANDOPENUM enumerated type contains a list of the possible command operators for nodes in a command tree.

enum DBCOMMANDOPENUM {
  DBOP_scalar_constant            = 0,  // Indexing Service
  DBOP_DEFAULT                    = DBOP_scalar_constant + 1,  // Indexing Service
  DBOP_NULL                       = DBOP_DEFAULT + 1,  // Indexing Service
  DBOP_bookmark_name              = DBOP_NULL + 1,
  DBOP_catalog_name               = DBOP_bookmark_name + 1,  // Indexing Service
  DBOP_column_name                = DBOP_catalog_name + 1,  // Indexing Service
  DBOP_schema_name                = DBOP_column_name + 1,
  DBOP_outall_name                = DBOP_schema_name + 1,  // Indexing Service
  DBOP_qualifier_name             = DBOP_outall_name + 1,
  DBOP_qualified_column_name      = DBOP_qualifier_name + 1,
  DBOP_table_name                 = DBOP_qualified_column_name + 1,  // Indexing Service
  DBOP_nested_table_name          = DBOP_table_name + 1,
  DBOP_nested_column_name         = DBOP_nested_table_name + 1,
  DBOP_row                        = DBOP_nested_column_name + 1,
  DBOP_table                      = DBOP_row + 1,
  DBOP_sort                       = DBOP_table + 1,  // Indexing Service
  DBOP_distinct                   = DBOP_sort + 1,
  DBOP_distinct_order_preserving  = DBOP_distinct + 1,
  DBOP_alias                      = DBOP_distinct_order_preserving + 1,  // Indexing Service
  DBOP_cross_join                 = DBOP_alias + 1,
  DBOP_union_join                 = DBOP_cross_join + 1,
  DBOP_inner_join                 = DBOP_union_join + 1,
  DBOP_left_semi_join             = DBOP_inner_join + 1,
  DBOP_right_semi_join            = DBOP_left_semi_join + 1,
  DBOP_left_anti_semi_join        = DBOP_right_semi_join + 1,
  DBOP_right_anti_semi_join       = DBOP_left_anti_semi_join + 1,
  DBOP_left_outer_join            = DBOP_right_anti_semi_join + 1,
  DBOP_right_outer_join           = DBOP_left_outer_join + 1,
  DBOP_full_outer_join            = DBOP_right_outer_join + 1,
  DBOP_natural_join               = DBOP_full_outer_join + 1,
  DBOP_natural_left_outer_join    = DBOP_natural_join + 1,
  DBOP_natural_right_outer_join   = DBOP_natural_left_outer_join + 1,
  DBOP_natural_full_outer_join    = DBOP_natural_right_outer_join + 1,
  DBOP_set_intersection           = DBOP_natural_full_outer_join + 1,
  DBOP_set_union                  = DBOP_set_intersection + 1,  // Indexing Service
  DBOP_set_left_difference        = DBOP_set_union + 1,
  DBOP_set_right_difference       = DBOP_set_left_difference + 1,
  DBOP_set_anti_difference        = DBOP_set_right_difference + 1,
  DBOP_bag_intersection           = DBOP_set_anti_difference + 1,
  DBOP_bag_union                  = DBOP_bag_intersection + 1,
  DBOP_bag_left_difference        = DBOP_bag_union + 1,
  DBOP_bag_right_difference       = DBOP_bag_left_difference + 1,
  DBOP_bag_anti_difference        = DBOP_bag_right_difference + 1,
  DBOP_division                   = DBOP_bag_anti_difference + 1,
  DBOP_relative_sampling          = DBOP_division + 1,
  DBOP_absolute_sampling          = DBOP_relative_sampling + 1,
  DBOP_transitive_closure         = DBOP_absolute_sampling + 1,
  DBOP_recursive_union            = DBOP_transitive_closure + 1,
  DBOP_aggregate                  = DBOP_recursive_union + 1,
  DBOP_remote_table               = DBOP_aggregate + 1,
  DBOP_select                     = DBOP_remote_table + 1,  // Indexing Service
  DBOP_order_preserving_select    = DBOP_select + 1,
  DBOP_project                    = DBOP_order_preserving_select + 1,  // Indexing Service
  DBOP_project_order_preserving   = DBOP_project + 1,
  DBOP_top                        = DBOP_project_order_preserving + 1,  // Indexing Service
  DBOP_top_percent                = DBOP_top + 1,
  DBOP_top_plus_ties              = DBOP_top_percent + 1,
  DBOP_top_percent_plus_ties      = DBOP_top_plus_ties + 1,
  DBOP_rank                       = DBOP_top_percent_plus_ties + 1,
  DBOP_rank_ties_equally          = DBOP_rank + 1,
  DBOP_rank_ties_equally_and_skip = DBOP_rank_ties_equally + 1,
  DBOP_navigate                   = DBOP_rank_ties_equally_and_skip + 1,
  DBOP_nesting                    = DBOP_navigate + 1,  // Indexing Service
  DBOP_unnesting                  = DBOP_nesting + 1,
  DBOP_nested_apply               = DBOP_unnesting + 1,
  DBOP_cross_tab                  = DBOP_nested_apply + 1,
  DBOP_is_NULL                    = DBOP_cross_tab + 1,
  DBOP_is_NOT_NULL                = DBOP_is_NULL + 1,  // Indexing Service
  DBOP_equal                      = DBOP_is_NOT_NULL + 1,  // Indexing Service
  DBOP_not_equal                  = DBOP_equal + 1,  // Indexing Service
  DBOP_less                       = DBOP_not_equal + 1,  // Indexing Service
  DBOP_less_equal                 = DBOP_less + 1,  // Indexing Service
  DBOP_greater                    = DBOP_less_equal + 1,  // Indexing Service
  DBOP_greater_equal              = DBOP_greater + 1,
  DBOP_equal_all                  = DBOP_greater_equal + 1,  // Indexing Service
  DBOP_not_equal_all              = DBOP_equal_all + 1,  // Indexing Service
  DBOP_less_all                   = DBOP_not_equal_all + 1,  // Indexing Service
  DBOP_less_equal_all             = DBOP_less_all + 1,  // Indexing Service
  DBOP_greater_all                = DBOP_less_equal_all + 1,  // Indexing Service
  DBOP_greater_equal_all          = DBOP_greater_all + 1,  // Indexing Service
  DBOP_equal_any                  = DBOP_greater_equal_all + 1,  // Indexing Service
  DBOP_not_equal_any              = DBOP_equal_any + 1,  // Indexing Service
  DBOP_less_any                   = DBOP_not_equal_any + 1,  // Indexing Service
  DBOP_less_equal_any             = DBOP_less_any + 1,  // Indexing Service
  DBOP_greater_any                = DBOP_less_equal_any + 1,  // Indexing Service
  DBOP_greater_equal_any          = DBOP_greater_any + 1,  // Indexing Service
  DBOP_anybits                    = DBOP_greater_equal_any + 1,  // Indexing Service
  DBOP_allbits                    = DBOP_anybits + 1,  // Indexing Service
  DBOP_anybits_any                = DBOP_allbits + 1,  // Indexing Service
  DBOP_allbits_any                = DBOP_anybits_any + 1,  // Indexing Service
  DBOP_anybits_all                = DBOP_allbits_any + 1,  // Indexing Service
  DBOP_allbits_all                = DBOP_anybits_all + 1,  // Indexing Service
  DBOP_between                    = DBOP_allbits_all + 1,
  DBOP_between_unordered          = DBOP_between + 1,
  DBOP_match                      = DBOP_between_unordered + 1,
  DBOP_match_unique               = DBOP_match + 1,
  DBOP_match_partial              = DBOP_match_unique + 1,
  DBOP_match_partial_unique       = DBOP_match_partial + 1,
  DBOP_match_full                 = DBOP_match_partial_unique + 1,
  DBOP_match_full_unique          = DBOP_match_full + 1,
  DBOP_scalar_parameter           = DBOP_match_full_unique + 1,
  DBOP_scalar_function            = DBOP_scalar_parameter + 1,
  DBOP_plus                       = DBOP_scalar_function + 1,
  DBOP_minus                      = DBOP_plus + 1,
  DBOP_times                      = DBOP_minus + 1,
  DBOP_over                       = DBOP_times + 1,
  DBOP_div                        = DBOP_over + 1,
  DBOP_modulo                     = DBOP_div + 1,
  DBOP_power                      = DBOP_modulo + 1,
  DBOP_like                       = DBOP_power + 1,  // Indexing Service
  DBOP_sounds_like                = DBOP_like + 1,
  DBOP_like_any                   = DBOP_sounds_like + 1,
  DBOP_like_all                   = DBOP_like_any + 1,
  DBOP_is_INVALID                 = DBOP_like_all + 1,  // Indexing Service
  DBOP_is_TRUE                    = DBOP_is_INVALID + 1,  // Indexing Service
  DBOP_is_FALSE                   = DBOP_is_TRUE + 1,  // Indexing Service
  DBOP_and                        = DBOP_is_FALSE + 1,  // Indexing Service
  DBOP_or                         = DBOP_and + 1,  // Indexing Service
  DBOP_xor                        = DBOP_or + 1,
  DBOP_equivalent                 = DBOP_xor + 1,
  DBOP_not                        = DBOP_equivalent + 1,  // Indexing Service
  DBOP_implies                    = DBOP_not + 1,
  DBOP_overlaps                   = DBOP_implies + 1,
  DBOP_case_condition             = DBOP_overlaps + 1,
  DBOP_case_value                 = DBOP_case_condition + 1,
  DBOP_nullif                     = DBOP_case_value + 1,
  DBOP_cast                       = DBOP_nullif + 1,
  DBOP_coalesce                   = DBOP_cast + 1,
  DBOP_position                   = DBOP_coalesce + 1,
  DBOP_extract                    = DBOP_position + 1,
  DBOP_char_length                = DBOP_extract + 1,
  DBOP_octet_length               = DBOP_char_length + 1,
  DBOP_bit_length                 = DBOP_octet_length + 1,
  DBOP_substring                  = DBOP_bit_length + 1,
  DBOP_upper                      = DBOP_substring + 1,
  DBOP_lower                      = DBOP_upper + 1,
  DBOP_trim                       = DBOP_lower + 1,
  DBOP_translate                  = DBOP_trim + 1,
  DBOP_convert                    = DBOP_translate + 1,
  DBOP_string_concat              = DBOP_convert + 1,
  DBOP_current_date               = DBOP_string_concat + 1,
  DBOP_current_time               = DBOP_current_date + 1,
  DBOP_current_timestamp          = DBOP_current_time + 1,
  DBOP_content_select             = DBOP_current_timestamp + 1,
  DBOP_content                    = DBOP_content_select + 1,  // Indexing Service
  DBOP_content_freetext           = DBOP_content + 1,  // Indexing Service
  DBOP_content_proximity          = DBOP_content_freetext + 1,  // Indexing Service
  DBOP_content_vector_or          = DBOP_content_proximity + 1,  // Indexing Service
  DBOP_delete                     = DBOP_content_vector_or + 1,
  DBOP_update                     = DBOP_delete + 1,
  DBOP_insert                     = DBOP_update + 1,
  DBOP_min                        = DBOP_insert + 1,
  DBOP_max                        = DBOP_min + 1,
  DBOP_count                      = DBOP_max + 1,
  DBOP_sum                        = DBOP_count + 1,
  DBOP_avg                        = DBOP_sum + 1,
  DBOP_any_sample                 = DBOP_avg + 1,
  DBOP_stddev                     = DBOP_any_sample + 1,
  DBOP_stddev_pop                 = DBOP_stddev + 1,
  DBOP_var                        = DBOP_stddev_pop + 1,
  DBOP_var_pop                    = DBOP_var + 1,
  DBOP_first                      = DBOP_var_pop + 1,
  DBOP_last                       = DBOP_first + 1,
  DBOP_in                         = DBOP_last + 1,
  DBOP_exists                     = DBOP_in + 1,
  DBOP_unique                     = DBOP_exists + 1,
  DBOP_subset                     = DBOP_unique + 1,
  DBOP_proper_subset              = DBOP_subset + 1,
  DBOP_superset                   = DBOP_proper_subset + 1,
  DBOP_proper_superset            = DBOP_superset + 1,
  DBOP_disjoint                   = DBOP_proper_superset + 1,
  DBOP_pass_through               = DBOP_disjoint + 1,
  DBOP_defined_by_GUID            = DBOP_pass_through + 1,
  DBOP_text_command               = DBOP_defined_by_GUID + 1,
  DBOP_SQL_select                 = DBOP_text_command + 1,
  DBOP_prior_command_tree         = DBOP_SQL_select + 1,
  DBOP_add_columns                = DBOP_prior_command_tree + 1,
  DBOP_column_list_anchor         = DBOP_add_columns + 1,
  DBOP_column_list_element        = DBOP_column_list_anchor + 1,
  DBOP_command_list_anchor        = DBOP_column_list_element + 1,
  DBOP_command_list_element       = DBOP_command_list_anchor + 1,
  DBOP_from_list_anchor           = DBOP_command_list_element + 1,
  DBOP_from_list_element          = DBOP_from_list_anchor + 1,
  DBOP_project_list_anchor        = DBOP_from_list_element + 1,  // Indexing Service
  DBOP_project_list_element       = DBOP_project_list_anchor + 1,  // Indexing Service
  DBOP_row_list_anchor            = DBOP_project_list_element + 1,
  DBOP_row_list_element           = DBOP_row_list_anchor + 1,
  DBOP_scalar_list_anchor         = DBOP_row_list_element + 1,
  DBOP_scalar_list_element        = DBOP_scalar_list_anchor + 1,
  DBOP_set_list_anchor            = DBOP_scalar_list_element + 1,
  DBOP_set_list_element           = DBOP_set_list_anchor + 1,
  DBOP_sort_list_anchor           = DBOP_set_list_element + 1,  // Indexing Service
  DBOP_sort_list_element          = DBOP_sort_list_anchor + 1,  // Indexing Service
  DBOP_alter_character_set        = DBOP_sort_list_element + 1,
  DBOP_alter_collation            = DBOP_alter_character_set + 1,
  DBOP_alter_domain               = DBOP_alter_collation + 1,
  DBOP_alter_index                = DBOP_alter_domain + 1,
  DBOP_alter_procedure            = DBOP_alter_index + 1,
  DBOP_alter_schema               = DBOP_alter_procedure + 1,
  DBOP_alter_table                = DBOP_alter_schema + 1,
  DBOP_alter_trigger              = DBOP_alter_table + 1,
  DBOP_alter_view                 = DBOP_alter_trigger + 1,
  DBOP_coldef_list_anchor         = DBOP_alter_view + 1,
  DBOP_coldef_list_element        = DBOP_coldef_list_anchor + 1,
  DBOP_create_assertion           = DBOP_coldef_list_element + 1,
  DBOP_create_character_set       = DBOP_create_assertion + 1,
  DBOP_create_collation           = DBOP_create_character_set + 1,
  DBOP_create_domain              = DBOP_create_collation + 1,
  DBOP_create_index               = DBOP_create_domain + 1,
  DBOP_create_procedure           = DBOP_create_index + 1,
  DBOP_create_schema              = DBOP_create_procedure + 1,
  DBOP_create_synonym             = DBOP_create_schema + 1,
  DBOP_create_table               = DBOP_create_synonym + 1,
  DBOP_create_temporary_table     = DBOP_create_table + 1,
  DBOP_create_translation         = DBOP_create_temporary_table + 1,
  DBOP_create_trigger             = DBOP_create_translation + 1,
  DBOP_create_view                = DBOP_create_trigger + 1,
  DBOP_drop_assertion             = DBOP_create_view + 1,
  DBOP_drop_character_set         = DBOP_drop_assertion + 1,
  DBOP_drop_collation             = DBOP_drop_character_set + 1,
  DBOP_drop_domain                = DBOP_drop_collation + 1,
  DBOP_drop_index                 = DBOP_drop_domain + 1,
  DBOP_drop_procedure             = DBOP_drop_index + 1,
  DBOP_drop_schema                = DBOP_drop_procedure + 1,
  DBOP_drop_synonym               = DBOP_drop_schema + 1,
  DBOP_drop_table                 = DBOP_drop_synonym + 1,
  DBOP_drop_translation           = DBOP_drop_table + 1,
  DBOP_drop_trigger               = DBOP_drop_translation + 1,
  DBOP_drop_view                  = DBOP_drop_trigger + 1,
  DBOP_foreign_key                = DBOP_drop_view + 1,
  DBOP_grant_privileges           = DBOP_foreign_key + 1,
  DBOP_index_list_anchor          = DBOP_grant_privileges + 1,
  DBOP_index_list_element         = DBOP_index_list_anchor + 1,
  DBOP_primary_key                = DBOP_index_list_element + 1,
  DBOP_property_list_anchor       = DBOP_primary_key + 1,
  DBOP_property_list_element      = DBOP_property_list_anchor + 1,
  DBOP_referenced_table           = DBOP_property_list_element + 1,
  DBOP_rename_object              = DBOP_referenced_table + 1,
  DBOP_revoke_privileges          = DBOP_rename_object + 1,
  DBOP_schema_authorization       = DBOP_revoke_privileges + 1,
  DBOP_unique_key                 = DBOP_schema_authorization + 1,
  DBOP_scope_list_anchor          = DBOP_unique_key + 1,  // Indexing Service
  DBOP_scope_list_element         = DBOP_scope_list_anchor + 1,  // Indexing Service
  DBOP_content_table              = DBOP_scope_list_element + 1  // Indexing Service
};

Remarks

The OLE DB Provider for Indexing Service does not support all the operators in this enumerated type. Indexing Service supports only elements in the list designated by the comment "// Indexing Service".

For information about individual operators, see Data Manipulation Operators.


DBCOMMANDREUSEENUM

The DBCOMMANDREUSEENUM enumerated type specifies whether a state from the previous command is retained.

enum DBCOMMANDREUSEENUM {
  DBCOMMANDREUSE_NONE       = 0,    // don't reuse the previous state
  DBCOMMANDREUSE_PROPERTIES = 0x1,  // reserved for future use
  DBCOMMANDREUSE_PARAMETERS = 0x2   // reserved for future use
};

Remarks

The ICommandTree::SetCommandTree method uses a value from this enumerated type as a parameter.


DBKINDENUM

The DBKINDENUM enumerated type specifies the combination of GUID, property number, or property name to use to identify a database object.

enum DBKINDENUM {
  DBKIND_GUID_NAME    = 0,                        // use the guid and pwszName members
  DBKIND_GUID_PROPID  = DBKIND_GUID_NAME + 1,     // use the guid and ulPropid members
  DBKIND_NAME         = DBKIND_GUID_PROPID + 1,   // use only the pwszName member, and
                                                  // ignore the uGuid member
  DBKIND_PGUID_NAME   = DBKIND_NAME + 1,          // use the pGuid and pwszName members
  DBKIND_PGUID_PROPID = DBKIND_PGUID_NAME + 1,    // use the pGuid and ulPropid members
  DBKIND_PROPID       = DBKIND_PGUID_PROPID + 1,  // use only the ulPropid member, and
                                                  //  ignore the uGuid member
  DBKIND_GUID         = DBKIND_PROPID + 1         // use only the guid member
};

Remarks

The DBID structure uses a value from this enumerated type as a parameter.

The OLE DB Provider for Indexing Service accepts only the DBKIND_GUID_NAME, DBKIND_GUID_PROPID, DBKIND_PGUID_NAME, and DBKIND_PGUID_PROPID values.


DBVALUEKINDENUM

The DBVALUEKINDENUM enumerated type is used to indicate the type of the union member inside a DBCOMMANDTREE structure. For programming convenience, the values in this enumeration correspond exactly to the OLE Automation VARENUM and OLE DB DBTYPE enumerations. The comments associated with each enumeration value represent the type and branch of the union type inside the command structure containing the value. nodes that do not assign a value to the union member should assign a DBVALUEKIND_EMPTY to the wKind member of the DBCOMMANDTREE structure.

enum DBVALUEKINDENUM {
  // List of structure values     union contains a pointer to:
  DBVALUEKIND_BYGUID           = 256.                           // DBBYGUID struct
  DBVALUEKIND_COLDESC          = DBVALUEKIND_BYGUID + 1,        // DBCOLDESC struct
  DBVALUEKIND_ID               = DBVALUEKIND_COLDESC + 1,       // DBID struct
  DBVALUEKIND_CONTENT          = DBVALUEKIND_ID + 1,            // DBCONTENT struct
  DBVALUEKIND_CONTENTVECTOR    = DBVALUEKIND_CONTENT + 1,       // DBCONTENTVECTOR struct
  DBVALUEKIND_GROUPINFO        = DBVALUEKIND_CONTENTVECTOR + 1, // DBGROUPINFO struct
  DBVALUEKIND_PARAMETER        = DBVALUEKIND_GROUPINFO + 1,     // DBPARAMETER struct
  DBVALUEKIND_PROPERTY         = DBVALUEKIND_PARAMETER + 1,     // DBPROPERTY struct
  DBVALUEKIND_SETFUNC          = DBVALUEKIND_PROPERTY + 1,      // DBSETFUNC struct
  DBVALUEKIND_SORTINFO         = DBVALUEKIND_SETFUNC + 1,       // DBSORTINFO struct
  DBVALUEKIND_TEXT             = DBVALUEKIND_SORTINFO + 1,      // DBTEXT struct

  // List of OLE interface pointer values
  DBVALUEKIND_COMMAND          = DBVALUEKIND_TEXT + 1,          // pCommand value
  DBVALUEKIND_MONIKER          = DBVALUEKIND_COMMAND + 1,       // pMoniker value
  DBVALUEKIND_ROWSET           = DBVALUEKIND_MONIKER + 1,       // pRowset value
  DBVALUEKIND_LIKE             = DBVALUEKIND_ROWSET + 1,        // DBLIKE struct
  DBVALUEKIND_CONTENTPROXIMITY = DBVALUEKIND_LIKE + 1,          // DBCONTENTPROXIMITY structure
  DBVALUEKIND_CONTENTSCOPE     = DBVALUEKIND_CONTENTPROXIMITY + 1  // DBCONTENTSCOPE structure
  DBVALUEKIND_CONTENTTABLE     = DBVALUEKIND_CONTENTSCOPE + 1   // DBCONTENTTABLE structure
  DBVALUEKIND_IDISPATCH        = 9,                             // pDispatch value
  DBVALUEKIND_IUNKNOWN         = 13,                            // pUnknown value

  // List of OLE DB type values
  DBVALUEKIND_EMPTY            = 0,                            // No value assigned to
                                                               // the union
  DBVALUEKIND_NULL             = 1,                            // NULL value
  DBVALUEKIND_I2               = 2,                            // sValue
  DBVALUEKIND_I4               = 3,                            // lValue
  DBVALUEKIND_R4               = 4,                            // flValue
  DBVALUEKIND_R8               = 5,                            // dblValue
  DBVALUEKIND_CY               = 6,                            // cyValue
  DBVALUEKIND_DATE             = 7,                            // dateValue
  DBVALUEKIND_BSTR             = 8,                            // pbstrValue

  DBVALUEKIND_ERROR            = 10,                           // scodeValue;
  DBVALUEKIND_BOOL             = 11,                           // fValue
  DBVALUEKIND_VARIANT          = 12,                           // pvarValue to an OLE auto variant
  DBVALUEKIND_VECTOR           = 0x1000,                       // pdbvectorValue
  DBVALUEKIND_ARRAY            = 0x2000,                       // parrayValue
  DBVALUEKIND_BYREF            = 0x4000,                       // pvValue

  DBVALUEKIND_I1               = 16,                           // bValue
  DBVALUEKIND_UI1              = 17,                           // bValue
  DBVALUEKIND_UI2              = 18,                           // sValue
  DBVALUEKIND_UI4              = DBVALUEKIND_UI2 + 1,          // ulValue
  DBVALUEKIND_I8               = DBVALUEKIND_UI4 + 1,          // llValue
  DBVALUEKIND_UI8              = DBVALUEKIND_UI8 + 1,          // ullValue
  DBVALUEKIND_GUID             = 72,                           // pGuid

  DBVALUEKIND_BYTES            = 128,                          // pbValue
  DBVALUEKIND_STR              = 129,                          // pszValue
  DBVALUEKIND_WSTR             = 130,                          // pwszValue
  DBVALUEKIND_NUMERIC          = 131,                          // pdbnValue
  DBVALUEKIND_DBDATE           = 133,                          // dbdateValue
  DBVALUEKIND_DBTIME           = 134,                          // dbtimeValue
  DBVALUEKIND_DBTIMESTAMP      = 135,                          // pdbtsValue
  DBVALUEKIND_PROBABILISTIC    = 136,                          // DBPROBABILISTIC structure -- reserved for future use
  DBVALUEKIND_RELEVANTDOCUMENT = 137                           // DBRELEVANTDOCUMENT structure -- reserved for future use
};


Constants

This section describes the following constants for use with the interfaces and structures of the OLE DB Provider for Indexing Service.

  • Aggregate Function Constants
  • Command-Text Node Constants
  • Data Source Object Constant
  • Generate Method Constants
  • Like Operator Constants
  • Proximity Unit Constants
  • Scope Flag and Type Constants
  • Vector Rank Constants


Aggregate Function Constants

The aggregate function constants specify which method of aggregation to use in a select operation.

#define DBSETFUNC_NONE     = 0x0
#define DBSETFUNC_ALL      = 0x1
#define DBSETFUNC_DISTINCT = 0x2

Remarks

The dwSetQuantifier member of the DBSETFUNC structure uses these constants.

These constants are currently reserved for future use.


Command-Text Node Constants

The command-text node constants are a collection of globally unique identifiers (GUIDs) for the dialect of a command-text node.

DBGUID_SQL92       // Reserved for future use.
DBGUID_DBSQL       // This covers SQL used by OLE DB and ODBC.
                   // Deprecated; use DBGUID_DEFAULT instead.
extern const OLEDBDECLSPEC GUID DBGUID_DEFAULT = \
    {0xc8b521fb,0x5cf3,0x11ce, \
        {0xad,0xe5,0x00,0xaa,0x00,0x44,0x77,0x3d}};
DBGUID_TSQL        // Reserved for future use.
DBGUID_ACCESSSQL   // Reserved for future use.

Remarks

To determine which dialects a provider supports, call IDBProperties::GetProperties for the DBPROP_SQLDIALECTS property. (For more information on using the IDBProperties interface, see the OLE DB Programmer's Reference in the Platform SDK.)


Data Source Object Constant

The CLSID_INDEX_SERVER_DSO constant is the Indexing Service data source object (DSO) class ID (CLSID) used to create an Indexing Service DSO with the CoCreateInstance function.

#define CLSID_INDEX_SERVER_DSO \
    { 0xF9AE8980, 0x7E52, 0x11d0, \
      { 0x89, 0x64, 0x00, 0xC0, 0x4F, 0xD6, 0x11, 0xD7 } }

Remarks

For an example of using the DSO CLSID, see Accessing OLE DB with the OLE DB Provider for Indexing Service.


Generate Method Constants

The generate method constants specify the method to use when generating alternate word forms in pattern matching queries.

#define GENERATE_METHOD_EXACT   ( 0 )  // The query string value must match exactly.
#define GENERATE_METHOD_PREFIX  ( 1 )  // The query string value is a prefix for strings in documents.
#define GENERATE_METHOD_INFLECT ( 2 )  // Generate multiple forms of the query string word to match documents.

Remarks

The dwGenerateMethod member of the DBCONTENT structure uses these constants.


Like Operator Constants

The Like operator constants are a collection of globally unique identifiers (GUIDs) for the Like operator.

extern const OLEDBDECLSPEC GUID DBGUID_LIKE_SQL = \
    {0xc8b521f6,0x5cf3,0x11ce,
        {0xad,0xe5,0x00,0xaa,0x00,0x44,0x77,0x3d}};
extern const OLEDBDECLSPEC GUID DBGUID_LIKE_DOS = \
    {0xc8b521f7,0x5cf3,0x11ce,
        {0xad,0xe5,0x00,0xaa,0x00,0x44,0x77,0x3d}};
extern const OLEDBDECLSPEC GUID DBGUID_LIKE_OFS = \
    {0xc8b521f8,0x5cf3,0x11ce,
        {0xad,0xe5,0x00,0xaa,0x00,0x44,0x77,0x3d}};
extern const OLEDBDECLSPEC GUID DBGUID_LIKE_MAPI = \
    {0xc8b521f9,0x5cf3,0x11ce,
        {0xad,0xe5,0x00,0xaa,0x00,0x44,0x77,0x3d}};

Remarks

The OLE DB Provider for Indexing Service uses only the DBGUID_LIKE_OFS constant, which signifies an Indexing Service Like operator.


Proximity Unit Constants

The proximity unit constants specify the unit of measurement for text when applying the proximity operator.

#define PROXIMITY_UNIT_WORD      ( 0 )
#define PROXIMITY_UNIT_SENTENCE  ( 1 )
#define PROXIMITY_UNIT_PARAGRAPH ( 2 )
#define PROXIMITY_UNIT_CHAPTER   ( 3 )

Remarks

The dwProximityUnit member of the DBCONTENTPROXIMITY structure uses these constants.

The OLE DB Provider for Indexing Service currently uses only the PROXIMITRY_UNIT_WORD constant. The other constants are reserved for future use.


Scope Flag and Type Constants

The scope flag and type constants specify whether to include a scope and its subdirectories and whether the scope is a physical or virtual path.

#define SCOPE_FLAG_MASK    ( 0x000000ff )  // mask to select flag
#define SCOPE_FLAG_INCLUDE ( 0x00000001 )  // include scope
#define SCOPE_FLAG_DEEP    ( 0x00000002 )  // include subdirectories

#define SCOPE_TYPE_MASK    ( 0xffffff00 )  // mask to select type
#define SCOPE_TYPE_WINPATH ( 0x00000100 )  // scope is physical
#define SCOPE_TYPE_VPATH   ( 0x00000200 )  // scope is virtual


Vector Rank Constants

The vector rank constants specify the ranking method to use to evaluate the rank of a match in a vector space query.

#define VECTOR_RANK_MIN     ( 0 )  // Use minimum algorithm
#define VECTOR_RANK_MAX     ( 1 )  // Use maximum algorithm
#define VECTOR_RANK_INNER   ( 2 )  // Use inner product algorithm
#define VECTOR_RANK_DICE    ( 3 )  // Use Dice coefficient algorithm
#define VECTOR_RANK_JACCARD ( 4 )  // Use Jaccard coefficient algorithm

Remarks

The dwRankingMethod member of the DBCONTENTVECTOR structure uses these constants.


Other Types

The OLE DB Provider for Indexing Service provides several types for use with interfaces. This section describes the following types.

  • DBCOMMANDOP
  • DBCOMMANDREUSE
  • DBKIND
  • DBVALUEKIND


DBCOMMANDOP

The DBCOMMANDOP type specifies the operation for a command node in the OLE DB command tree.

typedef WORD DBCOMMANDOP;

Remarks

In each DBCOMMANDTREE structure representing a node in the command tree, DBCOMMANDOP takes on the appropriate DBOP_* operation value from the DBCOMMANDOPENUM enumeration, as described in the Data Manipulation Operators section of this reference.

See Also

DBCOMMANDOPENUM, DBCOMMANDTREE


DBCOMMANDREUSE

The DBCOMMANDREUSE type defines a variable that specifies whether a state from the previous command is retained.

typedef WORD DBCOMMANDREUSE;

Remarks

In each DBCOMMANDTREE structure representing a node in the command tree, DBCOMMANDREUSE takes on the appropriate DBCOMMANDREUSE_* value from the DBCOMMANDREUSEENUM enumeration, as described in the Data Manipulation Operators section of this reference.

See Also

DBCOMMANDREUSEENUM, DBCOMMANDTREE


DBKIND

The DBKIND type defines a variable that specifies the type of database object in a command tree.

typedef WORD DBKIND;

Remarks

In each DBCOMMANDTREE structure representing a node in the command tree, DBKIND takes on the appropriate DBKIND_* value from the DBKINDENUM enumeration, as described in the Data Manipulation Operators section of this reference.

See Also

DBCOMMANDTREE, DBKINDENUM


DBVALUEKIND

The DBVALUEKIND type defines a variable that indicates the type of union member inside a DBCOMMANDTREE structure.

typedef WORD DBVALUEKIND;

Remarks

In each DBCOMMANDTREE structure representing a node in the command tree, DBVALUEKIND takes on the appropriate DBVALUEKIND_* operation value from the DBVALUEKINDENUM enumeration, as described in the Data Manipulation Operators section of this reference.

See Also

DBCOMMANDTREE, DBVALUEKINDENUM


Command-Tree Nodes and Operators

This section describes the command-tree nodes used by the OLE DB Provider for Indexing Service. The ICommandTree interface uses these nodes and their corresponding operators. The nodes consist of only data manipulation language (DML) nodes. The section includes the following topics.

  • Catalog of DML Nodes
  • Data Manipulation Operators


Catalog of DML Nodes

This section summarizes all data manipulation language (DML) command nodes. For each node, the section describes the information stored within the node, its required and optional input types, and the types of the output produced by the node. This information represents a first step in defining the correct way to build OLE DB command trees.

The supported output types and minor types are listed in the form

output-type:minor-type

The minor type is not listed if it is not required by the operator. The following table lists the output-types and minor-types.

Output Type | output-type | minor-type | Description
Table1 | T | O U OU H | Ordered Unique Ordered unique Hierarchical
Row | R | — | —
Scalar | S | AF BMK COL CON DEF EXP NUL PAR SF | Aggregate function Bookmark Column Constant Default Expression NULL Parameter Scalar function
Boolean | B | — | —
List anchor | LA_CD LA_COL LA_CMD LA_FRM LA_IDX LA_PRJ LA_PRP LA_ROW LA_SC LA_SET LA_SRT | — | Column definition list anchor Column list anchor Command list anchor From list anchor Index list anchor Project list anchor Property list anchor Row list anchor Scalar list anchor Set list anchor Sort list anchor
List element | LE_CD LE_COL LE_CMD LE_FRM LE_IDX LE_PRJ LE_PRP LE_ROW LE_SC LE_SET LE_SRT | — | Column definition list element Column list element Command list element From list element Index list element Project list element Property list element Row list element Scalar list element Set list element Sort list element
Catalog name | CN | — | —
Schema name | SN | — | —
Outall name | ON | — | —
Update operator | U | U D I | Update operator Delete operator Insert operator
Any legal output type | Any | — | —
1 UT, OT, and OUT imply T, but T does not imply UT, OT, and OUT. UT, OT, and OUT are specializations of T. UT and OT do not imply each other. OUT implies UT and OT.

The following table contains a list of all supported DML nodes and their characteristics.

Node | DBVALUEKIND | R | O | Input Types | Output Types
alias | pwszValue | 1 | 1 | 1st: T 2nd: LA_COL | T
allbits | see anybits |  |  |  |
allbits_all | see anybits |  |  |  |
allbits_any | see anybits |  |  |  |
and, or, xor, equivalent | Node weight is stored as DBVALUEKIND_I4. | 2 | N | 1st: B 2nd: B | B
anybits, allbits, anybits_any, allbits_any, anybits_all, allbits_all | Node weight is store as DBVALUEKIND_I4. | 2 | 0 | 1st: S:COL 2nd: S | B
anybits_all | see anybits |  |  |  |
anybits_any | see anybits |  |  |  |
catalog_name | Catalog name as: DBID, pwszValue, pMoniker | 0 | 0 |  | CN
column_list_anchor | DBVALUEKIND_EMPTY | 0 | N | 1st-nth: LE_COL | LA_COL
column_list_element | pwszValue | 0 | 0 |  | LE_COL
column_name | DBID, pwszValue, pMoniker, ulValue | 0 | 0 |  | S:COL
content, content_freetext | DBCONTENT | 1 | 0 | 1st: S:COL | B
content_freetext | see content |  |  |  |
content_proximity | DBCONTENTPROXIMITY | 2 | n | 1st: content or content_freetext 2nd: content or content_freetext nth: Boolean expression formed from and, or, not, content_proximity, and content. | B
content_vector | DBCONTENTVECTOR | 2 | n | 1st: content or content_freetext 2nd: content or content_freetext nth: Boolean expression formed from and, or, not, content_proximity, content, and content_freetext | B
DEFAULT, NULL | DBVALUEKIND_EMPTY | 0 | 0 |  | S:DEF, S:NUL
defined_by_GUID | DBBYGUID | * | * | * defined by implementation | *
equal, not_equal, less, less_equal, greater, greater_equal | Node weight is stored as DBVALUEKIND_I4. | 2 | 0 |  | B
equal_all, not_equal_all, less_all, less_equal_all, greater_all, greater_equal_all, equal_any, not_equal_any, less_any, less_equal_any, greater_any, greater_equal_any | Node weight is stored as DBVALUEKIND_I4. | 2 | 0 | 1st: S or R 2nd: T | B
equal_any | see equal_all |  |  |  |
greater | see equal |  |  |  |
greater_all | see equal_all |  |  |  |
greater_any | see equal_all |  |  |  |
greater_equal | see equal |  |  |  |
greater_equal_all | see equal_all |  |  |  |
greater_equal_any | see equal_all |  |  |  |
is_FALSE | see is_INVALID |  |  |  |
is_INVALID, is_TRUE, is_FALSE | DBVALUEKIND_EMPTY | 1 | 0 | 1st: S | B
is_NOT_NULL | see is_NULL |  |  |  |
is_NULL, is_NOT_NULL | DBVALUEKIND_EMPTY | 0 | 0 |  | B
is_TRUE | see is_INVALID |  |  |  |
less | see equal |  |  |  |
less_all | see equal_all |  |  |  |
less_any | see equal_all |  |  |  |
less_equal | see equal |  |  |  |
less_equal_all | see equal_all |  |  |  |
less_equal_any | see equal_all |  |  |  |
like | DBLIKE | 2 | 0 | 1st: S 2nd: S | B
like_all | see like_any |  |  |  |
like_any, like_all | DBVALUEKIND_EMPTY | 2 | 0 | 1st: S 2nd: T | B
nested_table_name | Table name as: DBID, pwszValue, pMoniker | 0 | 1 | 1st: nested_table_name or table_name | T:H
not | Node weight is stored as DBVALUEKIND_I4. | 1 | 0 | 1st: B | B
not_equal | see equal |  |  |  |
not_equal_all | see equal_all |  |  |  |
not_equal_any | see equal_all |  |  |  |
NULL | see DEFAULT |  |  |  |
or | see and |  |  |  |
outall_name | DBVALUEKIND_EMPTY | 0 | 0 |  | ON
pass_through | DBVALUEKIND_EMPTY | 1 | 0 | 1st: any tree input | Any
prior_command_tree | DBVALUEKIND_EMPTY | 0 | 0 |  | S or T
project | DBVALUEKIND_EMPTY | 2 | 0 | 1st: T 2nd: LA_PRJ | T
project_list_anchor | DBVALUEKIND_EMPTY | 0 | N | 1st-nth: LE_PRJ | LA_PRJ
project_list_element | pwszValue | 1 | 0 | 1st: S, qualifier_name, or ON | LE_PRJ
project_order_preserving | DBVALUEKIND_EMPTY | 2 | 0 | 1st: T or T:O 2nd: LA_PRJ | T or T:O
scalar_constant | any value | 0 | 0 |  | S:CON
select | DBVALUEKIND_EMPTY | 2 | 0 | 1st: T 2nd: B | T
sort | DBVALUEKIND_EMPTY | 2 | 0 | 1st: T. 2nd: LA_SRT | T:O
sort_list_anchor | DBVALUEKIND_EMPTY | 0 | N | 1st-nth: LE_SRT | LA_SRT
table | DBVALUEKIND_EMPTY | 1 | 0 | 1st: LAaROW | T
table_name | Table name as: DBID, pwszValue, pMoniker | 0 | 1 | 1st: SN | T
top | ulValue member contains the count of rows | 1 | 0 | 1st: T:O | T:O


Data Manipulation Operators

The following topics describe the semantics of the data manipulation operators, including their inputs and outputs:

  • Constants, Identifiers, Names, and Parameters
  • Constructors and Coercion Operators
  • Operators on Tables
  • Operators with Two Variants for Ordered and Non-Ordered Tables
  • Operators for Ordered Tables
  • Operators for Hierarchical Tables
  • Comparison Operators
  • Operators for Scalars
  • Content Search Operators
  • Update Operators
  • Aggregate Functions
  • Mixed Operators
  • Special Operators
  • Operators for AddPostProcessing Method
  • Lists of Arguments


Constants, Identifiers, Names, and Parameters

Note that names in the name operators that contain special characters do not need to be quoted (unlike names in SQL statements). If a name in an operator is quoted, these quotes are part of the name.

The following list describes the operators for constants, identifiers, names, and parameters.

DBOP_scalar_constant
Represents a scalar constant whose value can use any element of the value union of the DBCOMMANDTREE structure. A scalar value can be of any OLE DB type. This node has no inputs. The result type is the type of the scalar value represented by the node.
DBOP_DEFAULT, DBOP_NULL
SQL's "DEFAULT" and "NULL" value indicators. There are no inputs. The result type can be any type of scalar.
DBOP_bookmark_name
Represents the bookmark column of a table (for example, SELECT T.*, T.bookmark FROM T). It takes one optional input, a DBOP_table_name, to which the bookmark belongs. A string representing the name of the column can optionally be assigned in the pwszValue member of DBCOMMANDTREE.
DBOP_catalog_name, DBOP_column_name
Represent the name of a catalog and column, respectively. These nodes have no inputs. A name may be specified by a pwszValue member that is not a null pointer, by a DBID structure, or by a moniker in the node's value field. For column names, the column may be denoted as an unsigned integer value (for example, SELECT A, B FROM T ORDER BY 2).
DBOP_schema_name
Represents the name of a schema. A name may be specified by a pwszValue member that is not a null pointer, by a DBID structure, or by a moniker in the node's value field. A schema name node has an optional input DBOP_catalog_name node.
DBOP_outall_name
Specifies that all input columns (for example, SQL's "SELECT *") must be output. This node has no inputs contains contains no other DBCOMMANDTREE value. DBOP_outall_name is used as an input to the DBOP_project_list_element node, but not to the set_list_element, sort_list_element, column_list_element or from_list_element nodes.
DBOP_qualifier_name
Specifies all columns in a table (for example, SQL's "table.*"). This node has no inputs. The table name is represented by a pwszValue member that is not a null pointer. DBOP_qualifier_name is used as an input to the DBOP_project_list_element node, but not to the set_list_element, sort_list_element, column_list_element or from_list_element nodes.
DBOP_qualified_column_name
Represents a column name. It takes two inputs: a DBOP_table_name, and a DBOP_column_name, in that order. It contains no other DBCOMMANDTREE value.
DBOP_table_name
Represents a table name, possibly in another catalog or schema. A table name may be specified by a pwszValue member that is not a null pointer, by a DBID structure, or by a moniker in the value field of the node. This node takes an optional input: DBOP_schema_name.
DBOP_nested_table name
Represents a nested table name. A nested table is a table containing at least one chaptered column. The component of the nested name is stored as a pwszValue member that is not a null pointer, by a DBID structure, or by a moniker in the value field of the node. This node takes a DBOP_nested_table_name or a DBOP_table_name input. For example, the nested table "Customers.Orders" with chapter "Detail" is represented as follows:
        DBOP_nested_table_name (pwsz = "Detail")
            |
    DBOP_nested_table_name (pwsz = "Orders" )
        |
DBOP_table_name (pwsz = "Customers")
DBOP_nested_column_name
Specifies a column in a nested table. This node takes one DBOP_nested_table_name and a DBOP_column_name as inputs, in that order.


Constructors and Coercion Operators

The following list describes the operators for constructors and coercion.

DBOP_row
Constructs a row from a list of scalar values. Similar to SQL-92's row-value constructor from column values or literals, as in "(t.a, t.b, t.c) < VALUES (2, 3, 5)." It takes a scalar_list_anchor as input and produces a single row.
DBOP_table
Constructs a table from a list of union-compatible row constructors. It takes a row_list_anchor as input and produces a table.
DBOP_sort
Sorts a table in increasing or decreasing order according to a list of columns or expressions over its columns. A DBOP_sort has two required child nodes. The first child represents the input table to be sorted. The second child is a DBOP_sort_list_anchor node representing the list of sort keys. Each element of the sort_list, specified by a sort_list_element, contains the order of sort in the DBSORTINFO member, and points to the column name or expression on which to sort. This operator produces an ordered table. If the input to sort is a unique table, it produces an ordered-unique table. If the input to sort is a hierarchical table, the sort operator applies only to the root rowset in that table. That is, the list of columns on which to sort should reference only non-chaptered columns of the root rowset; otherwise, the sort specification is invalid. The output of sort in this case is a hierarchical table with the rows in the root rowset ordered. For example: Let T1->T2->T3 be a hierarchical rowset, where the columns of each rowset are T1(A,B,C,X), T2(D,E,F,Y), and T3(G,H), assume X, and Y represent the chaptered columns of T1 and T2, respectively. Assume DBOP_sort specifies a list W of columns on which to sort. W must reference only subsets of {A,B,C}.
DBOP_distinct, DBOP_distinct_order_preserving
These operators remove duplicate rows from a table. The DBOP_distinct operator takes a table as input and produces a unique table. The DBOP_distinct_order_preserving operator takes an ordered or unordered table as input and produces a unique table maintaining the row order of the input table. If the input table is ordered, then the output is an ordered unique table.


Operators on Tables

The following list describes the operators for tables.

DBOP_alias
The alias facilities for a table. DBOP_alias takes one mandatory input and one optional input. The first is a table-valued subtree, often a table_name operator, representing the table being aliased. The alias name for the table is provided in the pwszValue member of the DBOP_alias DBCOMMANDTREE structure. A second optional input is a column_list_anchor containing column elements representing aliases to be assigned to the columns of the input table. SQL examples: "SELECT a.* FROM table AS a" and "SELECT x, z FROM table AS a (x, y, z)." The output table is of the same table type as the input table. The new name(s) replaces the old name(s) for the output of this operator. If the second input is provided, the size of the column_list must be the same as the number of columns in the first input.
DBOP_cross_join
Represents the Cartesian product of two tables; that is, ANSI-standard CROSS JOIN clause of SQL. This operator takes two tables, T1 and T2, as input and produces a table R. The columns of R are all the columns of T1 and T2. Let t1, t2, and r denote a row in T1, T2, and R, respectively. Let r[Ti] denote the projection of row r on the columns of Ti, i=1,2. Each row r in R is formed by taking each row t1 in T1 and concatenating it with each row t2 in T2, so that r[T1]=t1 and r[T2]=t2. The cardinality of R is the product of the cardinalities of T1 and T2. R is a unique table if both T1 and T2 are unique tables; otherwise, it is a table.
DBOP_union_join
Represents the UNION join of SQL. This operator takes two tables T1 and T2 as input and produces a table R. The columns of R are all the columns of T1 and T2. Let ti_null denote a row of Ti, i=1,2, containing NULL values in every column. Each row r in R is formed by taking every row from T1 and T2 as follows: (a) r[T1]= t in T1 and r[T2] = t2_null, or (b) r[T1] = t1_null, and r[T2] = t in T2. The cardinality of R is the sum of the cardinalities of T1 and T2.

The output is a unique table if both inputs are unique tables; otherwise, it is a table.

DBOP_inner_join, DBOP_left_semi_join, DBOP_right_semi_join, DBOP_left_anti_semi_join, DBOP_right_anti_semi_join, DBOP_left_outer_join, DBOP_right_outer_join, DBOP_full_outer_join
All join operators take two required table inputs, T1 and T2, and produce a table R as output. A third required input is a Boolean-valued expression specifying the join condition (that is, the ON or WHERE clause of SQL). The columns of R are specified as follows:
  • For inner_join and all outer_joins, the columns of R are all the columns of T1 and T2, in that order;
  • For left_semi_join and left_anti_semi_join, the columns of R are the columns of T1; and
  • For right_semi_join and right_anti_semi_join, the columns of R are the columns of T2.

The rows in R are specified as follows:

  • For inner_join, R contains the subset of rows from the Cartesian product of T1 and T2. The subset satisfies the join condition. If the join condition is the predicate TRUE or a tautology (for example, 5 = 5), then R is exactly the Cartesian product of T1 and T2.
  • For left_semi_join, R contains all rows of T1 that have a matching row in T2 satisfying the join condition. If the join condition is always TRUE, then R contains the same rows as T1. If the join condition is always FALSE, then R is empty.
  • For left_anti_semi_join, R contains all rows of T1 that do not have a matching row in T2 satisfying the join condition. If the join condition is always TRUE, then R is empty. If the join condition is always FALSE, then R contains the same rows as T1.
  • For right_semi_join, R contains all rows in T2 that have a matching row in T1 satisfying the join condition. If the join condition is always TRUE, then R contains the same rows as T2. If the join condition is always FALSE, then R is empty.
  • For right_anti_semi_join, R contains all rows in T2 that do not have a matching row in T1 satisfying the join condition. If the join condition is always TRUE, then R is empty. If the join condition is always FALSE, then R contains the same rows as T2.
  • For left_outer_join, R contains all tuple data objects in the inner_join of T1 and T2, and all tuples in the left_anti_semi_join of T1 and T2 concatenated with t2_null;
  • For right_outer_join, R contains all tuples in the inner_join of T1 and T2, and all tuples in the right_anti_semi_join of T1 and T2 concatenated with t1_null.
  • For full_outer_join, R contains all tuples in the inner_join of T1 and T2, all tuples in the left_anti_semi_join of T1 and T2 concatenated with t2_null, and all tuples in the right_anti_semi_join of T1 and T2 concatenated with t1_null.

In general, the output R is a table; it is a unique table in the three following cases:

  • For inner_join and all outer joins, if both inputs are unique tables.
  • For left_semi_join and left_anti_semi_join, if the left input is a unique table.
  • For right_semi_join and right_anti_semi_join, if the right input is a unique table.
DBOP_natural_join, DBOP_natural_left_outer_join, DBOP_natural_right_outer_join, DBOP_natural_full_outer_join
All natural join operators take two required table inputs, T1 and T2, and produce a table R as output. A third optional input is a column_list node type that specifies the columns on which to test the join predicate (such as the USING clause of SQL). Natural joins are different from the join operations described above in that they have an implicit projection and an implicit join condition. Let CC represent the columns that are common to both T1 and T2, T1C represent the columns of T1 not in CC, and T2C represent the columns of T2 not in CC. The columns of R are T1C, CC, and T2C. Producing the set of columns CC only once in R represents the implied projection. The implied join condition is the conjunction of terms T1.Ci = T2.Ci, for every Ci in CC. If the column_list input of these operators is included, then the join condition is restricted to the terms involving only the columns in the column list, which can only reference columns in CC. Other than the implied projection and join condition, the semantics of the natural join operators are exactly the same as their non-natural counterparts. That is, the cardinality of R is the cardinality of the non-natural join operators. If CC is the empty set, then the implied join predicate is TRUE and R contains the cross join of T1 and T2.
DBOP_set_intersection, DBOP_set_union, DBOP_set_left_difference, DBOP_set_right_difference, DBOP_set_anti_difference
Set operations, requiring "union compatible" input tables. These operators take two required inputs, T1 and T2, and produce a result table R. Let A1, A2,..., An denote the columns of T1, and B1, B2,..., Bm denote the columns of T2. T1 and T2 are union compatible if: n = m, and the types of Ai and Bi, I = 1,..,n, are compatible. The rules determining when the types of two columns are compatible and what the type of the resulting columns will be are provider-specific. If Ai, Bi, have the same name, that name is propagated to the output; otherwise, the resulting name is provider-specific. Left-difference is the usual difference operator; right-difference is the opposite (T1 right-difference T2 == T2 left-difference T1). The anti-difference is the union of the left- and right-differences. For SQL's "union corresponding," the tree node requires a third optional input, which must be a non-empty column_list_anchor. If the third input is present, the input tables are projected on the columns named in that list before the set operation proceeds. If the third input is not included and the Boolean fValue member DBCOMMANDTREE node is set to TRUE, then the command processor decides the maximal set of columns from the two inputs that are union-compatible (and should therefore be preserved). The output is a unique table.
DBOP_bag_intersection, DBOP_bag_union, DBOP_bag_left_difference, DBOP_bag_right_difference, DBOP_bag_anti_difference
Multi-set (bag) operations, requiring "union-compatible" input tables. The number of occurrences of a row in the output table is the minimum (intersection), sum (union), or difference, respectively, of the number of occurrences of that row in the two input tables. Variants are the same as those for set operations. DBOP_bag_union represents SQL's UNION ALL operator. These operations require two or more table inputs; the output is a table.

Given table A with two occurrences of row X and table B with one occurrence of row X, then:

  • (A bag_intersection B) will contain one (min(2,1)) occurrence of row X;
  • (A bag_union B) will contain three (2+1) occurrences of row X;
  • (A bag_left_difference B) will contain one (2-1) occurrence of row X;
  • (A bag_right_difference B) will contain zero occurrences of row X, since 1-2 is a negative number.
  • (A bag_anti_difference B) will contain one (1+0) occurrence of row X corresponding to the bag_union of the bag_left_difference and bag_right_difference.
DBOP_division
Represents the relational division operator. This operator takes two required table inputs, T1 and T2, and produces a unique table R as result. The first input, T1, is the dividend table; the second input, T2, is the divisor table. The set of columns of T2 must be a subset of the columns of T1. Let CC be the columns that are common to T1 and T2, and T1C be the columns in T1 not in T2. Table R has all the columns in T1C. Let t1 denote a row in T1 and t2 a row in T2. The result R contains the set of rows r such that for every row t1 in T1, there is a row t2 in T2 with r = t1[T1C] and t1[T2] = t2.
DBOP_relative_sampling
A random sampling of rows from a table based on a reduction factor (given as a percentage, which must be an integer between 0 and 100). Randomness is guaranteed only to the ability of the provider to generate random numbers. The only required input is a table. The percentage between 0 and 100 is represented as an integer in the ulValue member of the DBCOMMANDTREE node. If the input table is unique, so is the output table; otherwise, the output is a table.
DBOP_absolute_sampling
A random sampling of rows from a table with a known, fixed output cardinality. The output cardinality is given as a positive integer stored in the ulValue member of the DBCOMMANDTREE node (values larger than the input cardinality raise an error). Randomness is guaranteed only to the ability of the provider to generate random numbers. The only required input is a table. If the input table is unique, so is the output table; otherwise, the output is a table.
DBOP_transitive_closure
This operator performs recursive computations that involve traversal of all paths in a directed graph, starting from a set of initial nodes as defined by Agrawal [Institute of Electrical and Electronics Engineers (IEEE) Transactions on Software Engineering, Volume 14, Number 7, 1988]. Suppose the input table T is of the form T(K1, K2, P1, P2, ..., Pm), where K1 and K2 are columns belonging to the same domain. K1 and K2 can consist of more than one, but an equal number of, columns. T can be represented as a directed graph in which each row t in T is represented as a link (arc) from node t[K1] to node t[K2]. The values t[Pi], i = 1,..., m, represent link properties. Semantically, the transitive_closure operator computes a table representing all paths in that graph as the following iterative program.
let R = T;
do
  let R = select * from T
          union
          select R.K1, T.K2 from R inner join T on R.K2 = T.K1;
while "R changes";

The operator takes four mandatory inputs. The first is a table T representing directed links in a graph. The second is a join predicate to determine when a link and a path can be concatenated (for example, R.K2 = T.K1). The third is a project_list input representing the columns to be preserved after such a concatenation; each column may be the result of a scalar computation (including aggregate functions). In the preceding sample code, it is represented by R.K1, T.K2, but it may also include Pi columns from R and T. The fourth input is a predicate to select result tuples based on their derivation history (see the following table). A fifth optional input represents a selection condition on the initial table. The derivation path that led to the existence of a row in the transitive_closure of T is captured in an additional chaptered column called Delta that gets implicitly attached to each result row. Thus, the operator's output is a hierarchical table R, having the same columns as T, plus the chaptered column.

DBOP_recursive_union
As required by SQL-3 (but not SQL-92), the recursive union starts with an input table and adds to that table (in the result, not in the stored database) rows that can be computed by a predicate from rows already in the table. When viewed as a computation on graphs, this operation starts with a set of nodes and adds nodes that may be reached by one or more steps in the graph. The starting points are specified in the input table, and the steps are specified by the predicate. Alternatively, the starting table's rows can represent a set of arcs in a graph, and the predicate can express how links connect and can be combined into new links (paths).
DBOP_aggregate
Combines grouping of rows from an input table T into equivalence classes, and aggregate function computation within each group to produce a table R. The operator first builds equivalence classes based on equal values in a set of (grouping) expressions (handling NULLs as required in SQL). It then collapses each equivalence class into a single row by computing an aggregate function on the rows in the class. The operator takes three required inputs. The first is a table. The second is a list of grouping expressions represented by a project_list_anchor input (as for the "project" operator). The grouping expressions form the unique key for the output table. If the list of grouping expressions is empty, all of the input is presumed to be a single equivalence class and the output is a table with a single row. The list of grouping expressions may include all columns of the input table. The third input is composed of aggregation expressions that are passed as a second project_list_anchor (similar to "project" operator), with the requirement that references to input columns other than those in the grouping list must be nested inside aggregate functions (for example, "sum"). Note that both lists are "project" lists, thus permitting arithmetic and assignment of new column names (expressions in the grouping list require a name). The new name(s) replaces the old name(s) for the output of this operator. The table R contains all the columns mentioned in the two project lists. The output is a unique table.


Operators with Two Variants for Ordered and Non-Ordered Tables

The following list describes the operators with two variants for ordered and non-ordered tables.

DBOP_select, DBOP_order_preserving_select
Subset of rows based on a predicate. The required inputs are one table and one Boolean expression. If the input table is unique, so is the output table. For the "order-preserving-select" operator, if the input is an ordered table, so is the output.
DBOP_project, DBOP_project_order_preserving
Preserve a subset of columns, possibly with some arithmetic computation within each single row. No duplicate elimination of rows is implied. The two required inputs are a table and a project_list_anchor input; the output is a table. For the "order-preserving-project" operator, if the input is an ordered table, so is the output. If the provider permits, some of the ordering columns may be removed by the projection operator, such that the ordering is not restorable if it were to be lost in a subsequent operation. Only unqualified names are available above a projection level; use an intervening alias node to avoid ambiguous references.


Operators for Ordered Tables

The following list describes the operators for ordered tables.

DBOP_top, DBOP_top_percent, DBOP_top_plus_ties, DBOP_top_percent_plus_ties
Take the first rows from an ordered table. These operators are different from the sampling operators because they prohibit randomness. The "top" operations require a fixed count of rows. The "top_percent" operations require a fraction of the input rows (not an approximation). The "plus-ties" operators include all rows that are equal (with respect to the sort order of the input table) to the last one that is explicitly requested. The first required input for all operators is an ordered table. The top and top_plus_ties operators store the count of rows as a positive integer in the ulValue member of the command node. The "top_percent*" operators take a second required scalar_list_anchor input. The elements of this list contain two scalar_constant members that represent a pair of positive integers expressing a fraction between 0 and 1. The output is an ordered table.
DBOP_rank, DBOP_rank_ties_equally, DBOP_rank_ties_equally_and_skip
Add a new column "rank" to the table, counting from 1 to the table's cardinality. If the column name "rank" already exists, add "rank2" ("rank3" etc.) instead. The "ties" operations assign the same rank to items that are equal (with respect to the sort order of the input table). The "and skip" variant skips an appropriate number of values in the counting sequence. An example without skipping would be 1, 2, 2, 2, 3, 4, 4, 5; an example with skipping would be 1, 2, 2, 2, 5, 6, 6, 8. The input is an ordered table. If the operator is "rank," the output is an ordered unique table; for the "ties" operators, it is an ordered table.


Operators for Hierarchical Tables

The following list describes the operators for hierarchical tables.

DBOP_navigate
Given two tables, one or both of which may be hierarchical tables, this operator computes their join. However, instead of creating large rows with columns from both join inputs, it attaches to each row of the first table all matching rows from the second table, thus creating a hierarchy of rowsets. It also adds expression-valued columns to both the new parent rowset and the new child rowset.

This operator has six inputs:

  • Two table-valued subtrees representing the input to the operator.
  • A join predicate to make the connection.
  • A list element with a name for the new column representing the nested column. The alias name for child levels is mandatory and must be unique across the hierarchy.
  • A list specifying expression-valued columns to be added to the parent level (such as sub-totals).
  • A list adding expression-valued columns to the child level (such as running sums).
DBOP_nesting
Given a flat table, this operator creates a hierarchical table. First, it classifies the table's rows, as in a grouping operation. For each resulting group, it produces a single output row to become part of the parent table. This output row contains columns defined in the parent list, plus one nested column. The nested column represents a subtable, which contains columns defined in the child list. The grouping list is a project list; that is, it includes a column name for each element. The parent list is also a project list; its values are computed from the grouping list and aggregates over the input (same grouping). The child list is also a project list, whose values are computed from the input columns. In addition to these three lists, the inputs include an input table and a name for the column representing the subtable.

Given a hierarchical table, this operator creates an additional hierarchical column. Note that a subtable which already exists in the input may become part of the new top or lower levels. In the former case, set equality is required for two input rows to become members of the same group. In the latter case, multilevel nesting is created.

If the input to nesting is an ordered table, it does not affect the behavior of nesting. DBOP_nesting will produce what is specified by the semantics of nesting, regardless of the order of the input. An optimizer might take the ordering into consideration when defining the execution strategy for DBOP_nesting to reduce the cost of the grouping, but to the data consumer it does not make any difference.

The inputs to this operator are a flat or hierarchical input table, a column name for the nested column (sub-rowset) to be created, and the grouping, parent, and child lists. (The alias name for child levels is mandatory and must be unique across the hierarchy.)

The order of the parent and child tables produced as output of DBOP_nesting is undefined. This gives providers more flexibility during implementation (for example, the grouping can be done by hashing, and the computation of the chapters can be based on traversing an index or computing a parameterized query).

NULLs are handled during the grouping as in SQL "GROUP BY" clauses.

DBOP_unnesting
Given a hierarchical table, this operator flattens one nested column by repeating the top-level row as many times as there are values in the nested column (rows in the sub-rowset)

The inputs are a hierarchical table and the column to be flattened.

DBOP_nested_apply
Given a hierarchical table, this operator applies any table operation to a nested column and replaces the nested column with the resulting value (in the query result, not in the underlying database), or adds the query result as a new column. If multiple levels of nesting exist, the operation to be applied may "nested apply" itself. The "nesting" and "unnesting" operations are also permitted, as well as operations that result in a scalar, such as "aggregate" and "exists".

The inputs are a hierarchical table and a table operation, a column to which the table operation is to be applied, and (optionally) a column name for a new column. The output is a table, which may or may not be nested, depending on the input table and the result type of the table operation applied.

DBOP_cross_tab
This node takes as an input a command tree that specifies a hierarchy of rowset chapters. It outputs an augmented result containing additional rowsets that generate "column membership" and "column aggregates" that are useful for cross-tabulation reports.

To specify the crosstab, an alias is given to name the top level of the input hierarchy. Also, two lists of aliases are given: RowHierarchy and ColumnHierarchy. The RowHierarchy followed by the ColumnHierarchy must indicate a continuous descending path. The first element of the RowHierarchy is required to be the top level of the input hierarchy.

The crosstab node augments the input hierarchy such that each level of the RowHierarchy input contains a nested rowset that is an instance of ColumnHierarchy. The augmented hierarchy is then nested inside a "top" rowset. This rowset also contains a nested rowset corresponding to ColumnHierarchy and a list of aggregate values that are computed over the entire input tree. Aggregates are specified using a "project_list" structure and follow the same binding rules as specified by the nesting node.

Fields of a given instance of a level of the ColumnHierarchy input are defined as follows:

  • Aggregates (such as Sum, Avg, Min, and Max) are computed over the set of records matching the criteria imposed by the exact drill-down path. For example, drilling down from the "top" rowset will show aggregates that are computed over all the levels of the RowHierarchy input.
  • Upward references resolve correctly when possible. If the reference doesn't exist on the path that was taken from the "top" rowset to this instance of a level of the RowHierarchy, then E_OUTOFSCOPE is returned for the evaluation of that field.
  • Nested rowsets other than those specified in ColumnHierarchy return E_UNAVAILABLE, unless the path that was taken from the "top" rowset includes the last level of RowHierarchy.

The exact list of parameters for this node are: a command tree, an alias for the input, a list of aliases for RowHierarchy, a list of aliases for ColumnHierarchy, and an optional project_list of aggregates.


Comparison Operators

The following list describes the comparison operators.

DBOP_is_NULL, DBOP_is_NOT_NULL
Comparison to NULL value. Both operators are needed, since "NOT is_NULL" and "is_NOT_NULL" differ in SQL if the operand is a row with some (but not all) NULL values. These operators take one scalar input and produce a Boolean result.
DBOP_equal, DBOP_not_equal, DBOP_less, DBOP_less_equal, DBOP_greater, DBOP_greater_equal, DBOP_equal_all, DBOP_not_equal_all, DBOP_less_all, DBOP_less_equal_all, DBOP_greater_all, DBOP_greater_equal_all, DBOP_equal_any, DBOP_not_equal_any, DBOP_less_any, DBOP_less_equal_any, DBOP_greater_any, DBOP_greater_equal_any
Comparison operators with semantics as in SQL. For the normal comparison operators, the two input rows must both be scalars or both be rows. Otherwise, the scalar is converted into a one-column row as necessary. The "_all" and "_any" operators require a scalar left input and a table-valued right input, where a column value in a chaptered column is a special case of a table. These operators produce Boolean output.

Row-valued comparison refers to the comparison between two row instances. Multivalued comparison refers to the comparison between a row instance and a table (such as "_all" and "_any" operators). The rules for row-valued comparisons are based on ANSI SQL semantics. The rules for multivalued comparisons are an extension of the rule-valued comparisons.

The weight of this node is stored as a DBVALUEKIND_I4 in an lValue member of the DBCOMMANDTREE structure.

DBOP_anybits, DBOP_allbits, DBOP_anybits_any, DBOP_allbits_any, DBOP_anybits_all, DBOP_allbits_all
Comparison operators that have the same syntax as other comparison operators. These operators take two inputs, with the first being a column and the second being a scalar value to compare with the column. The specific semantics of these nodes are as follows: DBOP_any_bits is true if the result of a bitwise AND operation performed on the column value and the constant is non-zero. DBOP_all_bits is true if the result of a bitwise AND operation performed on a column value and the constant equals the constant. As with other comparison operators, there are also "_any" and "_all" versions of these nodes.

The weight of this node is stored as a DBVALUEKIND_I4 in the lValue member of the DBCOMMANDTREE structure.

DBOP_between, DBOP_between_unordered
SQL comparison operations. "Between_unordered" first sorts the bounding values; "a between_unordered b and c" is equivalent to "a >= min (b, c) and a <= max (b, c)", whereas "a between b and c" is equivalent to "a >= b and a <= c." All variants of "between" are inclusive, meaning that a value equal to one of the end points is acceptable. There is no exclusive "between" variant. These operations require three scalar inputs (which may be rows), and produce a Boolean result.
DBOP_match, DBOP_match_unique, DBOP_match_partial, DBOP_match_partial_unique, DBOP_match_full, DBOP_match_full_unique
SQL's match predicate. These operation require two scalar inputs (which may be rows), and produce a Boolean output.
DBOP_and, DBOP_or, DBOP_xor, DBOP_equivalent
These Boolean operators represent the logical AND, OR, exclusive OR, and equivalence operators. They take two or more Boolean inputs (except DBOP_equivalent, which takes exactly two), and produce a Boolean result. The weight of this node is stored as DBVALUEKIND_I4 in the value.lValue member.
DBOP_not
This operator requires one Boolean input and produces one Boolean result. The weight of this node is stored as DBVALUEKIND_I4 in the value.lValue member.
DBOP_implies
This operator represents Boolean implication. It takes two mandatory Boolean inputs and produces a Boolean output according to the following table:
Input1 | Input2 | Result
False | False | True
False | True | True
True | False | False
True | True | True


Operators for Scalars

The following list describes the operators for scalars.

DBOP_scalar_parameter
Scalar parameter, named by a string. The name must be unique within all parameters for the command, including the parameters of SQL commands in textual nodes in the same command tree. This operator does not take any input and produces scalar output.
DBOP_scalar_function
A scalar function identified by name, globally unique identifier (GUID), etc., similar to a column name. The number of arguments (inputs) depends on the function; it produces scalar output.
DBOP_plus, DBOP_minus, DBOP_times, DBOP_over, DBOP_div, DBOP_modulo, DBOP_power
Standard arithmetic. "div" always returns an integer result, such that "(a div b) times b plus a modulo b == a" for all nonzero values for b. These operators require two scalar inputs and produce a scalar result.
DBOP_like, DBOP_sounds_like
Regular expression matching. These operators require two string inputs. For DBOP_like, the operator node includes a globally unique identifier (GUID) for the language or system whose regular expression syntax is to be used. Fixed GUIDs are assigned for SQL, MS-DOS®, and Messaging Application Programming Interface (MAPI). Boolean result. The DBOP_like node uses the DBLIKE structure to hold the GUID and a weight.
DBOP_like_any, DBOP_like_all
Regular expression matching. These operators take a scalar first input and a table-valued second input and produce a Boolean output.
DBOP_is_INVALID, DBOP_is_TRUE, DBOP_is_FALSE
SQL's tests on predicates. These operators take one scalar input and produce a Boolean result.
DBOP_overlaps, DBOP_case_condition, DBOP_case_value, DBOP_nullif, DBOP_cast, DBOP_coalesce, DBOP_position, DBOP_extract, DBOP_char_length, DBOP_octet_length, DBOP_bit_length, DBOP_substring, DBOP_upper, DBOP_lower, DBOP_trim, DBOP_translate, DBOP_convert, DBOP_string_concat, DBOP_current_date, DBOP_current_time, DBOP_current_timestamp


Content Search Operators

The following operators describe search operations on columns containing text. These operators generally behave like any other Boolean operators. When used in conjunction with the DBOP_content_select operator, however, the resulting tables include two special columns describing the hit count and rank.

DBOP_content_select
This operator is similar to the DBOP_select operator. It takes a table T and Boolean expression (selection condition) as input, and produces a table R as output. The rows in R are those rows that satisfy the selection condition. However, the columns of R include all the columns of T plus three additional columns representing the hit count, a rank, and a rank vector (which together represent the quality of the match).
DBOP_content, DBOP_content_freetext
These operators are used to express content searches for words or phrases found in a column. They take one required input: a column name specifying the column in which to search. They have two special column identifiers. The first, PROPID_STG_CONTENTS, means "look in the object contents" for data providers that have rows that actually are objects. The second, PROPID_ QUERY_ALL, means "look in all columns."

The text search pattern is stored in the DBCONTENT structure within the node. DBOP_content_freetext differs from DBOP_content in that it instructs the query engine to use all of its text-processing tricks in evaluating the restriction. The DBOP_content node may specify a method to generate words matching a pattern (this field is ignored for DBOP_content_freetext), which determines the manner in which the initial query term is expanded before searching text. GENERATE_METHOD_EXACT matches only the word or phrase specified in the content node. GENERATE_METHOD_PREFIX matches all words that begin with the text specified in the node. GENERATE_METHOD_INFLECT causes linguistic inflection of the specified word. The English word "run", for example, may expand to "run", "running", "ran", "runs", and so forth. Providers may support other generation methods (for example, GENERATE_METHOD_MISSPELLING or GENERATE_METHOD_REGEX). The generation methods specified in this node are mutually exclusive. Not all of the levels specified above are available for each language. If GENERATE_METHOD_PREFIX or GENERATE_METHOD_INFLECT is used with a phrase (multiple words), the expansion applies to each word separately. The exact method of splitting a phrase into words is implementation-specific. These nodes also have a weight field, which may be used by a sophisticated data consumer to give more or less weight in hit-ranking to matches on this particular content restriction. The output of these operators is Boolean. The arguments internal to this node are specified using the DBCONTENT structure.

PSGUID_QUERY is the GUID for the property set for special content columns. The following are some of the interesting columns in this set:

#define PROPID_QUERY_RANKVECTOR (0x2) // column used to return rank
                                      // values of the
                                      // content_vector_or operator

#define PROPID_QUERY_RANK (0x3) // column used to return the final
                                // rank of each row

#define PROPID_QUERY_HITCOUNT (0x4) // column used to return the
                                    // number of content hits found
                                    // in a row

#define PROPID_QUERY_ALL    (0x6) // search in all text associated
                                  // with a row

#define PROPID_STG_CONTENTS (0x13) // search inside the contents on
                                   // an object
DBOP_content_proximity
Proximity nodes are used to rank hits within queries that search for several different pieces of text. The rank of an object matched by a proximity node increases as the words and phrases move closer together. The formula used to compute rank is specific to a given implementation. Generally a proximity node should be used as an n-ary AND node among multiple content restrictions. The internal arguments of this node are a proximity unit (DWORD), a proximity distance (ULONG), and a weight on the node (LONG), all specified with the DBCONTENTPROXIMITY structure.

The proximity units specified by the proximity unit constants are supported.

The node takes two or more input subtrees, each of which should contain DBOP_content, DBOP_content_freetext, DBOP_content_proximity, DBOP_and, DBOP_or, or DBOP_not nodes. The output of the node is Boolean. It is logically similar to a bitwise AND operator in that all input subtrees must evaluate to TRUE to produce a true value.

DBOP_content_scope
[ TBD ]
DBOP_content_table
[ TBD ]
DBOP_content_vector_or
Used to support advanced content-retrieval models. This node acts as an n-ary OR node, with two main differences. First, when a vector node is used the programmer has the option of retrieving a rank vector for each object, as a special, well-known column. This vector contains the rank of each child node in the vector. Second, the formula used to compute the overall rank of the vector may be specified. The ranking methods specified by the vector rank constants are supported.

There may be at most one vector node in the tree. The internal arguments of this node are a ranking method (DWORD) and a weight on the node (LONG), specified within the DBCONTENTVECTOR structure.

There are two or more children, of exactly the same type as DBOP_content_proximity above. This operator produces Boolean output. It acts as an n-aryOR operation of the input subtrees.


Update Operators

The following list describes the update operators.

DBOP_delete
Removes rows from a table. This operator takes two inputs — one required and one optional The required input is a DBOP_table_name node describing the table being updated. The optional input is a table-valued expression representing the rows to be deleted. If the optional input is not provided, all rows of the table specified in the first required input are deleted. The requirement as to whether the input table being updated must be a base table is provider specific.
DBOP_update
Modifies the values of one or more columns in rows, from a table, that satisfy a condition. This operator takes two required inputs. The first is a table-valued expression describing the set of rows being updated. The second is a DBOP_set_list_anchor node containing the update expressions (for example, SET A = A + 1, B = B - 5). The column names represented in the DBOP_set_list_elements must be unambiguous. That is, in cases where the tuples to be updated are defined by a join expression over multiple tables, and a column being updated appears in more than one table, the reference to the updated column must be fully qualified (DBOP_qualified_column_name). For example, the update statement
UPDATE A INNER JOIN B ON A.F1=B.F1 SET A.X = 1, B.Y = 2 WHERE A.Z =10

is represented by an update node whose first input is a subtree representing the expression

A INNER JOIN B ON A.F1=B.F1 AND A.Z = 10

and the second input is a DBOP_set_list_anchor containing two list elements for A.X = 1, and B.Y = 2. The requirement as to whether the input table being updated must be a base table is provider specific.

DBOP_insert
Adds rows to a table. This operator specifies three arguments: one required row_constructor or table_constructor, one required table, and one required column_list. The number of elements of column_list must match the number of values in the constructed row(s). Columns not listed in the column_list must have default values or be capable of containing NULL values. Requirements as to whether table input must be a base table are provider specific.


Aggregate Functions

The following list describes the operators for aggregate functions.

DBOP_min, DBOP_max, DBOP_count, DBOP_sum, DBOP_avg, DBOP_any_sample, DBOP_stddev, DBOP_stddev_pop, DBOP_var, DBOP_var_pop, DBOP_first, DBOP_last
These are aggregate functions, to be used in the aggregation operation, including standard deviation and variance for samples (using division by "N - 1") and complete populations (division by "N"). All operators (except _count) take one mandatory input representing a column_name on which the function is computed. A count node with no inputs indicates SQL's COUNT(*). The DISTINCT and ALL SQL set quantifiers; for example, SELECT SUM (DISTINCT X) FROM T, SELECT SUM (ALL X) FROM T) are indicated by setting the appropriate bits of the dwSetQuantifier member of the DBSETFUNC structure using the aggregate function constants. The node produces a scalar output.


Mixed Operators

The following list describes the mixed operators.

DBOP_in
Membership test of a scalar or row in a table. Inputs for this operator are a row and a table; it produces a Boolean result as output.
DBOP_exists, DBOP_unique
These operators take a table T as input and produce a Boolean result as output. DBOP_exists evaluates to TRUE if the cardinality of T is greater than zero; otherwise it evaluates to FALSE. DBOP_unique detects duplicate rows in T. If any two rows in T are equal to one another, DBOP_unique evaluates to FALSE; otherwise, it evaluates to TRUE.
DBOP_subset, DBOP_proper_subset, DBOP_superset, DBOP_proper_superset, DBOP_disjoint,
These operators take two tables T1 and T2 as input and determine whether T1 is a subset, proper_subset, superset, proper_superset, or disjoint set of T2. The output is Boolean.


Special Operators

The following list describes the special operators.

DBOP_pass_through
This operator passes the entire subtree to a provider. All operations on the subtree are to be delegated to the provider, including parts of global tree operations, such as validation, and can therefore be unexpectedly expensive. The command tree must be self-contained. The provider is identified with a string or a globally unique identifier (GUID). This operator takes one input tree with any result type; output type is the same as input type.
DBOP_defined_by_GUID
This operator is a major means of extensibility: It is an operator not included explicitly in this enumerated type, and is known to both consumer and provider by its GUID. Consumer and provider must also agree on the count, type, and so forth, for the operator. The cost of leaving the set of possible operators mostly undefined is that type checking is left entirely to the provider implementation. Additional node information may be provided in the DBBYGUID structure inside the node. The information stored in the pbInfo member is provider-specific.
DBOP_text_command
A command in a textual command language, typically a SQL expression. The language and its dialect are indicated in the guidDialect member of the DBTEXT structure stored in the value field in the node structure. Fixed values are defined for SQL-92, SQL-92-intermediate, SQL-92-entry, T-SQL, and Access SQL. In SQL, possible subtrees in the OLE DB command tree are references with strings "::1", "::2", and so on. The textual command is stored in the pwszText member of the DBTEXT structure. This operator produces scalar- or table-valued output. It is used by OLE DB consumers to communicate complete or partial SQL statements. If the operator has no inputs, then the text stored in pwszText should contain a complete SQL statement. If the operator has an input, then the DBOP_text_command contains a partial SQL statement and its input is the operator to which the partial statement corresponds. For example, if an OLE DB consumer wants to communicate only the FROM clause of a SQL statement to another consumer, the partial text will contain a string such as "FROM T1, T2" and the input to the operator will be a DBOP_from_list_anchor.
DBOP_SQL_select
The equivalent of a SQL SELECT statement, with its component clauses SELECT, FROM, WHERE, GROUP BY, HAVING, and ORDER BY, in that sequence. The SELECT and GROUP-BY clauses are represented by project lists. The FROM clause input, represented by a from_list_anchor, contains from_list_elements that take a table-valued expression as input. The table-valued expression may refer to a base table, a subquery, or a table-valued result generated by an OLE DB query processor. The WHERE and HAVING clauses are each represented by a Boolean expression. The ORDER BY clause is represented by a sort list. All clauses must be present in the node, but they may be empty. An empty list is denoted by an *_anchor node with no *_element nodes attached to it. SQL scope (visibility) rules apply. The SQL DISTINCT option is specified by setting the fValue member of the SQL_select node as TRUE. The output is a table. If an ORDER BY clause is given and DISTINCT is not specified, then the output is an ordered table. If DISTINCT is specified and no ORDER BY clause is specified, then the output is a unique table. If both DISTINCT and an ORDER BY clause are specified, then the output is an ordered-unique table.
DBOP_remote_table
Refers directly to a table in an external data source without creating a synonym for it beforehand. Its children are identical to that of the DBOP_create_synonym node and the external data source is identified in the same way.


Operators for AddPostProcessing Method

The following list describes the operators for the IQuery::AddPostProcessing method.

DBOP_prior_command_tree
Used when adding post-processing operations. This operator occurs in the post-processing tree but never in a complete command tree. It has either no inputs, or no table- or scalar-valued expressions, depending on the previous command tree.
DBOP_add_columns
Used when adding post-processing operations, this operation is the only operation that can add columns "projected away" by earlier operations, such as columns from tables that already participate in the query. The inputs are a table and a projection list; output is a table.


Lists of Arguments

The following list describes operators with lists of arguments. An empty list is denoted by the corresponding anchor node with no element nodes.

DBOP_column_list_anchor, DBOP_column_list_element
These operators are used to define a list of column aliases (see DBOP_alias). Each element represents the name alias as a string value in the pwszValue field of the command node. Elements take no inputs.
DBOP_command_list_anchor, DBOP_command_list_element
These operators are used to define a sequence of OLE DB commands. Each element takes one command tree input representing either a data manipulation language (DML) or data definition language (DDL) command.
DBOP_from_list_anchor, DBOP_from_list_element
The list of tables in a SQL FROM clause. Each element requires a table-valued expression as input, which can be represented by a table_name or alias to serve as a SQL "correlation name."
DBOP_project_list_anchor, DBOP_project_list_element
The anchor and an element in a list of columns for a projection. The anchor has an element as its first child, but no other information. Each element assigns a column name, which is stored in the string portion of the tree node, to a scalar expression, which is given as the element node's input tree. In addition, outall_name and qualifier_name must be in the project_list of a project node (as opposed to a project_list of an aggregate node). If a project list includes the member outall_name and a column_name that is a member of the columns implied by outall_name, then that column will appear twice in the result.
DBOP_row_list_anchor, DBOP_row_list_element
The anchor and element in a list of rows for constructing a table. Each element has one DBOP_row input. At least one row_list_element must be in each list.
DBOP_scalar_list_anchor, DBOP_scalar_list_element
The anchor and element in a list of scalar constants for constructing a row. Each element takes one DBOP_scalar_constant as input. At least one scalar list element must be in each list.
DBOP_set_list_anchor, DBOP_set_list_element
The anchor and element in a list of columns for updating. Each element has two inputs, one a column name and one an expression of the same type as the column. At least one set_list_element must be in each list.
DBOP_sort_list_anchor, DBOP_sort_list_element
The anchor and an element in a list of columns for sorting. This list is different from a projection list in that no new column name is assigned but an ascending or descending flag and an optional locale ID are indicated. Each element includes a scalar input expression.


Error Messages

Several errors can occur when submitting queries to the SQL parser. When these errors occur, the OLE DB Provider returns a DB_E_ERRORSINCOMMAND error (see ICommand::Execute). It can usually also return a string describing the error. These errors are usually syntax related.

The following error messages are not defined in a public header and the error codes associated with them are not exposed. They are also localized. Parameters shown in italics are specific to each query that is in error.

  • Parser Error
  • Illegal PASSTHROUGH query: Query_Expression
  • Incorrect syntax near Query_Token. SQLSTATE=42000
  • Incorrect syntax near Query_Token. Expected Token. SQLSTATE=42000
  • Multiple statement commands are not supported. SQLSTATE=42000
  • ORDER BY ordinal number must be between 1 and Ordinal_Number. SQLSTATE=42000
  • View View_Name has not been defined in catalog Catalog_Name. SQLSTATE=42S02
  • Column Column_Name has not been defined. SQLSTATE=42S22
  • View name conflicts with a predefined view definition
  • Out of memory
  • SELECT * only allowed on views
  • Content_Search_Condition OR NOT Content_Boolean_Term not allowed
  • Cannot convert Data_Type_1 to type Data_Type_2
  • Value is out of range for type Data_Type
  • Specification of Relative_Interval must be negative
  • Column_Name is not a column in the view definition
  • Property name conflicts with a predefined property definition
  • Weight value must be between 0.0 and 1.0
  • Error in matches string
  • Property name cannot be set because it is already being used in a VIEW. SQLSTATE=42000
  • View View_Name already exists in catalog Catalog_Name and cannot be redefined. SQLSTATE=42S01
  • Invalid catalog name Catalog_Name. SQLSTATE=42000


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.