ClearKey (clear specified key components)

Top  Previous  Next

 

ClearKey ( key [, firstcomponent] [, lastcomponent] [, highvalue] )

ClearKey

Clears or (re)initializes the specified range of key component fields.

key

The label of the KEY.

firstcomponent

A numeric constant, variable, EQUATE, or expression that indicates the first component to clear. If omitted, firstcomponent defaults to one (1).

lastcomponent

A numeric constant, variable, EQUATE, or expression that indicates the last component to clear. If omitted, lastcomponent defaults to twenty-two (22).

highvalue

An integer constant, variable, EQUATE, or expression that indicates whether to clear the components to zero (or spaces for string fields) or to their highest possible values. A value of one (1) applies the highest possible value; a value of zero (0) applies spaces for strings and zeros for numerics. If omitted, highvalue defaults to zero (0).

The ClearKey method clears or (re)initializes the specified range of key component fields.

Implementation: ClearKey is useful for range limiting to the first instance of the first "free" key component. By retaining higher order key component values and clearing lower order key component values, you can fetch the first (or last) record that matches the retained higher order component values; for example, the first order (lower order key component) for a customer (higher order key component).

The value ClearKey assigns depends on three things: the data type of the component field (numeric or string), the sort direction of the component (ascending or descending), and the value of the highvalue parameter (True or False). The following table shows the values ClearKey assigns for each combination of data type, sort direction, and highvalue.

 

 

Numeric Fields

String Fields

 

highvalue

Ascending

Descending

Ascending

Descending

True (1)

High Values

zero

High Values

Spaces

False (0)

zero

High Values

spaces

High Values

Example:

PROGRAM

INCLUDE('ABFILE.INC')              !declare FileManager class

MAP                                !program map

END

GlobalErrors ErrorClass             !declare GlobalErrors object

Access:Order CLASS(FileManager)     !derive Access:Order object

            END

 

Order    FILE,DRIVER('TOPSPEED'),PRE(ORD),CREATE,BINDABLE,THREAD

IDKey     KEY(Ord:Cust,Ord:ID,Ord:Date),NOCASE,OPT,PRIMARY

Record    RECORD,PRE()

Cust       LONG

ID         LONG

Date       LONG

         END

        END

CODE

!program code

!find first order for current customer by clearing all components except Ord:Cust

Access:Order.ClearKey( ORD:IDKey, 2 )     !clear Ord:ID and Ord:Date

Access:Order.Fetch                        !get the next record by key