Query Object

This section lists and describes query object properties and methods. See .Asp Examples for sample query forms constructed with query object properties and methods.

Properties

This section lists and describes the query object properties used in building .asp files.

AllowEnumeration

Type
VARIANT_BOOL

Syntax
TRUE | FALSE

Comments
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. This property expresses the inverse of the .idq parameter CiForceUseCI.

Example
Q.AllowEnumeration = TRUE

Catalog

Type
BSTR

Syntax
indexname

Comments
Gives the catalog name on a local computer. If no name is supplied, indexname defaults to the default catalog on the computer.

Example
Q.Catalog = "kb"

Columns

Type
BSTR

Syntax
Fname1 [ , fname2 ] . . .

Comments
Gives a list friendly column names, with each name separated by commas. This list of columns appears as columns in the result. The column names are case insensitive and can be enclosed in quotation marks if they contain characters other than alphabetic and numeric characters.

Example
Q.Columns = "DocAuthor, vpath, doctitle"

LocaleID

Type
LONG (LCID)

Syntax
number

Comments
Specifies the language code and optional country code used for a query. The value is a Win32 LocaleID (LCID).

Example
Q.LocaleID = 1033 ' EN-US locale code

MaxRecords

Type
LONG

Syntax
number

Comments
Limits the number of records a provider returns from a data source. The default setting of zero means the provider returns all requested records. MaxRecords is Read/Write when the recordset is closed and Read only when it is open.

Example
Q.MaxRecords = 200

OptimizeFor

Type
BSTR

Syntax
performance | recall

Comments
Replaces the .idq parameter CiDeferNonIndexedTrimming. If you choose the performance option, scope and security trimming are deferred until after the maximum number of hits is collected. This option may result in less than the expected number of hits returned for queries in which the scope checks or security trimming removes results. If the option is set to recall, the result set trimming occurs while executing the query. The default is to optimize for recall.

Example
Q.OptimizeFor = "performance"

Query

Type
BSTR

Syntax
Query string

Comments
Determines the documents to be returned in a search. This feature is called the query restriction.

Example
Q.Query = "#filename *.htm and dog near cat"

SortBy

Type
BSTR

Syntax
Fname1 [ [a]|[d] ] [ , fname2 [ [a]|[d] ] ] . . .

Comments
Sorts results in ascending order by default. The option [a] or [d] specifies an ascending or descending sort order respectively.

Example
Q.SortBy = "DocAuthor, rank[d]"

Methods

This section lists and describes the query object methods used in building .asp files.

CreateRecordSet

Executes a query and creates an ADO recordset for navigating through query results.

Syntax
RecordSet = CreateRecordSet( CursorType )

Returns
Returns an ADO RecordSet object for interating over the results of a query.

Arguments
CursorType is either “sequential” or “nonsequential” to create an IRowset (sequential) or an IRowsetScroll (nonsequential) recordset.

Remarks
Before calling CreateRecordSet, you must set any required parameters for a query, such as the Query property and the Columns property.

Example
The following example creates a sequential recordset:
set recordset = Q.CreateREcordSet("sequential")

DefineColumn

Defines a new friendly name for a column.

Syntax
DefineColumn strColumnDef

Returns
Nothing.

Arguments
strColumnDef is a BSTR that defines the column. The syntax of the column definition string is: fname [ ( type ) ] = propset-id [ prop-id | “ prop-name ” ]

Where
fname is the friendly name given to the property, the optional type is the DBTYPE of the column (used in query restrictions). propset-id is a GUID giving the property set ID for the column.
prop-id or prop-name give the property ID or property name for the column.

Remarks
The fname can mask some previously defined or pre-defined 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
Q.DefineColumn "DocAuthor(DBTYPE_WSTR|DBTYPE_BYREF) = F29F85E0-4FF9-1068-AB91-08002B27B3D9 4"

QueryToURL

Produces a uniform resource locator (URL) string reflecting the state of the query object.

Syntax
strQueryString = QueryToURL()

Returns
strQueryString is a BSTR that gives the CGI QueryString. This string is escaped for use in a URL.

Arguments
None.

Example
Href = "http://server/sample.asp?" & Q.QuerytoURL()
Response.Write "<A Href=""" & href & """>Next page</A>"

Reset

Resets the state of the query object.

Syntax
Reset

Returns
Nothing.

Arguments
None.

Remarks
The Reset method clears any internal state in the query object.

Example
Q.Reset

SetQueryFromURL

Sets query parameters from a Web client request.

Syntax
SetQueryFromURL ( strQueryString )

Returns
Nothing.

Arguments
strQueryString is a BSTR that gives the CGI QueryString. This input string is considered to be URL-encoded.

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.

Example
Q.SetQueryFromURL("qu=%40size+%3E+10000&so=rank%5bd%5d&mh=200")

Conventional Form and QUERY_STRING Variables

The following table defines the conventional URL tags in the QUERY_STRING used by the SetQueryFromURL and QueryToURL methods.

URL Tags for the QUERY_STRING

Table Head Text Table Head Text
qu Full text of the query. Associated with the Query property.
so Sort. Associated with the SortBy property.
sd Sort down (in descending order). Associated with the SortBy property.
ct Catalog. Associated with the Catalog property.
mh Maximum hits. Associated with the MaxRecords property.
ae Allow enumeration. Associated with the AllowEnumeration property. If set to a nonzero digit, enumeration is allowed.
op Optimize for. Associated with the OptimizeFor property. The first character of the value can be x for “performance” or r for “recall.”

Tags for Creating Built-Up Query Strings

The following tags create built-up query strings. In each, the 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 & operator.

Table Head Text Table Head Text
cn Column for a built-up query. Associated with the Query property.
on Operator for a built-up query. Associated with the Query property.
qn Query string for a built-up query. Associated with the Query property.

© 1997 by Microsoft Corporation. All rights reserved.