IDA Scripts
List of Virtual Roots
Enabling Indexing of a Virtual Root
Setting Up a Remote Virtual Root
Forcing a Scan of a Virtual Root
Forcing a Merge
Monitoring Performance
Unfiltered Files
Logging Queries

Microsoft Index Server is designed to minimize administrative requirements. By default, every virtual root is indexed, but indexing can be controlled on a per-root basis. Performance statistics can be retrieved by use of either the Performance Monitor or HTTP.

IDA Scripts

Administrative requests are very similar to queries, except the parameters are stored in an .ida file instead of an .idq file. The parameters available in an .ida file are:

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
`CiAdminOperation`	One of: UpdateRoots, GetState, ForceMerge, or ScanRoots. If not specified, defaults to GetState.	Yes
`CiLocale`	Defines the locale used to issue the query. Standard HTML locale encoding supported.	Yes

You can also pass user-defined variables through 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). See the Security page for more information on security.

Note Do not put .ida files on a virtual root pointing to a remote Uniform Naming Convention (UNC) share.

List of Virtual Roots

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 CiRestriction be set to a non-null value, but a restriction such as #path * 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, plus one special property: metavrootused. This Boolean value is set to TRUE if the root is indexed, FALSE if it is not. A sample administrative query is stored here.

Enabling Indexing of a Virtual Root

To turn indexing of a virtual root on or off, you need only specify CiAdminOperation=UpdateRoots in the .ida file and send one or two special variables in the HTTP GET command. The special variables are PROOT_virtual root and INDEX_virtual root.

A variable with the name PROOT_virtual root identifies the current mapping between virtual and physical root. The virtual root is the variable name after the string PROOT_ and the corresponding physical path is the value of the variable. For example, a home directory pointing to E:\Wwwroot would be described by: PROOT_/ = e:\wwwroot.

If the second special variable, INDEX_virtual root exists, then Index Server will turn indexing on. If this variable does not exist, then indexing will be turned off. In the sample .htx file listing virtual roots, the metavrootused property primes a check box named INDEX_virtual root. This is the resulting page.

When changes are submitted, Index Server compares the new set of virtual roots with the corresponding existing entries and makes the appropriate changes in the index. For each root, possible changes are:

Enable indexing.
Modify the virtual or physical mapping.
Disable indexing.
Do nothing (if the new root state matches the existing index state).

Changes of type (1) and (2) will cause files under the virtual root to be reindexed. Change (3) will remove files under the virtual root from the index.

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, Microsoft Index Server 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 Microsoft Index Server. 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.

Forcing a Scan of a Virtual Root

To force a scan of a virtual root, you need only specify CiAdminOperation=ScanRoots in the .ida file and send two special variables in the HTTP GET command. The special variables are PROOT_virtual root and SCAN_virtual root.

If the second special variable, SCAN_virtual root exists and set to one of IncrementalScan or FullScan, then Index Server will do the specified scan of the virtual directory. If this variable does not exist or set to NoScan, then no scanning will be done.

The sample Scan.htx file lists all the virtual roots that are indexed and by default sets the SCAN_virtual root to NoScan. See the Scanning page for more details on the sample ForceScan administration operation.

Forcing a Merge

The optimal index arrangement for queries is to have just a single master index (See the Indexing page for more details on indexing). You can force the index to that state by running an .ida script with CiAdminOperation=ForceMerge.

Note Master merge is potentially a long, CPU-intensive activity. Query execution may visibly slow during master merge. Consider displaying an extra confirmation page before running the script itself.

Monitoring Performance

There are two ways to monitor performance of Index Server: by using Performance Monitor, or by running an .ida script. The information available is nearly identical, but the method of retrieval differs. Both solutions can be used locally or from a remote client. Performance Monitor has the advantage of automatic refresh, plus graphing and logging capabilities. The .ida script method offers more flexible .htx formatting of the output and the ability to be viewed from a client running an operating system other than Windows.

No setup is required to use the Windows NT Performance Monitor. For the IDA method, you must create an .ida file with CiAdminOperation=GetState. A sample page has been provided. The table below lists the .htx variables available for statistics. Variables starting with CiAdminIndex are in the Content Index performance object. Variables starting with CiAdminCache are in the Http Content Index object.

.htx Variable	Performance Monitor field	Description
`CiAdminCacheActive`	Active queries	Number of queries being executed.
`CiAdminCacheCount`	Cache items	Number of cached queries.
`CiAdminCacheHits`	% Cache hits	Percentage of HTTP requests that use an existing cached query.
`CiAdminCacheMisses`	% Cache misses	Percentage of HTTP requests that execute a new query.
`CiAdminCachePending`	Current requests queued	Number of pending queries waiting for execution.
`CiAdminCacheRejected`	Total requests rejected	Number of queries rejected because the query engine was too busy.
`CiAdminCacheTotal`	Total queries	Number of queries executed since the Web server was started.
`CiAdminIndexCountDeltas`	(not applicable)	Number of documents that have been indexed or deleted since the last master merge.
`CiAdminIndexCountFiltered`	# Documents filtered	Number of documents filtered since Index Server was started.
`CiAdminIndexCountPersIndex`	Persistent indexes	Count of shadow indexes and master indexes in catalog.
`CiAdminIndexCountQueries`	Running queries	Count of queries with open cursors against the catalog. Will differ from the number of active queries in the cache because some cached queries may be enumerated (nonindexed), and some quiescent cached queries may still hold cursors open.
`CiAdminIndexCountToFilter`	Files to be filtered	Number of documents that have been added or modified since the last time they were filtered.
`CiAdminIndexCountTotal`	Total # documents	Number of documents in the catalog.
`CiAdminIndexCountUnique`	Unique Keys	Number of unique words in the catalog. Updated only after a master merge.
`CiAdminIndexCountWordlists`	Word list	Count of word lists in catalog.
`CiAdminIndexMergeProgress`	Merge progress	Percent of current merge completed. Will be 100% when no merge is in progress.
`CiAdminIndexSize`	Index size (in megabytes)	Size in megabytes of index. Includes both in-memory word lists and on-disk shadow indexes and master indexes. Does not include property cache.
`CiAdminIndexStateAnnealingMerge`	n/a	True if an annealing merge is in progress.
`CiAdminIndexStateMasterMerge`	n/a	True if a master merge is in progress.
`CiAdminIndexStateScanRequired`	n/a	True if the catalog needs to be rebuilt, which happens automatically when appropriate.
`CiAdminIndexStateShadowMerge`	n/a	True if a shadow merge is in progress.

Unfiltered Files

Files that are corrupted or files that could not be filtered because of problems in a filter DLL are called unfiltered files and can be viewed by issuing the administrative command for unfiltered files. This command issues the query: @Unfiltered=true. The names section of the .idq file must contain:

[Names]
Unfiltered (DBTYPE_BOOL) = 49691c90-7e17-101a-a91c-08002b2ecda9 7

This property is not in the list of built-in properties, to prevent users from making this request. Unlike the other queries described here, the unfiltered-files query is not restricted to administrators. It can be controlled by placing an ACL on the .idq file that defines the unfiltered property.

Note The unfiltered property connot be used in conjunction with other properties. A query such as @Unfiltered=true & @write >= -1d will return no results.

Logging Queries

Queries are logged through the standard Internet Information Server logging mechanism.