| Navigation: Language Reference > 13 - Built-in Functions >====== BUILD (build keys and indexes) ====== |    |
| 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: