DbCreateIndex Function |  |
Create an index file and add an order to it.
Namespace: XSharp.RT
Assembly: XSharp.RT (in XSharp.RT.dll) Version: 2.19
SyntaxRequest Example
View Source
TRUE if successful; otherwise, FALSE.
Parameters
- cIndexFile (Optional)
- Type: Usual
The name of the target index file, including an optional drive, directory, and extension. See SetDefault() and SetPath() for file searching and creation rules.
The default extension is determined by the RDD and can be obtained using DBOrderInfo(DBOI_INDEXEXT).
In RDDs that support production indexes, the production index file is assumed if cIndexFile is not specified.
If cIndexFile does not exist, it is created.
If cIndexFile exists, DBCreateIndex() must first obtain exclusive use of the file.
If successful, the file is overwritten without warning or error.
If the attempt is unsuccessful because, for example, the file is open by another process, NetErr() is set to TRUE. - cKeyValue (Optional)
- Type: Usual
The order key expression specified as a string.
This is the key expression that is stored in the index file and used for such purposes as locating key values and recreating the order.
Although cKeyValue is optional, it is highly recommended that you specify this argument. Without it, the order will be properly created using cbKeyValue, but the key expression will be stored in the index file as a NULL_STRING, rendering the order unusable for subsequent access. - cbKeyValue (Optional)
- Type: Usual
The order key expression specified as a code block.
This code block is used to initially create the order.
If you do not supply cbKeyValue, it is macro-compiled from cKeyValue (for example, {||&cKeyValue}).
The data type of the key expression and all other limitations, including the length of the key and the key expression, are determined by the RDD. - lUnique (Optional)
- Type: Usual
TRUE creates a unique order by including only those records with unique key values; FALSE uses all records in the database file.
If lUnique is omitted, the SetUnique() setting is used.
Return Value
Type: LogicTRUE if successful; otherwise, FALSE.
Remarks
By default, this function creates an index file for the database file associated with the currently selected work area.
It can be made to operate on an unselected work area by specifying it within an aliased expression. DBCreateIndex() uses the current DBSetOrderCondition() to determine the conditions for the order (for example, its scope, for condition, and while condition). If there are other open index files in the work area, they are closed.
After the new index file is created, an order is added to the file using the index file name and the specified key.
The index file is opened (in the same mode as its associated database file), the controlling order for the work area is set, and the database file is positioned to the first logical record.
It can be made to operate on an unselected work area by specifying it within an aliased expression. DBCreateIndex() uses the current DBSetOrderCondition() to determine the conditions for the order (for example, its scope, for condition, and while condition). If there are other open index files in the work area, they are closed.
After the new index file is created, an order is added to the file using the index file name and the specified key.
The index file is opened (in the same mode as its associated database file), the controlling order for the work area is set, and the database file is positioned to the first logical record.
 Tip |
|---|
| If the RDD supports multiple orders per index file, add subsequent orders to the index file using DBCreateOrder(). |
| Tip |
|---|
|
Side effects: DBCreateIndex() is guaranteed to create an order that, when made the controlling order, will impose the specified logical order on the database. The key expression is not necessarily evaluated at any particular time, by any particular means, or on any particular record or series of records. If the key expression relies on information external to the database file or work area, the effect is unpredictable. If the key expression changes the state of the work area (for example, by moving to a different record or changing the contents of a record), the effect is unpredictable. Key evaluation: Before the key expression is evaluated, the associated work area is automatically selected as the current work area; the previously selected work area is automatically restored afterward. |
Examples
This example creates an index file, EMPNAME, indexed on the Name field:
X#
1USE employee NEW 2Employee->DBCreateIndex("EmpName", "Name", ; 3 {|| Employee->Name})
See Also