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

 @...SAY
 Display data at a specified screen or printer row and column
------------------------------------------------------------------------------
 Syntax

     @ <nRow>, <nCol>
        SAY <exp> [PICTURE <cSayPicture>]
        [COLOR <cColorString>]

 Arguments

     <nRow> and <nCol> are the row and column coordinates of the
     display.  Row values can range from zero to a maximum of MAXROW() if the
     current DEVICE is the SCREEN or 32,766 if the current DEVICE is the
     PRINTER.  Also, column values can range from zero to a maximum of
     MAXCOL() or 32,766 if the current DEVICE is the PRINTER.

     SAY <exp> displays the result of a character, date, logical, or
     numeric expression to the current DEVICE.

     PICTURE <cSayPicture> defines the formatting control for the display
     of <exp>.  CA-Clipper provides two mechanisms, functions and templates,
     to control formatting.  Functions apply to an entire SAY, while
     templates format characters position by position.

     COLOR <cColorString> defines the display color of <exp>.  If not
     specified, <exp> displays in the standard color as defined by
     SETCOLOR().  <cColorString> is a character expression containing the
     standard color setting.  If you specify a literal color setting, it must
     be enclosed in quote marks.

     On a combined @...SAY...GET command, two COLOR clauses are required to
     specify colors for both the SAY and the GET: one for the SAY and one for
     the GET.

 Description

     @...SAY is a full-screen command that outputs the results of <exp> to
     either the screen or the printer at the specified row and column
     coordinates.  It can optionally format output using the PICTURE clause.
     @...SAY creates data entry screens or reports that can be sent to the
     screen or printer.

     When an @...SAY command executes , the output from <exp> is sent to the
     current device defined with SET DEVICE.  The current DEVICE can be the
     SCREEN or PRINTER.  Unlike console commands, @...SAY output to the
     printer is not echoed to the screen and SET CONSOLE has no effect on
     @...SAY output to the screen.

     If the current DEVICE is the SCREEN (the system default), @...SAY
     displays output to the screen leaving the cursor one column position to
     the right of the last character displayed.  ROW() and COL() are then
     updated with this position.  Output that displays off the screen, as
     defined by MAXROW() and MAXCOL(), is clipped and the cursor is
     positioned beyond the visible screen.  All @...SAY output displays are
     in standard color.  Refer to the SETCOLOR() reference in this chapter
     for more information on color.

     If the current DEVICE is set to PRINTER, the display is directed to the
     printer at the specified <nRow> and <nCol> position.  If current MARGIN
     value is greater than zero, it is added to <nCol> first.  The printhead
     is then advanced one column position to the right of the last character
     output and PROW() and PCOL() are updated.  @...SAY commands to the
     printer behave differently than to the screen if output is addressed to
     a printer row or column position less than the current PROW() and PCOL()
     values.

     .  If <nRow> is less than PROW(), an automatic EJECT (CHR(12)) is
        sent to the printer followed by the number of linefeed characters
        (CHR(10)) required to position the printhead on <nRow> on the
        following page.

     .  If <nCol> including the SET MARGIN value is less than PCOL(),
        a carriage return character (CHR(13)) and the number of spaces
        required to position <exp> at <nCol> are sent to the printer.

     To override this behavior and send control codes to the printer, or for
     any other reason, you can use SETPRC() to reset PROW() and PCOL() to new
     values.  See the SETPRC() function reference  for more information.

     If the current DEVICE is the PRINTER, redirect output from @...SAY
     commands to a file using the SET PRINTER TO <xcFile> command.

     @...SAY command output can be formatted using the PICTURE clause with a
     <cSayPicture>.  This performs the same action as the TRANSFORM()
     function.  A <cSayPicture> may consist of a function and/or a template.
     A PICTURE function imposes a rule on the entire @...SAY output.  A
     PICTURE template defines the length of the @...SAY output and the
     formatting rule for each position within the output.

     .  Function string: A PICTURE function string specifies
        formatting rules which apply to the SAY's entire display value,
        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
        table below).  The function string must not 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.

        SAY and TRANSFORM() PICTURE Format Functions
        ---------------------------------------------------------------------
        Function     Action
        ---------------------------------------------------------------------
        B            Displays numbers left-justified
        C            Displays CR after positive numbers
        D            Displays dates in SET DATE format
        E            Displays dates and numbers in British format
        R            Nontemplate characters are inserted
        X            Displays DB after negative numbers
        Z            Displays zeros as blanks
        (            Encloses negative numbers in parentheses
        !            Converts alphabetic characters to uppercase
        ---------------------------------------------------------------------

     .  Template string: A PICTURE template string specifies
        formatting rules on a character-by-character basis. The template
        string consists of a series of characters, some of which have special
        meanings (see table below).  Each position in the template string
        corresponds to a position in the displayed SAY value.  Characters in
        the template string which do not have assigned meanings are copied
        verbatim into the displayed SAY value.  If you use the @R picture
        function, characters without special PICTURE template string meaning
        are inserted between characters of the display value; otherwise, they
        overwrite the corresponding characters of the display value.  You may
        specify a template string alone or with a function string.  If both
        are present, the function string must precede the template string,
        and the two must be separated by a single space.

        SAY and TRANSFORM() Template Symbols
        ---------------------------------------------------------------------
        Template     Action
        ---------------------------------------------------------------------
        A,N,X,9,#    Displays digits for any data type
        L            Displays logicals as "T" or "F"
        Y            Displays logicals as "Y" or "N"
        !            Converts alphabetic characters to uppercase
        $            Display a dollar sign in place of a leading space in a
                     number
        *            Display an asterisk in place of a leading space in a
                     number
        .            Specifies a decimal point position
        ,            Specifies a comma position
        ---------------------------------------------------------------------

 Examples

     .  This example uses an @...SAY with a PICTURE clause to display
        formatted output:

        nNetIncome = 7125.50
        nNetLoss = -125.50
        cPhone = "2134567890"
        cName = "Kate Mystic"
        //
        @ 1, 1 SAY nNetIncome PICTURE "@E 9,999.99"
        // Result: .125,50

        @ 2, 1 SAY nNetLoss PICTURE "@)"
        // Result: (125.50)

        @ 3, 1 SAY cPhone PICTURE "@R (999)999-9999"
        // Result: (213)456-7890

        @ 4, 1 SAY cName PICTURE "@!"
        // Result: KATE MYSTIC

     .  This example is a small label printing program that uses SET
        DEVICE to direct output to the printer and SETPRC() to suppress
        automatic EJECTs:

        USE Salesman INDEX Salesman NEW
        SET DEVICE TO PRINTER
        DO WHILE !EOF()                  // Print all records
           @ 2, 5 SAY RTRIM(FirstName) + ", " + LastName
           @ 3, 5 SAY Street
           @ 4, 5 SAY RTRIM(City) + ", " + State + "  " + ;
                    PostalCode
           @ 6, 0 SAY SPACE(1)           // Move to label bottom
           SETPRC(0, 0)                  // Suppress page eject
           SKIP                          // Next record
        ENDDO
        SET DEVICE TO SCREEN
        CLOSE Salesman

 Files:  Library is CLIPPER.LIB.