xHarbour Reference Documentation > Function Reference

OrdKeyAdd()

Adds an index key to a custom built index.

Syntax

OrdKeyAdd( [<nOrder>|<cIndexName>], ;
           [<cIndexFile>]         , ;
           [<xIndexValue>]          ) --> lSuccess

Arguments

<nOrder>

A numeric value specifying the ordinal position of the custom index open in a work area. Indexes are numbered in the sequence of opening, beginning with 1. The value zero identifies the controlling index.

<cIndexName>

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

<cIndexFile>

<cIndexFile> is a character string with the name of the file that stores the custom index. It is only required when multiple index files are open that contain indexes having the same <cIndexName>.

<xIndexValue>

This is the index value to be added to the index for the current record. It must be of the same data type as the value returned by the index expression. If omitted, <xIndexValue> is obtained by evaluating the index expression with the data of the current record.

Return

The function returns .T. (true) if the current record is successfully included in the index, otherwise .F. (false) is returned.

Description

OrdKeyAdd() is used to build a custom index whose entries are programmatically added and deleted. Custom built indexes are not automatically updated by the RDD but are initially empty. OrdKeyAdd() adds the current record to the custom index and OrdKeyDel() removes it. It is possible to add multiple index values to the index for the same record, so that the same record is found when different search values are passed to DbSeek().

If no parameters are passed, OrdKeyAdd() evaluates the index expresssion with the data of the current record to obtain <xIndexValue>. The record is added to the index when it matches the FOR condition and scoping restrictions, if they are defined. When <xIndexValue> is specified, it must have the same data type as the value of the expression &(OrdKey()).

OrdKeyAdd() fails if the record pointer is positioned on Eof(), if the specified index is not a custom index, or if the specified index does not exist.

This is important when the custom index is the controlling index. Since a custome index is initially empty, relative database navigation with SKIP positions the record pointer always at Eof(). To include records to a controlling custom index, they must be physically navigated to using DbGoto().

The recommended way of creating a custom index is to use a non-custom index as the controlling index, skip through the database and specify <cIndexName> for OrdListAdd() when the current record meets the conditions for being included in the custom index.

Info

See also:	DbOrderInfo(), DbGoto(), INDEX, OrdKey(), OrdKeyDel(), OrdKeyVal()
Category:	Database functions , Index functions
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example shows two approaches for building a custom index.
// In the first approach, the controlling index is a regular index
// which allows for relative database navigation. The second approach
// uses the custome index as controlling index and requires absolute
// database navigation. The first five logical records and physical records
// are added to the custome index.

   REQUEST Dbfcdx

   PROCEDURE Main
      USE Customer VIA "DBFCDX"
      INDEX ON Upper(LastName+FirstName) TAG NAME    TO Cust01
      INDEX ON Upper(LastName+FirstName) TAG NAMESET TO Cust01t CUSTOM

      // relative navigation with non-custom index
      OrdSetFocus( "NAME" )
      GO TOP
      FOR i:=1 TO 5
         OrdKeyAdd( "NAMESET" )
         SKIP
      NEXT

      GO TOP
      Browse()

      // absolute navigation with custom index
      OrdSetFocus( "NAMESET" )
      FOR i:=1 TO 5
         DbGoto( i )
         OrdKeyAdd( "NAMESET" )
      NEXT

      GO TOP
      Browse()

      USE
   RETURN