Previous Page | Next Page

The FORMAT Procedure

PICTURE Statement

Creates a template for printing numbers.
See also: The section on formats in SAS Language Reference: Dictionary for documentation about formats that are supplied by SAS.
Featured in:
PICTURE name <(format-option(s))>
<value-range-set-1 <(picture-1-option(s) )>
<...value-range-set-n <(picture-n-option(s))>>>;

Task Option
Control the attributes of the format.

Specify that you can use directives in the picture as a template to format date, time, or datetime values. DATATYPE=

Specify the default length of the format. DEFAULT=

Specify the separator character for the fractional part of a number. DECSEP=

Specify the three-digit separator character for a number. DIG3SEP=

Specify a fuzz factor for matching values to a range. FUZZ=

Specify the language that is used for the days of the week and months of the year that you can substitute in a date, time, or datetime specification. LANGUAGE=

Specify a maximum length for the format. MAX=

Specify a minimum length for the format. MIN=

Specify multiple pictures for a given value or range and for overlapping ranges. MULTILABEL

Store values or ranges in the order that you define them. NOTSORTED

Round the value to the nearest integer before formatting. ROUND
Control the attributes of each picture in the format.

Specify a character that completes the formatted value. FILL=

Specify a number to multiply the variable's value by before it is formatted. MULTIPLIER=

Specify that numbers are message characters rather than digit selectors. NOEDIT

Specify a character prefix for the formatted value. PREFIX=

Required Arguments

name

names the format you are creating.

Requirement: The name must be a valid SAS name. A numeric format name can be up to 32 characters in length; a character format name can be up to 31 characters in length, not ending in a number. If you are creating a character format, you use a dollar sign ($) as the first character, which is why a character informat is limited to 31 characters.
Restriction: A user-defined format cannot be the name of a format supplied by SAS.
Interaction: The maximum length of a format name is controlled by the VALIDFMTNAME= SAS system option. See SAS Language Reference: Dictionary for details on VALIDFMTNAME=.
Tip: Refer to the format later by using the name followed by a period. However, do not put a period after the format name in the VALUE statement.
Options

The following options are common to the INVALUE, PICTURE, and VALUE statements and are described in Informat and Format Options:

DEFAULT= length

FUZZ=fuzz-factor

MAX=length

MIN=length

NOTSORTED

In addition, you can use the following arguments:

DATATYPE=DATE | TIME | DATETIME

specifies that you can use directives in the picture as a template to format date, time, or datetime values. See the definition and list of directives.

Tip: If you format a numeric missing value, then the resulting label will be ERROR. Adding a clause to your program that checks for missing values can eliminate the ERROR label.
DECSEP='character'

specifies the separator character for the fractional part of a number.

Default: . (a decimal point)
DIG3SEP='character'

specifies the three-digit separator character for a number.

Default: , (a comma)
FILL='character'

specifies a character that completes the formatted value. If the number of significant digits is less than the length of the format, then the format must complete, or fill, the formatted value:

  • The format uses character to fill the formatted value if you specify zeros as digit selectors.

  • The format uses zeros to fill the formatted value if you specify nonzero digit selectors. The FILL= option has no effect.

If the picture includes other characters, such as a comma, which appear to the left of the digit selector that maps to the last significant digit placed, then the characters are replaced by the fill character or leading zeros.

Default: ' ' (a blank)
Interaction: If you use the FILL= and PREFIX= options in the same picture, then the format places the prefix and then the fill characters.
Featured in: Filling a Picture Format

LANGUAGE=

specifies the language that is used for the days of the week and months of the year that can be substituted in a date, time, or datetime specification.

Default: English
MULTILABEL

allows the assignment of multiple labels or external values to internal values. The following PICTURE statements show the two uses of the MULTILABEL option. In each case, number formats are assigned as labels. The first PICTURE statement assigns multiple labels to a single internal value. Multiple labels can also be assigned to a single range of internal values. The second PICTURE statement assigns labels to overlapping ranges of internal values. The MULTILABEL option allows the assignment of multiple labels to the overlapped internal values. 

picture abc (multilabel)
   1000='9,999'
   1000='9999';

picture overlap (multilabel)
   /* without decimals */
   0-999='999'
   1000-9999='9,999'
   
   /* with decimals */
   0-9='9.999'
   10-99='99.99'
   100-999='999.9';
