BUILD (build keys and indexes)

Top  Previous  Next

 

 

 

| file |

 

BUILD(

| index | [, components [, filter ] ] )

 

 

| key |

BUILD

Builds keys and indexes.

file

The label of a FILE declaration.

index

The label of an INDEX declaration.

key

The label of a KEY declaration.

components

A string constant or variable containing the list of the component fields on which to BUILD the dynamic INDEX. The fields must be separated by commas, with leading plus (+) or minus (-) to indicate ascending or descending sequence (if supported by the file driver).

filter

A string constant, variable, or expression containing a logical expression with which to filter out unneeded records from the dynamic index. This requires that you name components for the index. You must BIND all variables used in the filter expression.

The BUILD statement re-builds keys and indexes in a FILE..

BUILD(file)

Builds all the KEYs declared for the file. The file must be closed, LOCKed, or opened with access mode set to 12h (ReadWrite/DenyAll) or 22h (ReadWrite/DenyWrite).

BUILD(key) or BUILD(index)

Builds only the specified KEY or INDEX. The file must be closed, LOCKed, or opened with access mode set to either 12h (ReadWrite/DenyAll) or 22h (ReadWrite/DenyWrite).

BUILD(index,components,filter)

Builds a dynamic INDEX. This form does not require exclusive access to the file, however, the file must be open (with any valid access mode). The dynamic INDEX is created as a temporary file, exclusive to the user who BUILDs it. The temporary file is automatically deleted when the file is closed. If a filter is specified, the resulting INDEX will contain only those records which meet the filter criteria. The filter must be in a format supported by the file driver.

BUILD will generate events to the currently open window if you assign a value (an integer from 1 to 100) to PROP:ProgressEvents for the affected FILE before you issue the BUILD. The larger the value you assign to PROP:ProgressEvents, the more events are generated and the slower the BUILD will progress. These events allow you to indicate to the user the progress of the BUILD. This can keep end-users informed that BUILD is still working while building large files (so they don't re-boot thinking the machine has locked up).

It is not valid to make any calls to the file being built except to query its properties, call NAME(file), or CLOSE(file) (which aborts the process and is not recommended). Issuing a CYCLE statement in response to any of the events generated (except EVENT:BuildDone) cancels the operation. During the BUILD operation, file{PROP:Completed} returns the percentage completed of the re-build and you can use file{PROP:CurrentKey} to get a key reference then either key{PROP:Name} or key{PROP:Label} to return the name of the current key being built.

Errors Posted:

37

File Not Open

40

Creates Duplicate Key

63

Exclusive Access Required

76

Invalid Index String

93

BUILD Cancelled

Events Generated:

EVENT:BuildFile

BUILD(file) is rebuilding the data portion of the file.

EVENT:BuildKey

BUILD(key) or BUILD(index) is rebuilding the key, or BUILD(file) is rebuilding the keys in the file.

EVENT:BuildDone

The BUILD is complete. If the user cancelled the BUILD, ERRORCODE 93 is set.

Example:

Names   FILE,DRIVER('TopSpeed'),PRE(Nam)  !Declare a file structure

NameKey  KEY(Nam:Name),OPT                !Declare name key

NbrNdx   INDEX(Nam:Number),OPT            !Declare number index

DynNdx   INDEX()                          !Declare a dynamic index

Rec      RECORD

Name      STRING(20),NAME('Nam:Name')

Number    SHORT,NAME('Nam:Number')

        END

       END

 

CODE

OPEN(Names,12h)                          !Open file, exclusive read/write

BUILD(Names)                             !Build all keys on Names file

BUILD(Nam:NbrNdx)                        !Build the number index

 

!Build dynamic index ascending number, ascending name:

BUILD(Nam:DynNdx,'+Nam:Number,+Nam:Name')

 

BIND('Nam:Name',Nam:Name)                !BIND the filter variable

 

!Build dynamic index of names that start with A:

BUILD(Nam:DynNdx,'+Nam:Name','UPPER(Nam:Name[1]) = A')

 

UNBIND('Nam:Name')                       !UNBIND the filter variable

 

See Also:

OPEN

SHARE

BIND

PROP:ProgressEvents

PROP:Completed