xHarbour Reference Documentation > Function Reference

OrdScope()

Defines the top and/or bottom scope for navigating in the controlling index.

Syntax

OrdScope( <nScope>, [<xNewValue>] ) --> xOldValue

Arguments

<nScope>

The parameter is a numeric value identifying the top or bottom scope to set or clear. #define constants are available in Ord.ch that can be used for <nScope>.

#define constants for <nScope>

Constant	Value	Description
TOPSCOPE	0	Specifies the top scope
BOTTOMSCOPE	1	Specifies the bottom scope

<xNewValue>

The parameter is specifies the value to be used as top or bottom boundary for the scope of the controlling index. The value must be of the same data type as the the value of the index expression, or it can be a code block that returns a value of this data type.

If <xNewValue> is omitted or the value NIL is passed explicitely for <xNewValue>, a previously defined top or bottom scope is cleared.

Return

The function returns the value for the top or bottom scope that is defined before the function is called.

Description

The OrdScope() function defines or clears the top and bottom scope for indexed database navigation. The top and bottom scope values define the range of values valid for navigating the record pointer within the controlling index.

Top and bottom scope value are inclusive, i.e. they are part of the resulting subset of records. They can be defined as constant values or as code blocks. When code blocks are used for top and/or bottom scope, they must return a value having the data type of the index expression. The scope code blocks are evaluated during database navigation, so that scope boundaries can change dynamically while the record pointer is moved.

When a scope is set, the GO TOP command is equivalent to DbSeek( <topScope> ), while GO BOTTOM is the same as DbSeek( <bottomScope>, .F., .T. ).

Attempting to move the record pointer before the top scope value does not change the record pointer but causes function BoF() to return .T. (true).

When the record pointer is moved beyond the bottom scope value, it is advanced to the ghost record (Lastrec()+1) and function EoF() returns .T. (true).

Note:  The current scope settings can be queried without altering them using function DbOrderInfo().

Info

See also:	DbOrderInfo(), OrdCondSet(), OrdKey(), SET RELATION, SET SCOPE
Category:	Database functions , Index functions
Header:	Ord.ch
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates evaluation of scope code blocks while a
// database is browsed. Although the code blocks return constant values,
// they could return the result of a function call as well.

   #include "Ord.ch"

   PROCEDURE Main
      USE Customer
      INDEX ON Upper(LastName+Firstname) TO Cust01

      OrdScope( TOPSCOPE   , {|| Tone(1000), "E" } )

      OrdScope( BOTTOMSCOPE, {|| Tone(500), "K" } )

      Browse()
   RETURN