Only multilabel-enabled procedures such as PROC MEANS, PROC SUMMARY, and PROC TABULATE can use multiple labels. All other procedures and the DATA step recognize only the primary label. The primary label for a given entry is the external value that is assigned to the first internal value or range of internal values that matches or contains the entry when all internal values are ordered sequentially. For example, in the first PICTURE statement, the primary label for 1000 is 1,000 because the format 9,999 is the first external value that is assigned to 1000. The secondary label for 1000 is 1000, based on the 9999 format.

In the second PICTURE statement, the primary label for 5 is 5.000 based on the 9.999 format that is assigned to the range 0-9 because 0-9 is sequentially the first range of internal values containing 5. The secondary label for 5 is 005 because the range 0-999 occurs in sequence after the range 0-9. Consider carefully when you assign multiple labels to an internal value. Unless you use the NOTSORTED option when you assign variables, SAS stores the variables in sorted order. This order can produce unexpected results when variables with the MULTILABEL format are processed. For example, in the second PICTURE statement, the primary label for 15 is 015, and the secondary label for 15 is 15.00 because the range 0-999 occurs in sequence before the range 10-99. If you want the primary label for 15 to use the 99.99 format, then you might want to change the range 10-99 to 0-99 in the PICTURE statement. The range 0-99 occurs in sequence before the range 0-999 and will produce the desired result.

MULTIPLIER=n

specifies a number that the variable's value is to be multiplied by before it is formatted. The value of the MULTIPLIER= option depends both on the result of the multiplication and on the digit selectors in the label portion of the format. For example, the following PICTURE statement creates the MILLION. format, which formats the variable value 1600000 as $1.6M : 

picture million low-high='09.9M' 
       (prefix='$' mult=.00001);

Note that there is a digit selector after the decimal. The value 16 is placed into the "template" beginning on the right. The value 16 overlays 09.9, and results in 01.6. Leading zeroes are dropped, and the final result is 1.6M.

If the value of low-high is equal to '000M', then the result would be 16M.

Alias: MULT=
Default: 10n , where n is the number of digits after the first decimal point in the picture. For example, suppose your data contains a value 123.456 and you want to print it using a picture of '999.999'. The format multiplies 123.456 by 103 to obtain a value of 123456, which results in a formatted value of 123.456.
Featured in: Creating a Picture Format
NOEDIT

specifies that numbers are message characters rather than digit selectors; that is, the format prints the numbers as they appear in the picture. For example, the following PICTURE statement creates the MILES. format, which formats any variable value greater than 1000 as >1000 miles: 

picture miles 1-1000='0000'
          1000<-high='>1000 miles'(noedit);
PREFIX='prefix'

specifies a character prefix to place in front of the value's first significant digit. You must use zero digit selectors or the prefix will not be used.

The picture must be wide enough to contain both the value and the prefix. If the picture is not wide enough to contain both the value and the prefix, then the format truncates or omits the prefix. Typical uses for PREFIX= are printing leading currency symbols and minus signs. For example, the PAY. format prints the variable value 25500 as $25,500.00: 

picture pay low-high='000,009.99'
                     (prefix='$');
Default: no prefix
Interaction: If you use the FILL= and PREFIX= options in the same picture, then the format places the prefix and then the fill characters.
Featured in:
ROUND

rounds the value to the nearest integer before formatting. Without the ROUND option, the format multiplies the variable value by the multiplier, truncates the decimal portion (if any), and prints the result according to the template that you define. With the ROUND option, the format multiplies the variable value by the multiplier, rounds that result to the nearest integer, and then formats the value according to the template. Note that if the FUZZ= option is also specified, the rounding takes place after SAS has used the fuzz factor to determine which range the value belongs to.

Tip: Note that the ROUND option rounds a value of .5 to the next highest integer.
value-range-set

specifies one or more variable values and a template for printing those values. The value-range-set is the following:

value-or-range-1 <..., value-or-range-n>='picture'

picture

specifies a template for formatting values of numeric variables. The picture is a sequence of characters in single quotation marks. The maximum length for a picture is 40 characters. Pictures are specified with three types of characters: digit selectors, message characters, and directives. You can have a maximum of 16 digit selectors in a picture.

Digit selectors are numeric characters (0 through 9) that define positions for numeric values. A picture format with nonzero digit selectors prints any leading zeros in variable values; picture digit selectors of 0 do not print leading zeros in variable values. If the picture format contains digit selectors, then a digit selector must be the first character in the picture.

Note:   This section uses 9's as nonzero digit selectors.  [cautionend]

Message characters are nonnumeric characters that print as specified in the picture. The following PICTURE statement contains both digit selectors (99) and message characters (illegal day value). Because the DAYS. format has nonzero digit selectors, values are printed with leading zeros. The special range OTHER prints the message characters for any values that do not fall into the specified range (1 through 31). 

