xHarbour Reference Documentation > Function Reference

OrdCreate()

Creates a new index.

Syntax

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

Arguments

<cIndexFile>

This 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.

<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.

<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.

Return

The function returns NIL.

Description

The index function OrdCreate() 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.

Indexes are created by the RDD used to open the database, according to the conditions specified with function OrdCondSet(). If the RDD does not support multiple indexes per index file (DBFNTX, for example) an existing index file <cIndexFile> is overwritten. If multiple indexes are supported by an RDD (DBFCDX, for example) and <cIndexFile> is open, a new index <cIndexName> is added to the file. If <cIndexName> exists already in the list of open indexes, it is replaced with a new index having the expression <cIndexExpr>.

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:	DbCreateIndex(), DbOrderInfo(), INDEX, OrdCondSet(), OrdListAdd(), OrdListClear(), Set()
Category:	Database functions , Index functions
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example creates two indexes in one index file.

   REQUEST Dbfcdx

   PROCEDURE Main

      USE Customer ALIAS Cust NEW VIA "DBFCDX"

      OrdCreate( "Customer", "ID"  , "CUSTNO"  )
      OrdCreate( "Customer", "NAME", "Upper(LastName+FirstName)" )
      OrdListClear()

      OrdListAdd( "Customer" )

      ? OrdNumber()               // result: 1
      ? OrdName()                 // result: ID
      ? OrdKey()                  // result: CUSTNO

      ? OrdSetfocus( "NAME" )     // result: ID
      ? OrdNumber()               // result: 2
      ? OrdName()                 // result: NAME
      ? OrdKey()                  // result: Upper(LastName+FirstName)

      CLOSE Cust

   RETURN