Function OrdKeyNo() | Xbase++

Determines the relative logical record number of the current data record within the indexed database.

OrdKeyNo( [<nIndex> | <cTagName>] ) --> nRelativeRecord

<nIndex> is a positive integer specifying the ordinal position within the work area of the index OrdKeyNo() uses to determine the logical position of the record pointer. By default, the controlling index is used.

Instead of <nIndex>, <cTagName> can be specified. This is a character string containing the name of the index.

The return value of OrdKeyNo() is a numeric value indicating the relative position of the record pointer within the indexed database. If no index is available, the function returns zero.

When an index is active in a work area, the data records are logically sorted and are no longer accessed in physical order. In this case, the function Recno() cannot be used to indicate the position of the record pointer relative to the first data record. As an example, when logically sorted the data record with Recno()=100 might be the first data record. The function OrdKeyNo() serves to determine the relative position of the record pointer in relation to the first logical (not physical) data record.

The function OrdKeyNo() is similar to Recno(). However, OrdKeyNo() determines the position of the record pointer based on the index file containing the controlling (current) index. OrdKeyNo() always returns a numeric value. The function Recno(), on the other hand, returns the identity of a data record which may not be represented by a numeric value. The return value of OrdKeyNo() is used only for display purposes, such as to visually show the relative position of the record pointer.

Displays the position of record pointer for indexed databases


// In this example, a typical use of OrdKeyNo() is demonstrated. Data 
// from an indexed database is shown using a Tbrowse object. The 
// relative position of the record pointer is output using a scroll 
// bar displayed in the right side of the TBrowse. 

#include "Inkey.ch" 

PROCEDURE Main 
   LOCAL oTB 

   USE Customer EXCLUSIVE           // open DBF and create index 
   INDEX ON Upper(LastName+FirstName) TO CustA 
   SET INDEX TO CustA 

   oTB := TBrowseDB( 3, 4, 21, 75 ) // create TBrowse 
   AEval( DbStruct(), {|a| oTB:AddColumn(             ; 
                              TBColumn():new( a[1],   ; 
                                 FieldBlock(a[1]) ) ) } ) 
   CLS 
   DbBrowseWindow( oTB )            // display TBrowse 
RETURN 

*******************************     // display TBrowse with 
PROCEDURE DbBrowseWindow( oTB )     // scroll bar 
   LOCAL aScrollBar[6], nKey, nRecordPos 

   @ oTB:nTop   -1, oTB:nLeft -1 TO ; 
     oTB:nBottom+1, oTB:nRight+1 DOUBLE 

   nKey          := 0 
   nRecordPos    := OrdKeyNo() 

   aScrollBar[1] := oTB:nTop   + 1  // top 
   aScrollBar[2] := oTB:nRight + 1  // right 
   aScrollBar[3] := oTB:nBottom- 1  // bottom 
   aScrollBar[4] := oTB:nTop   + 1  // position for indicator 
   aScrollBar[5] := 0               // record pointer position 
   aScrollBar[6] := LastRec()       // number of data records 

   DO WHILE nKey <> K_ESC 
      DO WHILE ! oTB:stabilize()    // incrementally display 
         IF (nKey := Inkey()) <> 0 
            EXIT 
         ENDIF 
      ENDDO 

      IF oTB:stable                 // TBrowse is stable 
         nRecordPos := OrdKeyNo()   // relative data record position 
         IF nRecordPos <> aScrollBar[5] 
            DispScrollBar( aScrollBar, nRecordPos ) 
         ENDIF 
         nKey := Inkey(0)           // wait for key press 
      ENDIF 

      TBApplyKey( oTB, nKey )       // process key 
   ENDDO 
RETURN 

************************************************** 
STATIC PROCEDURE DispScrollBar( aScrollBar, nPos ) 
   LOCAL nRow := Row(), nCol := Col() 

   IF aScrollBar[5] == 0            // display scroll bar first time 
      @ aScrollBar[1]-1 , aScrollBar[2] SAY Chr(24) // up arrow 
      @ aScrollBar[3]+1 , aScrollBar[2] SAY Chr(25) // down arrow 
      DispBox( aScrollBar[1], aScrollBar[2], ; 
               aScrollBar[3], aScrollBar[2], Chr(176) ) 
      aScrollBar[5] := 1 
   ENDIF 

   @ aScrollBar[4], aScrollBar[2] SAY Chr(176) // erase indicator 

   DO CASE 
   CASE nPos <= 1                    // first data record 
      aScrollBar[4] := aScrollBar[1] 
   CASE nPos >= aScrollBar[6]        // last data record 
      aScrollBar[4] := aScrollBar[3] 
   OTHERWISE                         // calculate indicator position 
      aScrollBar[4] := aScrollBar[1]  + ; 
            Int( (nPos/aScrollBar[6]) * ; 
                 (aScrollBar[3]-aScrollBar[1]+1) ) 
   ENDCASE 

   aScrollBar[5] := nPos             // store record pointer position 
   @ aScrollBar[4], aScrollBar[2] SAY Chr(219) // display indicator 
   SetPos( nRow, nCol )              // restore cursor position 
RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function OrdKeyNo() Foundation