picture days 01-31='99'
        other='99-illegal day value';

For example, the values 02 and 67 print as 

                             02
           67-illegal day value

Directives are special characters that you can use in the picture to format date, time, or datetime values.

Restriction: You can use only directives when you specify the DATATYPE= option in the PICTURE statement.

The permitted directives are as follows:

%a

abbreviated weekday name, for example, Wed.

%A

full weekday name, for example, Wednesday.

%b

abbreviated month name, for example, Jan.

%B

full month name, for example, January.

%C

long month name with blank padding (January through December), for example, December.

%d

day of the month as a two-digit decimal number (01-31), for example, 02.

%e

day of the month as a two-character decimal number with leading spaces (" 1"- "31"), for example, " 2".

%F

full weekday name with blank padding.

%g

year as a two-digit decimal number (00 - 99), for example, 02. If the week that contains January 1 has four or more days in the new year, then it is considered week 1 in the new year. Otherwise, it is the last week of the previous year and the year is considered the previouse year.

%G

year as a four-digit decimal number, for example, 2008. If the week that contains January 1 has four or more days in the new year, then it is considered week 1 in the new year. Otherwise, it is the last week of the previous year and the year is considered the previouse year.

%H

hour (24-hour clock) as a two-digit decimal number (00-23), for example, 19.

%I

hour (12-hour clock) as a two-digit decimal number (01-12), for example, 05.

%j

day of the year as a decimal number (1-366), with leading zero.

%m

month as a two-digit decimal number (01-12), for example, 01.

%M

minute as a two-digit decimal number (00-59), for example, 45.

%o

month (1-12) with blank padding, for example, " 2".

%p

equivalent to either a.m. or p.m.

%q

abbreviated quarter of the year string such as Qtr1, Qtr2, Qtr3, or Qtr4.

%Q

quarter of the year string, such as Quarter1, Quarter2, Quarter3, or Quarter4.

%S

second as a two-digit decimal number (00-61) and allowing for possible leap seconds, for example, 58.

%u

weekday as a one-digit decimal number (1-7 (Monday - Sunday)), for example, Sunday=7.

%U

week number of the year as a decimal number (0,53) with leading 0. Sunday is considered the first day of the week.

%V

week number (01-53) with the first Monday as the start day of the first week. Minimum days of the first week is 4.

%w

weekday as a one-digit decimal number (0-6 (Sunday through Saturday)), for example Sunday=0.

%W

week number (00-53) with the first Monday as the start day of the first week.

%y

year without century as a two-digit decimal number (00-99), for example, 93.

%Y

year with century as a four-digit decimal number (1970-2069), for example, 1994.

%%

the % character.

Any directive that generates numbers can produce a leading zero, if desired, by adding a 0 before the directive. Adding a leading zero applies to %d, %H, %I, %j, %m, %M, %S, %U, and %y. For example, if you specify %y in the picture, then 2001 would be formatted as '1', but if you specify %0y, then 2001 would be formatted as '01'.

Tip: Add code to your program to direct how you want missing values to be displayed.
value-or-range

See Specifying Values or Ranges.

Building a Picture Format: Step by Step

This section shows how to write a picture format for formatting numbers with leading zeros. In the SAMPLE data set, the default printing of the variable Amount has leading zeros on numbers between 1 and -1:

options nodate pageno=1 linesize=64 pagesize=60;

data sample;
   input Amount;
   datalines;
-2.051
-.05
-.017
  0
 .093
 .54
 .556
6.6
14.63
;

proc print data=sample;
   title 'Default Printing of the Variable Amount';
run;

            Default Printing of the Variable Amount            1

                         Obs     Amount

                          1      -2.051
                          2      -0.050
                          3      -0.017
                          4       0.000
                          5       0.093
                          6       0.540
                          7       0.556
                          8       6.600
                          9      14.630

The following PROC FORMAT step uses the ROUND format option and creates the NOZEROS. format, which eliminates leading zeros in the formatted values: 

libname library 'SAS-library';

proc format library=library;
   picture nozeros (round)
           low -  -1  =  '00.00' 
              (prefix='-')
           -1 <-<  0  =     '99' 
              (prefix='-.' mult=100)
            0  -< 1   =     '99'
              (prefix='.'  mult=100)
            1  - high =  '00.00';
run;

The following table explains how one value from each range is formatted. Formatting One Value in Each Range provides an illustration of each step. The circled numbers in the figure correspond to the step numbers in the table.

