| **Navigation:**  [[introduction.htm|Language Reference]] > 13 - Built-in Functions >====== BUILD (build keys and indexes) ====== | [[buffer  set record paging .htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[bxor  return bitwise exclusive or .htm|{{btn_next_n.gif|Next page}}]] |
|  ||

|  |  | | //file //| |
|  | **BUILD(** | | //index //| [,// components// [,// filter //] ] **)** |
|  |  | | //key //| |

{{blk2blue.jpg|blk2blue.jpg}}

| **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.htm|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  open a data structure .htm|OPEN]]

[[share  open data file for shared access .htm|SHARE]]

[[bind  declare runtime expression string variable .htm|BIND]]

[[prop progressevents.htm|PROP:ProgressEvents]]

[[prop completed.htm|PROP:Completed]]