ML and MR Codes - Mask Decimal with Alignment

Overview

The ML and MR codes format numbers. ML aligns the result to the left; MR, to the right. The codes provide the following capabilities:

Decimal precision and scaling
Zero suppress
Thousands separator
Credit codes
Currency symbol
Inclusion of literal character strings

Input Conversion

Input conversion carries out a correct inversion with a number that has only thousands separators and a decimal point.

Syntax

[ML||MR]{precision{scaling}}{Z}{,}{creditIndicator}{$}{formatMask}

Syntax Elements

ML Specifies left alignment.

MR Specifies right alignment.

precision Defines the decimal precision.

scaling Defines scaling and rounding.

Z Suppress leading zeros.

, Use thousands separators.

creditIndicator Use the credit indicator.

$ Use the currency symbol.

formatMask A format mask.

Alignment

The processor applies the alignment specified by the ML or MR code at a different stage from that specified by attribute 9 of the data definition item. First, the processor formats the data with symbols and filler characters and with left or right alignment as specified by the ML or MR code. Then it places this formatted data in an output field of blank spaces whose length is specified by the contents of attribute 10 of the definition item and whose alignment is specified by attribute 9 of that item.

Parentheses

In addition to having its own flexible literal specification, English handles literals enclosed in parentheses, as specified by the SMA standard. Therefore, if a site converts from another system to a Reality system, existing ML and MR codes need not be changed.

Decimal Precision and Scaling

The ML and MR codes allow you to specify the decimal precision of a number's output format. You can specify up to nine places.

The ML and MR codes also allow you to specify the scaling of a number. The scale factor follows the decimal precision in the parameters.

Syntax Elements

precision Defines the decimal precision. The number precision (0-9) specifies the number of digits to be output following the decimal point. The processor inserts trailing zeros or rounds if necessary (see the DataBasic ROUND function for details). If precision is omitted or 0 is specified, the processor does not output a decimal point.

You can change the decimal point symbol by executing the SET-DEC command.

scaling Defines scaling. The value is descaled (divided) by that power of 10. For example, if scaling = 2, the value is divided by 100; if scaling = 3, the value is divided by 1000, and so on.

If scaling is omitted, precision is used as the scaling factor.

Numeric Data

The precisionand scaling parameters can only be applied to numbers. Numeric data is defined as containing:

At least one numeric character (0-9).
An optional initial plus (+) or minus (-) sign.
A single, optional decimal point.
An optional initial currency character, as set using SET-MONEY.

If the data contains any other characters, the precisionand scaling parameters are ignored.

Notes:

Although real numbers (including decimal points) can be stored in Reality, it is recommended that you store numeric values as integers and scale them as required for display.
The ML and MR conversion codes normally treat a null value generated by the English conversion processor as a number and convert it to zero. If you set the INHIB.MLMR option in your operating environment, however, it will be treated as a string and remain null.
The definition of numeric data as it applies to the ML and MR conversion codes can be changed with the MD.ICONV.ALWAYS environment option.

In addition to any formatting specified, the following conversions are applied to numeric data:

Leading zeros (ignoring any sign character) are removed unless immediately preceding the decimal point. For example:

"0034.56" → "34.56"

"00.56" → "0.56"

"-00087" → "-87"
If the string contains a decimal point followed by one or more digits, but there are no digits before the decimal point, a zero character is inserted before the decimal point. For example:

"+.5" → "+0.5"
If there is a trailing decimal point, it is removed. For example:

"+5." → "+5"
If the only numeric characters are zeros, any leading + or - sign is removed. For example:

"-0.0" → "0.0"

Examples

The following examples illustrate the effect of the decimal precision and scaling parameters. All the examples use the ML code. The MR code would produce the same formatted data but right aligned.

Code	Stored Value	Formatted Data
ML	123456789	`123456789`
ML2	123456789	`1234567.89`
ML24	123456789	`12345.68`
ML05	123456789	`1235`
ML26	123456789	`123.46`

