FMT Function

The FMT function produces the given data filtered through a specified format mask.

Format

expr mask-expr

FMT(expr, mask-expr)

Parameter(s)

expr	An expression evaluating to the text to be masked.
mask-expr	An expression evaluating to the format mask to be used. The mask-expr may have a maximum length of 256 characters. The syntax for mask-expr is described below.

Description

The FMT function, or format mask, returns the given data in the specified format. It is particularly useful for generating output in a human-readable form.

There are two ways to produce masked data: by using the FMT keyword, or by simply specifying the format mask directly after the data. In mvBASIC, if one expression immediately follows another, the second expression is automatically taken as a format mask for the first.

The format mask interprets the given expression as straight numeric data or as the internal format for a date. For an internal date, a D should be entered as the first character in the format mask, and the next two characters determine the number of characters to be taken as the suffix for the year and the character to be used as a delimiter. See Internal Date Conversion for more information on using format masks to convert an internal date into external format.

For straight numeric data, the format mask expression (mask-expr) is broken into these components:

[numeric-mask] [[(] field-mask [)]]

The numeric mask formats the data itself, and the field mask formats the field into which the result is placed. Although the parentheses around the field mask are optional, they are highly recommended in order to clearly delineate the field mask from the numeric mask.

Be aware that if a format mask does not match the syntax expected, or if the data expression does not evaluate to a numeric value, the results will be unpredictable and no error message is printed.

The format mask codes may be used within the masked input statement, INPUT@, to accept only data matching the specified code and store it in its raw form. See INPUT @ Statement for more information.

Numeric Masks

The numeric mask is a series of characters in this order:

j	Justification code, or D for internal date conversion. For data justification, one of:
	L	Left justification (default).
	R	Right justification.
	Justification codes are meant to be used in conjunction with the field masking codes, listed below. The justification codes have no effect unless the field masking codes are used to specify a field size and background character.
n	Decimal precision code. A single-digit number (0-9) to be taken as the number of decimal places to round to. If n is 0, a decimal point is not printed. If the descaling code (m) is specified, the decimal precision must be specified first.
m	Descaling code. A single-digit number (0-9) to be taken as the descaling factor. A descaling code equal to the current precision (4 by default) returns the number unchanged, and a descaling code equal to the current precision plus 1 returns the number divided by 10. In general, a descaling code equal to the current precision plus x returns the current number divided by 10x. If the descaling code is specified, the decimal precision (n) must be specified first.
Z	Converts all leading zeros to blanks. This has no effect on leading zeros generated by using the % character in a right-justified field mask code.
.	Inserts commas. Every three digits to the left of the decimal point are grouped together by commas, each comma representing a thousands position.
c	Credit indicator code. One of the following:
	C	Places CR after negative values and two blank spaces after all other values.
	D	Places DB after positive values and two blank spaces after all other values.
	E	Places negative values between angle brackets (<,>), and all other values between blank spaces.
	M	Places a minus sign after negative values.
	N	Suppresses the minus sign in negative values. If a decimal precision code (n) is not specified with a credit indicator code, a precision of 0 is assumed.
	$	Places a dollar sign at the beginning of the resulting data.

Field Masks

The field mask includes any of these codes:

$	Places a dollar sign at the beginning of the field.
a	Any character to be placed in the field as a filler.
#[n]	Places data in a field of n blanks. If n is not specified, the next character of the resulting data is returned.
*[n]	Places data in a field of n asterisks. If n is not specified, the next character of the resulting data is returned.
%[n]	Places data in a field of n zeros. For a right-justified field, this code forces leading zeros. If n is not specified, the next character of the resulting data is returned.

Although all specifications are optional, mvBASIC needs to make some assumptions about positioning of format codes. In particular, an initial alphabetic character is taken as a justification code, and an initial numeric character is taken as a decimal precision code. Thus, in order to specify either the zero suppression code (Z) or the credit indicator codes (C, D, E, M, N), either a justification code or a decimal precision code must be specified first. Similarly, in order to specify a descaling code, a decimal precision code must immediately precede it.

