xHarbour Reference Documentation > Function Reference

OrdKeyRelPos()

Returns or sets the relative position of the current record.

Syntax

OrdKeyRelPos( [<nNewPosition>] ) --> nRelativePosition

Arguments

<nNewPosition>

Optionally, a numeric value between 0 and 1 can be passed. It specifies the relative position to move the record pointer to.

Return

The function returns a value between 0.0 and 1.0 (inclusive), which is the relative position of the current record.

Description

The function is used to obtain the relative position of the record pointer, or to move it to a relative position. The relative position is specified as a value between 0 and 1. The return value multiplied with 100 is the relative position of the record pointer in percent of all records. It can be used to visualize the record pointer position with a scroll bar.

OrdKeyRelPos() can be used with both, indexed and non-index databases. If a controlling index is active, the function returns the relative position of the current record within the controlling index. If a scope is set for the controlling index using OrdScope(), the number of visible records is taken into account. Filter conditions that limit the logical visibility of records are ignored.

Note that the relative psoition returned by OrdKeyRelPos() is only an estimate whose accuracy grows with the number of records.

Info

See also:	DbOrderInfo(), OrdKeyCount(), OrdKeyGoTo(), OrdScope(), Recno()
Category:	Database functions , Index functions , xHarbour extensions
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates the relative position of the first/last
// physical/logical record in an indexed database.

   PROCEDURE Main
      USE Customer

      INDEX ON Upper(LastName)
      SET DECIMALS TO 4

      GO TOP                        // Logical first record
      ? Lastname, OrdKeyRelPos()    // result: Alberts  0.0227

      DbGoto( 1 )                   // Physical first record
      ? Lastname, OrdKeyRelPos()    // result: Miller   0.6591

      GO BOTTOM                     // Logical last record
      ? Lastname, OrdKeyRelPos()    // result: Waters   0.9773

      DbGoto( LastRec() )           // Physical last record
      ? Lastname, OrdKeyRelPos()    // result: Smith    0.8864

   RETURN