If you had invoked the SET-DEC command to specify the comma as the decimal point symbol, the output in the last example would be:

123,46

Suppressing Leading Zeros

The ML and MR codes allow you to suppress leading zeros of the displayed data. However, the processor always outputs a zero if that would be the only digit to precede the decimal point.

Syntax Elements

Z indicates suppress leading zeros. However, the output always includes a zero preceding the decimal point for values between 1 and -1.

Examples

The following examples illustrate zero suppression.

Code	Stored Value	Formatted Data
MRZ	0000
ML2Z	0001	`0.01`
MR2Z	0123	`1.23`

Specifying the Thousands Separator

The ML and MR codes allow you to include a thousands separator in the output. The syntax uses a comma to specify this feature, but you can use the SET-THOUS command to specify another symbol to be used in the display.

Syntax Elements

, is the thousands separator symbol. It specifies insertion of thousands separators every three digits to the left of the decimal point.

You can change the display separator symbol by executing the SET-THOUS command.

Examples

The following examples illustrate specifying thousands separator.

Code	Stored Value	Formatted Data
ML	123456789	`123456789`
ML,	123456789	`123,456,789`
MR,	123456789	`123,456,789`

If you had previously invoked the SET-THOUS command to specify the period as the thousands separator symbol, the output of the last example would be:

123.456.789

Specifying the Credit Indicator

The ML and MR codes allow you to specify a credit indicator to be included in the display. If you specify a credit indicator, the processor outputs either the credit characters or blank spaces depending on the value of the data.

Syntax Elements

creditIndicator is the credit indicator. It appends or encloses the value with appropriate credit characters:

COutput the literal CR after negative values.

DOutput the literal DB after positive values.

EEnclose negative values in angle brackets <>.

MOutput negative values with a trailing minus sign.

NSuppress minus sign for negative values.

If a value is negative and you have not specified one of these indicators, the processor displays the value with a leading minus sign.

Examples

These examples illustrate the use of various indicators for displaying negative numbers. The examples all use the MR code, but the ML code produces the same formatted data.

Code	Stored Value	Formatted Data
MR	12345678	`12345678`
MR	-12345678	`-12345678`
MRC	12345678	`12345678`
MRC	-12345678	`12345678CR`
MRD	12345678	`12345678DB`
MRD	-12345678	`12345678`
MRE	12345678	`12345678`
MRE	-12345678	`<123454678>`
MRM	12345678	`12345678`
MRM	-12345678	`12345678-`
MRN	12345678	`12345678`
MRN	-12345678	`12345678`

Specifying a Currency Symbol

The ML and MR codes allow you to specify a currency symbol in the display. The syntax uses the dollar sign ($) to specify this feature, but you can specify another display symbol by using the SET-MONEY command.

Syntax Elements

$ indicates that a currency symbol is to be included. The processor adds a floating currency symbol in front of the value.

You can change the display currency symbol by executing the SET-MONEY command.

Examples

These examples illustrate how to specify that a currency symbol be included in the display.

Code	Stored Value	Formatted Data
MR$	12345678	`$12345678`
ML$	-12345678	`$-12345678`

If you had invoked the SET-MONEY command to specify D as the currency symbol, the last example would be:

D-12345678

Specifying a Format Mask

The ML and MR codes allow you to specify a format mask.

Syntax Elements

formatMask is a format mask with the following format:

{&char}{(}mask{)}

where:

&charSpecifies a fill character to be used instead of blanks, asterisks or zeros. char can be any literal character.

maskThe required format. This can be any combination of literal and fill characters. The formatted value overwrites the fill characters as necessary.

#{count} Blank.

*{count} Asterisk.

%{count} Zero.

Where countspecifies the number of fill characters (default, 1).

Notes

At least one fill character must be included.
Only one of the above can be used as a fill character in a format mask. Once a fill character has been used, it can be repeated as required, but the other fill characters will be treated as literals.

