Click above to get retro games delivered to your door ever month!

 AX_SetScope()
 Set or return an index scope value
------------------------------------------------------------------------------

 Syntax

     AX_SetScope( [0 | 1 [, <xValue>]] ) -> scope value

     [ 0 | 1]  An optional numeric value identifying which scope value to
     set:

     0  Specifies the TOP scope is to be set / returned
     1  Specifies the BOTTOM scope is to be set / returned

     <xValue> An optional value to set as the top or bottom scope. The
     value data type must match the data type of the index key.

 Returns

     Returns the previous scope value that existed before this function
     was called.  If <xValue> is not specified, the current scope value is
     returned and no new scope is set.

 Description

     This function sets/returns the specified scope value for the current
     tag or index. It is used to set the TOP and BOTTOM scopes to specific
     index key values.  These values determine the upper and lower limits
     by which to view the index records.  Setting SCOPE values allows you
     to view a subset of the index records without creating a conditional
     index file.

     <xValue> specifies the value to establish as the upper or lower index
     boundary. The index keys visible by the scope are inclusive. The
     scope emulates the actual TOP and BOTTOM of the current index. If
     scoping descending indexes, the SCOPETOP key value will be greater
     than the SCOPEBOTTOM value.

     The specified scope is active as soon as the record pointer is
     repositioned using GO TOP, GO BOTTOM, SEEK or SKIP commands. Using
     the GOTO command will allow the record pointer to be positioned
     outside the defined scope.

     Scopes exist per index order. That is, each index order in each work
     area can have its own scope. Only the scope on the currently active
     index order in the currently active work area is in effect, however.
     Scopes continue to exist until the scope is cleared (using
     CLEAR SCOPE) or the corresponding index is closed. Changing active
     index orders and/or work areas does not clear a scope; it just changes
     what scope is in effect.

     Note:  If both a narrow SCOPE and a narrow FILTER (narrow meaning
     that only a small percentage of the total records in the table match
     the SCOPE and FILTER conditions) are being used in the same work area,
     poor performance may result.  Since knowledge of SCOPEs is ONLY on
     the client, and since FILTERs are handled on the server, the
     filtering of records on the server may unnecessarily traverse
     through the index well beyond one of the SCOPE boundaries, thus,
     leading to poor performance.  If this is occurring, it is recommended
     to use either a SCOPE or a FILTER, but not both in the same work area.

 Example

     USE test VIA "DBFCDXAX"       // Open TEST.DBF
     INDEX ON state TAG state      // Create an index on the STATE field

     AX_SetScope( 0, "AZ" )        // Set the top SCOPE value to "AZ"
     AX_SetScope( 1, "CA" )        // Set the bottom SCOPE value to "CA"

     Browse()                      // Browse all records w/ states from
                                   // AZ-CA

     AX_ClrScope( 0 )              // Clear SCOPETOP
     AX_ClrScope( 1 )              // Clear SCOPEBOTTOM