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.

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


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).


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.

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.


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