If there is no opening parenthesis, a trailing close parenthesis is treated as part of the mask.

Description

The easiest way to understand how the processor handles literals and format codes is by example. Say that we have four different data definitions, all pointing at the same data value:

123456

Parts of data definition items:

LL	RR
008: ML2,$&BAL10 009: L 010: 15	008: MR2,$&BAL10 009: R 010: 15
LR	RL
008: ML2,$&BAL10 009: R 010: 15	008: MR2,$&BAL10 009: L 010: 15

All four definitions are alike except that:

LL and LR have ML on line 8; RR and RL have MR.
LL and RL have L on line 9; RR and LR have R.

When the processor handles an ML or MR code, it formats the data using all the parameters specified before the start of the format mask.

The processor would format the data the same way for all these attributes. Each would produce this formatted data:

$1,234.56

The processor then formats the literal and the filler fields, and each of these attributes would produce the following formatted literal field:

BAL**********

The processor then moves the formatted data into the filler field of the formatted literal. The ML code processor moves from the left end of the data to the left end of the filler field; the MR code processor moves from the right to the right. The results are:

Attributes LL and LR	Attributes RR and RL
BAL$1,234.56*	BAL*$1,234.56

The processor then moves each filled-in, formatted literal to the display field, aligning it left or right depending on whether there is an L or an R on line 9 of the data definition item. The results for these attributes would be:

Attribute LL	Attribute LR	Attribute RR	Attribute RL
BAL$1,23456*	BAL$1,23456*	BAL*$1,23456	BAL*$1,23456

Examples

Creating Fields for Alignment

In the following examples fields are created so that the values are aligned.

Code	Stored Value	Alignment	Output Field (Column Width = 15)
			`123456789012345`
MR2#10	1234	L	`12.34`
MR2#10	1234	R	`12.34`
ML2%10	1234	L	`12.3400000`
MR2%10	1234	R	`0000012.34`
ML2*10	1234	L	`12.34*****`
ML2*10	1234	R	`12.34*****`

Note that the result in each example is effectively done in two steps:

The ML or MR code formats and positions the data in a field of specified length (10 in all these examples) filled with a specified character.
That field is positioned in the output field either left-aligned or right-aligned in a field 15 columns wide. The alignment and output field width are specified in attributes 9 and 10, respectively, of the data definition item.

Format Option

The following examples illustrate the alignment of the currency symbol through the use of the &x format option:

Code	Stored Value	Output Field (Left-aligned; Column Width = 20)
		`12345678901234567890`
MR2,$#15	12345678	`$123,456.78`
MR2,&$#15	12345678	`$$$$$123,456.78`
ML2,$*15	12345678	`$123,456.78*****`
MR2,$#15	12345678	`$ 123,456.78`
MR2,C$*15	-12345678	`$***123,456.78CR`

Note that the character immediately following the ampersand (&) fills the columns without data as specified by #n.

Inserting Literal Characters

The following examples illustrate the use of literals. Note that fields of blanks interspersed with literal characters are specified. The stored value is inserted into the blank fields.

Code	Stored Value	Output
ML###-##-####	123456789	`123-45-6789`
ML#3-#2-#4	123456789	`123-45-6789`

Inserting Phrases

The last examples illustrate the insertion of literal phrases for output:

Code	Stored Value	Output
MLSocial Security No. #3-#2-#4	123456789	Social Security No. 123-45-6789
MLTEL: (#3) #3-#4 Ext: #2	123456789012	TEL: (123) 456-7890 Ext: 12
ML((#3) #3-#4 Ext: #2	123456789012	(123) 456-7890 Ext: 12

Note that in the last example double opening parentheses are used. The system ignores a single opening parenthesis immediately following the ML in order to accommodate the ML and MR syntax that may be transferred from other MultiValue systems.

To	Reality
Version
Topic
Submitted by
Company
Location
Email address
Comment