xHarbour Reference Documentation > Function Reference

DbCreateIndex()

Creates a new index and/or index file.

Syntax

DbCreateIndex( <cIndexFile> , ;
               <cIndexExpr> , ;
              [<bIndexExpr>], ;
              [<lUnique>]   , ;
              [<cIndexName>]  ) --> NIL

Arguments

<cIndexFile>

<cIndexFile> is a character string with the name of the file that stores the new index. When the file extension is omitted, it is determined by the database driver that creates the file.

<cIndexExpr>

This is a character expression which describes the index expression in textual form. The expression is evaluated for the records in the current work area. The return value of <cIndexExpr> determines the logical order of records when the index is the controlling index. The data type of the index may be Character, Date, Numeric or Logical. The maximum length of an index expression and its value is determined by the replaceable database driver used to create the index.

<bIndexExpr>

It is the same like <cIndexExpr> but is specified as a code block that can be evaluated. If omitted, the code block is created from <cIndexExpr>.

<lUnique>

If the optional parameter is set to .T. (true), it suppresses inclusion of records that yield duplicate index values. When an index value exists already in an index, a second record resulting in the same index value is not added to the index. When <lUnique> is omitted, the current SET UNIQUE setting is used as default.

<cIndexName>

This is a character string holding the symbolic name of the index to create in an index file. It is analogous to the alias name of a work area. Support for <cIndexName> depends on the RDD used to create the index. Usually, RDDs that are able to maintain multiple indexes in one index file support symbolic index names, such as DBFCDX, for example.

Return

The return value is always NIL.

Description

The index function DbCreateIndex() creates an index for the database open in the current work area. Use an aliased expression to create an index in a different work area.

If the work area has indexes open, they are closed prior to creating the new index. During index creation, the code block <bIndexExpr> is evaluated for each record of the work area and its return value is added to the index. When index creation is complete, the new index becomes the controlling index. As a result, records are viewed in logical index order and no longer in physical order.

Info

See also:	DbClearIndex(), DbReindex(), DbSetIndex(), DbSetOrder(), INDEX, OrdCreate(), OrdListAdd(), OrdSetFocus()
Category:	Database functions , Index functions
Source:	rdd\rddord.prg
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example creates an index file Emp01 on the expression
// Upper(Lastname+Firstname). Note the two notations for the index
// expression.

   PROCEDURE Main
      USE Employees NEW EXCLUSIVE
      DbCreateIndex( "Emp01", ;
                     "Upper(Lastname+Firstname)", ;
                     {|| Upper(Lastname+Firstname) } ;
                   )

      ? IndexKey()                     // result: Upper(Lastname+Firstname)

      Browse()
   RETURN