PICTURE function / template

What is PICTURE function – template ?

@…SAY comand display data at a specified screen or printer row and column with syntax :

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

@…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 that 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
$ 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
---------------------------------------------------------------------

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: 7.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