m (Mask) Processing Code

The m processing code is a masking conversion used for both numeric and text string formatting. This conversion is quite complex because nearly all of the elements available in its syntax are optional. The elements are listed in the order that the system evaluates the expression. If an element is going to be used, it must be in the same order shown. Each of the elements available is discussed below.

System Processors	Update, List
Code Type	Attribute Defining
Dictionary Attributes	Output Conversion

Syntax

m{l | r} {{precision} {scalefactor}} {z} {,} {signcode} {$} {format.mask}

NOTE	The spaces in the syntax listing are to provide visual relief. There are no spaces allowed in the conversion, except for literal spaces (those between quotation marks or with a parenthesized format mask).

Parameter(s)

l \| r	Indicates the justification of the string. Use l for left justification. Left justification is used primarily for text strings Use r or d for right justification. Right justification is typically used to process decimal numbers.
precision	Indicates the number of decimal positions to print after the decimal point. It must be between 0 and 9. When omitted, this defaults to 0. If 0 is assumed or specified, no decimal point is printed.
scalefactor	Indicates the power to which the value is to be descaled. It must be between 0 and 9. There is no default value. When a precision is specified without a scalefactor, the scalefactor defaults to the precision value. (mr2 is identical to mr22).
z	(literal) Suppresses leading zeros (that is, 0003 becomes 3) and thereby suppresses 0 balance fields.
,	Inserts commas in the thousands and millions position on output.
signcode	Alters the normal handling of negative numbers, with the exception of the d signcode. Their functions are:
	c	Negative values are followed by cr.
	d	Positive and zero values are followed by db.
	e	Negative values are enclosed in angle brackets; <value>. Zero values have a space preceding and following them.
	m	Negative numbers are followed by a minus sign.
	n	Suppresses (leading) minus sign on negative numbers.
$	Appends a dollar sign to the value prior to justification.
format.mask	Can be any combination of literals and special fill operators listed below. format.mask can itself be enclosed within parentheses. When it is enclosed in parentheses, any alphabetic characters (and all punctuation characters except #, %, and *) can be specified as literal strings.
	n	Justify data in a field of n spaces.
	*n	Justify data in a field of n asterisks (*).
	%n	Justify data in a field of n zeroes (0).
	xn	Justify data in a field of n characters, where x is the fill character. x can only be one of these three characters: # * %
	string	Any amount of nonformat mask characters may be specified in the string. It is printed exactly as specified in the format mask.

When masking decimal numbers, precision and scaling can be used to round numbers. For example, an internally stored number is 56789. This number has four implied decimals. The mask, mr4, indicates that both scalefactor and precision are 4. This returns a result of 5.6789.

The precision and scalefactor need not be the same. Consider the situation where this number is to be scaled by four places, but the result needs two decimals of precision. The conversion to accomplish this is, mr24. Passing 56789 through the conversion, mr24, first scales by 4 and then rounds to two decimals resulting in the decimal number, 5.68.

CAUTION

The functionality for mask and date conversions is not intuitive when combined with selection criteria in an AQL sentence. If a mask or date conversion exists in the output-conversion, that conversion is applied to the selection criteria in an AQL statement. For instance, in the sentence:

select filename with attr "90]"

where the data contains such values as 9000, 9010, 9020, and so on, the "90]" is converted by an mr2 to "9000]". The logic is to convert the selection criteria once, rather than converting each value that is processed by the select command. Moving the mr2 to the correlative attribute bypasses the conversion to the selection criteria.

Example(s)

This chart shows the effect of taking a data value and passing it through the oconv function:

Data	Conversion	Sample Output
12345	mr2	123.45
12345	mr02	123
123456	mr2,$	$1,234.56
123456	mr02,$	$1,235
0	mrz	(none)
0	mr2,z$	(none)
123456	mr2,e	1,234.56
123456	mr2,d	1,234.56db
-123456	mr2,e	<1,234.56>
-123456	mr2,c	1,234.56cr
-123456	mr2,m	1,234.56-
-123456	mr2,n	1,234.56
123456	mr24,	12.35
123456	mr02,$	$1,235
-123456	mr2,$	$-1,234.56
-123456	mr2,e$	<$1,234.56>
-123456	mr2,c$	$1,234.56cr
123456	mr2,c$	$1,234.56
123456	mr(%10)	0000123456
123456	mr2(%10)	0001234.56
123456	mr(*10)	****123456
123456	mr2(*10)	***1234.56
123456	mr2,$*12	***$1,234.56
7145551212	ml((###)###-####)	(714)555-1212
7145551212	ml(###-###-####)	714-555-1212
7145551212	ml(#3-#3-#4)	714-555-1212
123456	mr2$(#10)	$ 1234.56
123456	mr2($#10)	$1234.56
123456	mr(#3 plus #3)	123 plus 456
123456	mr24	12.35