FMT function

Syntax

FMT (expression, format)
expression format

Description

Use the FMT function or a format expression to format data for output. Any BASIC expression can be formatted for output by following it with a format expression.

expression evaluates to the numeric or string value to be formatted.

format is an expression that evaluates to a string of formatting codes. The syntax of the format expression is:

[width] [fill] justification [edit] [mask]

The format expression specifies the width of the output field, the placement of background or fill characters, line justification, editing specifications, and format masking.

If expression evaluates to the null value, null is returned. If format evaluates to null, the FMT function and the format operation fail.

width is an integer that specifies the size of the output field in which the value is to be justified. If you specify mask, you need not specify width. If you do not specify mask, width is required.

fill specifies the character to be used to pad entries when filling out the output field. fill is specified as a single character. The default fill character is a space. If you want to use a numeric character or the letter L, R, T, or Q as a fill character, you must enclose it in single quotation marks.

justification is required in one of the following forms.

Decimal notation:

L

Left justification - Break on field length.

R

Right justification - Break on field length.

T

Text justification - Left justify and break on space.

U

Left justification - Break on field length.

Exponential notation:

Q

Right justification - Break on field length.

QR

Right justification - Break on field length.

QL

Left justification

edit can be any of the following:

n[m]

Used with L, R, or T justification, n is the number of digits to display to the right of the decimal point, and m descales the value by m minus the current precision. Each can be a number from 0 through 9. You must specify n in order to specify m. If you do not specify m, m = 0 is assumed. If you do not specify n, n = m = 0 is assumed. Remember to account for the precision when you specify m. The default precision is 4.

If you specify 0 for n, the value is rounded to the nearest integer. If the formatted value has fewer decimal places than n, output is padded with zeros to the nth decimal place. If the formatted value has more decimal places than n, the value is rounded to the nth decimal place.

If you specify 0 for m, the value is descaled by the current precision (0 - current precision).

nEm

Used with Q, QR, or QL justification, n is the number of fractional digits, and m specifies the exponent. Each can be a number from 0 through 9.

n.m

Used with Q, QR, or QL justification, n is the number of digits preceding the decimal point, and m the number of fractional digits. Each can be a number from 0 through 9.

$

Prefixes a dollar sign to the value.

F

Prefixes a franc sign to the value.

,

Inserts commas after every thousand.

Z

Suppresses leading zeros. Returns an empty string if the value is 0. When used with the Q format, only the trailing fractional zeros are suppressed, and a 0 exponent is suppressed.

E

Surrounds negative numbers with angle brackets (< >).

C

Appends cr to negative numbers.

D

Appends db to positive numbers.

B

Appends db to negative numbers.

N

Suppresses a minus sign on negative numbers.

M

Appends a minus sign to negative numbers.

T

Truncates instead of rounding.

Y

In NLS mode, prefixes the yen/yuan character to the value, that is, the Unicode value 00A5. Returns a status code of 2 if you use Y with the MR or ML code. If NLS is disabled or if the Monetary category is not used, Y prefixes the byte value 0xA5.

mask lets literals be intermixed with numerics in the formatted output field. The mask can include any combination of literals and the following three special format mask characters:

#n

Data is displayed in a field of n fill characters. A blank is the default fill character. It is used if the format string does not specify a fill character after the width parameter.

%n

Data is displayed in a field of n zeros.

*n

Data is displayed in a field of n asterisks.

If you want to use numeric characters or any of the special characters as literals, you must escape the character with a backslash ( \ ).

A #, %, or * character followed by digits causes the background fill character to be repeated n times. Other characters followed by digits cause those characters to appear in the output data n times.

mask can be enclosed in parentheses ( ) for clarity. If mask contains parentheses, you must include the whole mask in another set of parentheses. For example:

((###) ###-####)

You must specify either width or mask in the FMT function. You can specify both in the same function. When you specify width, the string is formatted according to the following rules:

If string is smaller than width n, it is padded with fill characters.

If string is larger than width n, a text mark (CHAR(251)) is inserted every nth character and each field is padded with the fill character to width.

The STATUS function reflects the result of edit as follows

:

0

The edit code is successful.

1

The string expression is invalid.

2

The edit code is invalid.

See the STATUS function for more information.

REALITY Flavor

In REALITY flavor accounts, you can use conversion codes in format expressions.

Examples

Format Expression

Formatted Value

Z=FMT("236986","R##-##-##")

Z=       23-69-86

X="555666898" X=FMT(X,"20*R2$,")

X=       *****$555,666,898.00

Y="DAVID" Y=FMT(Y,"10.L")

Y=       DAVID.....

V="24500" V=FMT(V,"10R2$Z")

V=        $24500.00

R=FMT(77777,"R#10")

R=            77777

B="0.12345678E1" B=FMT(B,"9*Q")

B=       *1.2346E0

PRINT 233779 "R"

233779

PRINT 233779 "R0"

233779

PRINT 233779 "R00"

2337790000

PRINT 233779 "R2"

233779.00

PRINT 233779 "R20"

2337790000.00

PRINT 233779 "R24"

233779.00

PRINT 233779 "R26"

2337.79

PRINT 2337.79 "R"

2337.79

PRINT 2337.79 "R0"

2338

PRINT 2337.79 "R00"

23377900

PRINT 2337.79 "R2"

2337.79

PRINT 2337.79 "R20"

23377900.00

PRINT 2337.79 "R24"

2337.79

PRINT 2337.79 "R26"

23.38