AdsSetScope

Advantage Client Engine

Sets a scope for the given index order.

Syntax

UNSIGNED32

AdsSetScope (ADSHANDLE hIndex,

UNSIGNED16 usScopeOption,

UNSIGNED8 *pucScope,

UNSIGNED16 usScopeLen

UNSIGNED16 usDataType);

Parameters

hIndex (I)

Handle of index order.

usScopeOption (I)

Indicates which scope value to set. Options are ADS_TOP and ADS_BOTTOM.

pucScope (I)

Scope value to set.

usScopeLen (I)

Length of scope value.

usDataType (I)

Indicates type of data given in pucKey. ADS_RAWKEY indicates that the key is given exactly as needed for seek. No conversion is performed. ADS_STRINGKEY indicates the data is in a character string (numeric date, and ANSI/OEM conversions performed as necessary. ADS_DOUBLEKEY indicates that the data is a pointer to an 8-byte floating-point value.

Remarks

AdsSetScope sets a scope for the index to limit the number of records visible. For example, setting a ADS_TOP scope of "M" on a index on a character field will make an AdsGotoTop call on this index go to the first key greater than or equal to "M". An ADS_BOTTOM scope will make the indicated value the last one visible in the index order. For example, if AdsSetScope is called with ADS_BOTTOM and "Smith" on a lastname index, the last Smith on an AdsGotoBottom call will be the current record. Set the scope for top and bottom to the same value to view only those records with the given scope value from the index.

It is not necessary to have both top and bottom scopes set at the same time. The Advantage Client Engine does not check that the ADS_TOP and ADS_BOTTOM scopes are not mutually exclusive. When setting scopes on descending indexes, the ADS_TOP scope will be set at the logical top of the index (largest key) and the ADS_BOTTOM is at the logical bottom (smallest key).

To set a scope using indexes built on date, time, or timestamp fields, it is simplest to pass the scope value as a string (ADS_STRINGKEY). The date should be formatted according the current date mask (AdsSetDateFormat). For example, to set a scope on a date index, an application might pass "2/25/1997" as the value. To set a scope on a timestamp index, the value could be "2/25/1997 3:25pm". An application can use a double (ADS_DOUBLEKEY) to set a scope on date and time indexes; the value for a date index must be passed as a Julian date, and the value for a time index must be passed as milliseconds since midnight.

Note If both a narrow scope and a narrow filter (narrow meaning that very few records match the scope or filter conditions) are being used on the same table, poor performance may result. Since knowledge of scopes is only on the client, and filters are handled on the server, the filtering of records on the server may unnecessarily traverse well beyond the bounds of a scope, causing poor performance. If this condition is expected, it is recommended to use either a scope or a filter, but not both.

Example

Click Here

See Also

AdsClearScope

AdsGetScope

AdsSeek

AdsSkip

AdsGotoTop

AdsGotoBottom

AdsClearAllScopes

AdsInitRawKey

AdsBuildRawKey