Note:  You may specify either a VALID or RANGE clause, but not both.

     PICTURE: When you specify the PICTURE clause for a GET, the
     character string specified by <cGetPicture> controls formatting and edit
     validation.  The picture string controls the display format like a SAY
     picture.  It also controls the way the user can edit the buffer.  A
     picture string consists of two distinct parts, a function string and a
     template string, either or both of which may be present.

     .  Function string: A PICTURE function string specifies
        formatting or validation rules which apply to the GET's display value
        as a whole, rather than to particular character positions within it.
        The function string consists of the @ character, followed by one or
        more additional characters, each of which has a particular meaning
        (see the following table).  The function string must be the first
        element of a PICTURE clause and cannot contain spaces.  A function
        string may be specified alone or with a template string.  If both are
        present, the function string must precede the template string, and
        the two must be separated by a single space.

        GET PICTURE Format Functions
        ---------------------------------------------------------------------
        Function     Type Action
        ---------------------------------------------------------------------
        A            C    Allows only alphabetic characters.
        B            N    Displays numbers left-justified.
        C            N    Displays CR after positive numbers.
        D            D,N  Displays dates in SET DATE format.
        E            D,N  Displays dates with day and month inverted
                          independent of the current DATE SETting, numerics
                          with comma and period reverse (European style).
        K            ALL  Deletes default text if first key is not a cursor
                          key.
        R            C    Nontemplate characters are inserted in the display
                          but not saved in the variable.
        S<n>         C    Allows horizontal scrolling within a GET.  <n> is
                          an integer that specifies the width of the region.
        X            N    Displays DB after negative numbers.
        Z            N    Displays zero as blanks.
        (            N    Displays negative numbers in parentheses with
                          leading spaces.
        )            N    Displays negative numbers in parentheses without
                          leading spaces.
        !            C    Converts alphabetic character to uppercase.
        ---------------------------------------------------------------------

     .  Template string:  A PICTURE template string specifies
        formatting or validation rules on a character by character basis.
        The template string consists of a series of characters, some of which
        have special meanings (see the following table).  Each position in
        the template string corresponds to a position in the displayed GET
        value.  Characters in the template string that do not have assigned
        meanings are copied verbatim into the displayed GET value.  If you
        use the @R picture function, these characters are inserted between
        characters of the display value, and are automatically removed when
        the display value is reassigned to <idVar>; otherwise, they overwrite
        the corresponding characters of the display value and also affect the
        value assigned to <idVar>.  You may specify a template string alone
        or with a function string.  If you use both, the function string must
        precede the template string, and the two must be separated by a
        single space.

        GET PICTURE Template Symbols
        ---------------------------------------------------------------------
        Template     Action
        ---------------------------------------------------------------------
        A            Allows only alphabetic characters
        N            Allows only alphabetic and numeric characters
        X            Allows any character
        9            Allows digits for any data type including sign for
                     numerics
        #            Allows digits, signs and spaces for any data type
        L            Allows only T, F, Y or N
        Y            Allows only Y or N
        !            Converts an alphabetic character to uppercase
        $            Displays a dollar sign in place of a leading space in a
                     numeric
        *            Displays an asterisk in place of a leading space in a
                     numeric
        .            Displays a decimal point
        ,            Displays a comma
        ---------------------------------------------------------------------

     SCOREBOARD: If a new value is rejected because it fails the RANGE*
     test or because it is a malformed date value, a message appears on the
     screen.  The message displays in the SCOREBOARD area, which you can
     enable or disable using the SET SCOREBOARD command.

     Exit with Esc: If the user exits a GET by pressing Esc, the GET
     variable is restored to the value it had on entry to the GET, and the
     READ is terminated.  No postvalidation is performed.  You can enable or
     suppress this behavior with the SET ESCAPE command.

     SET KEY procedures: The SET KEY command lets you specify a procedure
     to be executed whenever a specific key is pressed during a READ.  After
     a SET KEY procedure terminates, the GET is reactivated with the cursor
     restored to its previous position.

     Lifetime of a Get object: Get objects, like arrays, exist as long as
     there are active references to them somewhere in the current program.
     Normally, only the array in the GetList variable maintains a reference
     to the Get object; the GET is released when GetList is released or
     reassigned.  The CLEAR and CLEAR GETS commands assign an empty array to
     GetList, as does the READ command unless you specify the SAVE clause.

     Assignment: Each GET is associated with a variable, <idVar>, in the
     @...GET command.  At various times during the editing process, <idVar>
     may be assigned the current value of the Get object's buffer.  This
     occurs in the following instances:

     .  After the user presses an exit key and before the validation
        expression is executed

     .  After the user presses a SET KEY

     Also, the current Get object's buffer is refreshed from <idVar> and
     redisplayed at various intervals:

     .  After a SET KEY procedure terminates

     .  After a WHEN expression is evaluated

     .  After a VALID expression is evaluated

     This lets you explicitly assign <idVar> within any of these operations.
     See the note below for more information.

     GET coordinates and display: When you create a Get object using the
     @...GET command, the row and column coordinates at which the GET is
     initially displayed are stored in the Get object.  When the @...GET
     command executes, the new GET displays at <nRow> and <nCol>, unless you
     specify the SAY clause which positions the GET so there is one display
     column between the last character of the SAY output and the first
     character of the GET (or of the DELIMITERS, see below).

     If SET DELIMITERS is ON when the @...GET command executes, the current
     DELIMITER characters display on either side of the initial GET display,
     and the column coordinate of the GET is adjusted accordingly.  Note that
     the delimiters are not attributes of the Get object, but simply display
     as the SAY clause does.

     If INTENSITY is ON, GETs initially display in the current unselected
     color (or the enhanced color, if no unselected color has been
     specified).  During a READ, the active GET displays in the enhanced
     color, while the remaining GETs display in the unselected color.  With
     INTENSITY OFF, all GETs display in the standard color.

     When a GET displays, the width of the displayed value is determined by
     the length of the value in <idVar> or, if you specify the PICTURE
     clause, by the number of positions in <cGetPicture>.  If you specify the
     @S function as a part of <cGetPicture>, the @S argument controls the
     width of the displayed value.

 Notes

     .  WHEN and VALID:  The expressions specified in the WHEN and
        VALID clauses may be of arbitrary complexity and may include calls to
        user-defined functions.  This is useful for attaching automatic
        actions to the activation or deactivation of a GET.

     .  Assigning <idVar>:  Because of the automatic refresh and
        display properties of a Get object while it is being READ, you can
        make an explicit assignment to the Get object's <idVar> within a WHEN
        or VALID expression.  You can directly assign the variable by name in
        the validation expression or, for private, public, local, or static
        variables, by passing a reference to <idVar> to a function; the
        function can then assign <idVar> by assigning the corresponding
        formal parameter.  If <idVar> is a field, it is globally visible and
        can be assigned by name in a function called by the validation
        expression.

        When including a GET in a called function, do not include an <idVar>
        with the same name as a field <idVar>.  Field references have
        precedence over public variables so the public <idVar> will be
        ignored.

     .  GET specific help:  You can use a SET KEY procedure to display
        help text associated with a Get object.  Within the SET KEY
        procedure, use the READVAR() function to determine the <idVar>
        associated with the current Get object.  Use this information to
        display the appropriate help text.  Remember that when a CA-Clipper-
        compiled program loads, the F1 KEY is automatically SET TO a
        procedure or user-defined function named Help.

     .  SET DEVICE TO PRINTER: SET DEVICE TO PRINTER does not direct
        display of a Get object under the @...GET command to the printer or
        file.

 Examples

     .  This  example uses the VALID clause to validate input into a
        GET:

        LOCAL nNumber := 0
        @ 10, 10 SAY "Enter a number:" ;
           GET nNumber VALID nNumber > 0

     .  This example demonstrates passing a code block with the VALID
        clause.  The parameter oGet is the current Get object.  Udf() changes
        the value of the GET:

        LOCAL GetList := {}, cVar := SPACE(10)
        CLS
        @ 10, 10 GET cVar  VALID { |oGet| Udf1( oGet ) }
        READ
        .
        .
        .
        * Udf( <oGet> ) --> .T.

        FUNCTION Udf1( oGet )

        IF "test" $ oGet:BUFFER          // Compare buffer contents
        oGet:varPut( "new value " )      // Change contents
        ENDIF

        RETURN .T.

     .  This example uses the WHEN clause to prohibit entry into GETs
        based on the value of another GET.  In this example, entering Y in the
        Insured field indicates the client has insurance and the user is
        allowed to enter insurance information.  If the client does not have
        insurance, the cursor moves to the Accident field:

        @ 10, 10 GET Insured PICTURE "Y"
        @ 11, 10 GET InsNumber WHEN Insured
        @ 12, 10 GET InsCompany WHEN Insured
        @ 13, 10 GET Accident PICTURE "Y"
        READ

     .  This is an example of a GET in a secondary work area:

        USE Invoice NEW
        APPEND BLANK
        USE Inventory NEW
        @ 1, 1 GET Invoice->CustNo
        READ

     .  This example uses the @K function to suggest a default input
        value, but deletes it if the first key pressed is not a cursor key or
        Return:

        LOCAL cFile := "Accounts"
        @ 1, 1 SAY "Enter file" GET cFile PICTURE "@K"
        READ

     .  This is an example of a nested READ using a GetList and
        lexical scoping:

        #include "inkey.ch"
        //
        // Local to this function only
        LOCAL GetList := {}
        LOCAL cName   := SPACE( 10 )
        //
        CLS
        SETKEY( K_F2, { || MiscInfo() } )   // Hot key to special READ
        //
        // Get object added to getlist
        // works on local getlist
        @ 10, 10 SAY "Name" GET cName
        READ
        //
        RETURN NIL

        /***
        *  MiscInfo() ---> NIL
        */FUNCTION MiscInfo()
        //
        LOCAL GetList    := {}               // Local to this
        LOCAL cExtraInfo := SPACE( 30 )      // function only
        //
        // Get object added to getlist
        // works on local getlist
        @ 12, 10 SAY "Note: " GET cExtraInfo
        READ
        //
        RETURN NIL


 Files   Library is CLIPPER.LIB.