xHarbour Reference Documentation > Command Reference

@...SAY

Displays data at a particular row and column position.

Syntax

@ <nRow>, <nCol> ;
      SAY <expression> ;
 [PICTURE <cPicture>] ;
   [COLOR <cColor>]

Arguments

@ <nRow>, <nCol>

The parameters are numeric values specifying the row and column coordinates for the output. The range for rows on the screen is 0 to MaxRow(), and for columns it is 0 to MaxCol(). The coordinate 0,0 is the upper left corner of the screen.

When SET DEVICE TO PRINTER is active, the largest coordinate for both, row and column, is 32766.

SAY <expression>

This is an expression whose value is output to the current device.

PICTURE <cPicture>

The PICTURE clause defines a character string which specifies how to format the value of <expression> for output. See the explanation of formatting rules below.

COLOR <cColor>

The parameter <cColor> is an optional character string defining the color for output. It defaults to the current SetColor() setting. When <cColor> is specified as a literal color string, it must be enclosed in quotes.

Description

@...SAY is a text-mode output command that outputs the value of an expression to the current device, which is either the screen or a printer. Only values of simple data types like Character, Date, Numeric and Logic are output. Complex values, like Array or Object cannot be used with @...SAY.

The output device for @...SAY is selected with the SET DEVICE command. The SET CONSOLE setting has no effect. When the SCREEN is the output device, @...SAY outputs the value of <expression> at the specified row and column position and moves the screen cursor to the end of the displayed value. Row() and Col() reflect the new position of the cursor.

With printed output, the printhead position is changed and PRow() and PCol() are updated accordingly. When the row coordinate for printed output is smaller than the current value of PRow(), an EJECT command is automatically sent to the printer. If the column coordinate including SET MARGIN is smaller than the current value of PCol(), a "new line" command is sent to the printer along with the number of spaces to position the printhead to the new column. To redirect the @...SAY output to a file, SET DEVICE TO PRINTER and SET PRINTER TO <fileName>.

The output color can be specified with a color string compliant with the SetColor() function. The default color used is the standard color, which is the first color value of a color string.

Output can be formatted using the PICTURE clause. It specifies a character string that may consist of two parts: a picture function and a picture mask. A picture function begins with the @ sign, followed by one or more letters indicating a picture function to apply. A picture mask is a series of characters. When both, picture function and mask, are used in the picture string, they must be separated with a single space character and the picture function must be placed first in the picture string.

Picture function

A picture function specifies formatting rules for the entire output string. It must begin with the @ sign followed by one or more letters listed in the table below:

Picture function characters

Function	Formatting rule
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
L	Displays numbers with leading zeros instead of blank spaces
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

Picture mask

The picture mask must be separated by a single space from the picture function. When no picture function is used, the picture string is identical with the picture mask. The mask defines formatting rules for individual characters in the output string. Characters from the following table can be used. The position of a character of a picture mask specifies formatting for the character of the output string at the same position. An exception is the @R function which causes non-mask characters being inserted into the output string.

Picture mask characters

Character	Formatting rule
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
$	Displays a dollar sign in place of a leading space in a number
*	Displays an asterisk in place of a leading space in a number
.	Specifies a decimal point position
,	Specifies a comma position

Info

See also:	? | ??, @...CLEAR, @...GET, Col(), GetNew(), PCol(), PRow(), QOut() | QQOut(), Row(), SetColor(), Transform()
Category:	Output commands
Source:	rtl\console.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates different formatting with @...SAY and
// the PICTURE clause

   PROCEDURE Main
      LOCAL nGain  := 8596.58
      LOCAL nLoss  := -256.50
      LOCAL cPhone := "5558978532"
      LOCAL cName  := "Jon Doe"

      @ 10, 1 SAY nGain PICTURE "@E 9,999.99"
      // result: 8.596,58

      @ 11, 1 SAY nLoss PICTURE "@)"
      // Result: (256.50)

      @ 12, 1 SAY cPhone PICTURE "@R (999)999-9999"
      // Result: (555)897-8532

      @ 13, 1 SAY cName PICTURE "@!"
      // Result: JOHN DOE
   RETURN