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

SET SCOPE            Set/clear top and bottom index scope
------------------------------------------------------------------------------

Synopsis

    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>

Arguments

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

    <xTop> is the top scope.

    <xBottom> 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>, or <xBottom> can all be CodeBlocks as well.  This
    capability, in conjunction with SET RELATION TO allows you to handle
    one-to-many relations cleanly.  (Our thanks to Mark Worthen for this
    idea).

    <xValue>, <xTop>, and <xBottom> should all be the same type as the index
    key (or a CodeBlock which evaluates to the same type as the index key).

Description

    A scope allows you to quickly specify a range of records which are
    visible.  Only records with keys which fall within the range of the top
    and bottom scope values are visible.

    In general, scoping can be used anywhere that you would otherwise use a
    SEEK/WHILE loop.  Scoping is particularly useful with TBrowse, since it
    is far simpler to use than setting up custom skip blocks, and is
    extremely fast.

    Each index may have its own scope.  The scope will remain active until
    it is cleared using SET SCOPE TO (with no value) or the index is
    closed.

    GO TOP will position to the first record with a key matching <xTop>.

    GO BOTTOM will position to the last record with a key matching
    <xBottom>.

    When SKIP'ing forward, EOF() will be reached when you skip to a record
    with a key which is after <xBottom>.

    When SKIP'ing backward, BOF() will be reached when you skip to a record
    with a key which is before <xTop>.

    SEEKs will find only records which are within the scope.

    GOTO will access records which are outside of the index scope.  However,
    if you attempt to SKIP from a record which is outside of the scope
    (either before <xTop> or after <xBottom>), you will immediately be
    positioned at EOF().

    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
    current master index to the same value.

    SET SCOPE TO <xTop>, <xBottom> sets the top and bottom scope value for
    the current master 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.

Example

    use demo
    set index to last, age

    set order to tag last
    set scope to "C"            && Only last names which start with 'C'
                                && are now visible
    list last                   && Will only see 'C's

    set scopetop to             && Clear the top scope
    list last                   && Will now see everything from beginning
                                && through 'C's

    set scopetop to 'B'         && Set the top scope to 'B'
    list last                   && Will now see the 'B's through the 'C's

    seek 'D'                    && Won't find anything (out of scope)
    ? found()                   && .F.

    set scopebottom to          && Clear the bottom scope
    seek 'D'                    && Will now find it ('B's - eof now visible)
    ? found()                   && .T.

    set order to tag age
    set scope to 25,30          && Only people with an age of 25..30 visible
    list age

    set scopebottom to 40       && People with an age of 25..40 visible
    list age

    set scope to                && Clear the scope
    list age                    && Now everybody's visible

Example

        //  Use the CodeBlock for scope capability
    use invoice new

    use customer new
    set relation to customer->cid into invoice

    sele invoice
    set order to tag cid
    set scope to { || customer->cid }

        /*  In a TBrowse, just set up a child TBrowse (on invoice) and as
            you move to different customer records, call refreshAll() for
            the child TBrowse.

            Here's a simple listing program to illustrate.
         */


        //  Do a simple listing to illustrate the point
    customer->(dbGoTop())
    do while !customer->(eof())
        ? customer->cid, customer->first, customer->last

            /*  Only invoices for this customer will be listed, without
                having to change the scope (since scope is a CodeBlock)
             */
        list "   ", invoice->date, invoice->amount, invoice->paid

        customer->(dbSkip())
    enddo
    
See Also

    cmxClrScope(), cmxSetScope()