Building a Picture Format
Step Rule In this example
1 Determine into which range the value falls and use that picture. In the second range, the exclusion operator < appears on both sides of the hyphen and excludes -1 and 0 from the range.
2 Take the absolute value of the numeric value. Because the absolute value is used, you need a separate range and picture for the negative numbers in order to prefix the minus sign.
3 Multiply the number by the MULT= value. If you do not specify the MULT= option, then the PICTURE statement uses the default. The default is 10n , where n is the number of digit selectors to the right of the decimal (table note 1) in the picture. (Step 6 discusses digit selectors further.) Specifying a MULT= value is necessary for numbers between 0 and 1 and numbers between 0 and -1 because no decimal appears in the pictures for those ranges. Because MULT= defaults to 1, truncation of the significant digits results without a MULT= value specified. (Truncation is explained in the next step.) For the two ranges that do not have MULT= values specified, the MULT= value defaults to 100 because the corresponding picture has two digit selectors to the right of the decimal. After the MULT= value is applied, all significant digits are moved to the left of the decimal.
4 Add a fuzz factor of 10e-8 to the number. If the ROUND option is not in effect, truncate the number after the decimal. If the ROUND option is in effect, then the format rounds the number after the decimal to the next highest integer if the number after the decimal is greater than or equal to .5.

Note: The fuzzing factor is not related to the FUZZ= option. The FUZZ= option is used in matching ranges to values.

 Because the example uses MULT= values that ensured that all of the significant digits were moved to the left of the decimal, no significant digits are lost. The zeros are truncated.
5 Turn the number into a character string. If the number is shorter than the picture, then the length of the character string is equal to the number of digit selectors in the picture. Pad the character string with leading zeros. (The results are equivalent to using the Zw. format. Zw. is explained in the section on SAS formats in SAS Language Reference: Dictionary. The numbers 205, 5, and 660 become the character strings 0205, 05, and 0660, respectively. Because each picture is longer than the numbers, the format adds a leading zero to each value. The format does not add leading zeros to the number 55 because the corresponding picture only has two digit selectors.
6 Apply the character string to the picture. The format only maps the rightmost n characters in the character string, where n is the number of digit selectors in the picture. Thus, it is important to make sure that the picture has enough digit selectors to accommodate the characters in the string. After the format takes the rightmost n characters, it then maps those characters to the picture from left to right. Choosing a zero or nonzero digit selector is important if the character string contains leading zeros. If one of the leading zeros in the character string maps to a nonzero digit selector, then it and all subsequent leading zeros become part of the formatted value. If all of the leading zeros map to zero digit selectors, then none of the leading zeros become part of the formatted value; the format replaces the leading zeros in the character string with blanks. (table note 2) The leading zero is dropped from each of the character strings 0205 and 0660 because the leading zero maps to a zero digit selector in the picture.
7 Prefix any characters that are specified in the PREFIX= option. You need the PREFIX= option because when a picture contains any digit selectors, the picture must begin with a digit selector. Thus, you cannot begin your picture with a decimal point, minus sign, or any other character that is not a digit selector. The PREFIX= option reclaims the decimal point and the negative sign, as shown with the formatted values -.05 and .55.

TABLE NOTE 1:  A decimal in a PREFIX= option is not part of the picture. [arrow]

TABLE NOTE 2:  You can use the FILL= option to specify a character other than a blank to become part of the formatted value. [arrow]

Formatting One Value in Each Range

[Formatting One Value in Each Range]

The following PROC PRINT step associates the NOZEROS. format with the AMOUNT variable in SAMPLE. The output shows the result of rounding. 

proc print data=sample noobs;
   format amount nozeros.;
   title 'Formatting the Variable Amount'; 
   title2 'with the NOZEROS. Format';
run;

                 Formatting the Variable Amount                1
                    with the NOZEROS. Format

                             Amount

                             -2.05 
                              -.05 
                              -.02 
                               .00 
                               .09 
                               .54 
                               .56 
                              6.60 
                             14.63
CAUTION:
The picture must be wide enough for the prefix and the numbers.

In this example, if the value -45.00 were formatted with NOZEROS. then the result would be 45.00 because it falls into the first range, low - -1, and the picture for that range is not wide enough to accommodate the prefixed minus sign and the number.  [cautionend]

Specifying No Picture

This PICTURE statement creates a picture-name format that has no picture: 

picture picture-name;

Using this format has the effect of applying the default SAS format to the values.

Previous Page | Next Page | Top of Page

Copyright © 2010 by SAS Institute Inc., Cary, NC, USA. All rights reserved.