Command SET SCOPE | Xbase++

Sets/clears scope values for logical or physical orders

SET SCOPE TO
SET SCOPE TO <xValue>
SET SCOPE TO <xTop>, <xBottom>
 
SET SCOPETOP TO
SET SCOPETOP TO <xTop>
SET SCOPEBOTTOM TO
SET SCOPEBOTTOM TO <xBottom>
BScope:!EF current work area, current order

is the value to be used for both the top and the bottom scope.

<xTop>

is the top scope.

is the bottom scope.

When these parameters are omitted, the scope is cleared instead of being set (similar to SET FILTER TO with no parameters).

<xValue>, <xTop>, and <xBottom> must have the same data type as the index key or must be a numeric specifying a record number when no controlling index is active.

A scope is used to quickly specify a range of records in a database. Only those records whose scope values lie within the range of the top and bottom scope values are visible. In general, scoping can be used in any situation that would require a SEEK/WHILE loop. Scoping is particularly useful for browsing a database with TBrowse() or XbpBrowse(), since it is far simpler to use a scope than to set up a custom skip block, and is extremely fast. Also, scoping is good for query processing where scopes can be used to restrict the number of records and an additional filter is used to determine the relating subsets of the query.

A scope can be set for each order, be it a physical or logical order. A table may have its own scope using a record number as the scope value. The scope remains active until it is cleared using SET SCOPE TO (with no value) or the relating index or table is closed.

SET SCOPE TO with no parameters clears both the top and bottom scope.

SET SCOPETOP TO with no parameters clears the top scope.

SET SCOPEBOTTOM TO with no parameters clears the bottom scope.

SET SCOPE TO <xValue> sets both the top and bottom scope value for the controlling index to the same value.

SET SCOPE TO <xTop>, <xBottom> sets the top and bottom scope value for the controlling index to different values in a single command.

SET SCOPETOP TO <xTop> sets the top scope to the given value.

SET SCOPEBOTTOM TO <xBottom> sets the bottom scope to the given value.

Scoped database navigation

DbGoTop()

Positions the record pointer on the first record matching <xTop>.

DbGoBottom()

Positions the record pointer on the last record matching <xBottom>.

Bof()

Is set to .T. (true) when attempting to move the record pointer before <xTop>.

Eof()

Is set to .T. (true) when attempting to move the record pointer behind <xBottom>.

DbSeek()

Finds only records that lie within the scope.

DbGoto()

Moves the record pointer to the specified record, which may be located outside of the scope. If the record pointer is outside the scope it will be positioned at Eof() with the next SKIP operation.

DbPosition()

This function and DbGoPosition() are conforming with the scope settings, they return 0% for DbGoTop() and 100% for DbGoBottom(). Therefore they are restricted to positions inside the rowset as defined by the scope.

There is no restriction with FILTERing a scoped database. SCOPEs and FILTERs can be mixed

There is no restriction with SET RELATION TO ... SELECT either. Filters, scopes and relational restrictions can be defined simultaneously.

Setting scopes

// The example demonstrates the effect of scopes 
// for the browse display of a database 

PROCEDURE Main 

   USE Customer EXCLUSIVE 
   INDEX ON Upper(LastName+FirstName) TO CustA 

   // display all customers 
   Browse() 

   // display customers whose lastname begins with "H" 
   SET SCOPE TO "H" 

   Browse() 

   // display lastnames between "B" and "K" 
   SET SCOPETOP    TO "B" 
   SET SCOPEBOTTOM TO "K" 

   Browse() 

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

Command SET SCOPE Foundation