Internal Date Conversion

For internal date conversion, the format mask is assumed to be in the format:

Format

D [n] [c]

Parameter(s)

n	Is a single-digit number and c is any character. The number n determines how many digits to return from the end of the year, with all digits as the default (for example, -940 D produces 4 JUN 1965, and -940 D2 produces 4 JUN 65).
c	Determines the delimiter for the output fields, in which case the month, date and year are returned in their numeric values delimited by c (for example, -940 D/ produces 06/04/1965).

Example

Consider a program which reports the balances in a customer’s bank account. For accuracy, the current balance and balance at the beginning of the month are kept to 5 decimal places. Also, the date on which the account was last updated is kept in internal format.

BEGIN.BAL = ACCT.REC<7>

BALANCE = ACCT.REC<8>

LAST.UPDATE = ACCT.REC<10>

TODAY = DATE( )

ELAPSED = TODAY - LAST.UPDATE

PRINT "LAST UPDATE WAS " : ELAPSED : " DAYS AGO" :

PRINT " ON " : LAST.UPDATE "D2/"

PRINT "BALANCE AT START OF MONTH WAS"

BEGIN.BAL "2,$"

PRINT "CURRENT BALANCE IS " : BALANCE "2,$"

PRINT "WITH A CHANGE OF " : BALANCE-BEGIN.BAL

"2,$"

All dollar values are masked with the 2,$ code, specifying that:

Only two decimal points should be shown.
Commas should be placed at every thousands point.
A dollar sign should precede the number.

In addition, the internal date is masked with the D/ code, so that only the last two digits of the year are shown, and slashes / are used to delimit the fields.

If a file item from which ACCT.REC was read contains this data in Attributes 7 through 10:

007 78.22545

008 2943.56657

009

010 7674

then this prints on the screen:

LAST UPDATE WAS 14 DAYS AGO ON 01/03/89

BALANCE AT START OF MONTH WAS $78.23

CURRENT BALANCE IS $2,943.57

WITH A CHANGE OF $2865.34

Now consider the same program, but with the balances kept as integer values. In actual practice, all numbers on the mvBase system are stored as integers, so the file item from which ACCT.REC was read would actually read:

007 7822545

008 294356657

009

010 7674

To access the data correctly, the integer values need to be divided by 105. If the current precision is 4, the last five lines of code would read:

PRINT "LAST UPDATE WAS " : ELAPSED : " DAYS AGO " :

PRINT "ON " : LAST.UPDATE "D2/"

PRINT "BALANCE AT START OF MONTH WAS " : BEGIN.BAL "29,$"

PRINT "CURRENT BALANCE IS " : BALANCE "29,$"

PRINT "WITH A CHANGE OF " : BALANCE - BEGIN.BAL "29,$"

The only difference to note is that the mask code is now 29,$. If the precision is 4, the resulting data shows a decimal point 5 places from the right. This prints on the screen:

Last update on account was 14 days ago on 01/03/89

Balance at beginning of month was $78.23

Current balance is $2,943.57

With a change in balance of $2865.34

Note that the results are the same, as expected.

Now imagine that instead of printing out the account balances directly, we would like it tabulated onto the screen. Possible source code might read:

PRINT "BEGAN MONTH WITH" , "CURRENT BALANCE" ,

"INCREASE/DECREASE"

PRINT BEGIN.BAL "R29 , $(#16)" , "":

PRINT BALANCE "R29 , $(#15)", BALANCE - BEGIN.BAL, "R29 $(#17)"

In parentheses for each of the masking codes is #n, with n representing the maximum number of characters in the field, in this case the number of characters in the heading column. #n places the data in a field of n spaces. The R at the beginning of the masking code specifies right-justified data (so that if multiple accounts were reported, all decimal points would line up). With the same data as the previous example, the result might be:

BEGAN MONTH WITH	CURRENT BALANCE	INCREASE/DECREASE
$78.23	$2,943.57	$2,865.34