basic.masking.function Definition/BASIC Program

basic.masking.function

Command basic.masking.function Definition/BASIC Program
Applicable release versions: AP, R83
Category BASIC Program (486)
Description formatting expressions using numeric masks and format masks.

Where the mask expression is:

{r|l|d{n}{s}{z}{,}{c}{$}({{{f},l}...})

Where:

r|l|d (r)ight or (l)eft justified. The default is left. The "d" specifier functions identically to the "r" and is provided for compatibility reasons only.

n Number of digits after decimal. This is a single numeric digit that specifies the number of digits to print following the decimal point. If "n" = 0, the decimal point is not output. If the number of digits following the decimal point is greater than the number specified by "n", the output is rounded.

s Scaling factor. This is a single numeric digit that specifies to 'descale' the value by the 's - precision' power of 10. For example, an "s" value of 2 changes 1000 to 10.

z (A literal "z"). Suppresses leading zeros.

, Inserts commas between every "thousands" position of the value.

$ Appends dollar sign to beginning of value.

f "fill" character
l length
c signcode:

c Outputs "CR" after negative values. Two blanks follow positive or zero values.

d Outputs "DB" after positive values. Two blanks follow negative or zero values.

e Encloses negative values within a "<" and ">". A blank follows positive or zero values.

m Places a minus sign to the right of negative values. A blank follows positive or zero values. Ordinarily, the minus sign appears to the left of negative numbers.

n Suppresses the minus sign on negative values.

Special fill characters:

%n fills with "n" zeros.
#n fills with "n" blanks.
*n fills with "n" asterisks.

Any other character, including parentheses, may be included in the fill mask. The characters are output exactly as they appear in the mask. If a dollar sign is placed outside of the format mask, it is output just prior to the value, regardless of the filled field. If a dollar sign is used within the format mask, it is output in the leftmost position regardless of the filled field. Parentheses are ignored if they are the first character of a mask.

The numeric mask code controls justification, precision, scaling, and credit indication.

The format mask code controls field length and fill characters. The entire format string is enclosed in quotation marks. If a format mask is used, it should be enclosed in parentheses within the quotation marks.

The entire format string may be used as a literal, or it may be assigned to a variable. A format string literal can immediately follow the string it is to format. A format string variable must be separated by at least one space from the string it is to format. The format string may also be used directly in conjunction with the print statement.

The following mask codes must be entered in the order they are listed.

Mask Description

d{ } If specified before any other mask, this specifies standard date conversions, and any other mask code is ignored.

c If specified before any other mask, the various "character" masks may be specified (like "cu" or "cl"), just like the oconv(string,"mcu").
Syntax string.expression mask.expression
Options
Example
print x "l(#12)"

This value in "x" is left justified, in a field of 12 characters.  If 
the value of "x" is the word "test", the output looks as 
follows: (spaces are represented by lower case "b")

testbbbbbbbb

print y "r(#15)"

"y" is printed right justified, fill space, in a field of 15 
characters. If the value of "y" is the word "hello", the 
output looks as follows: (again, "b" represents spaces)

bbbbbbbbbbhello

print z "r24z,e$(*12)"

Unlike the "mr2" conversion used in an "oconv" or 
"iconv" function, this masks the value of "z" based on the 
current value of "precision" in Pick/BASIC runtime.

If the value of "z" is 78657767 and the current "precision" 
is 4, then the amount of scaling is the requested scaling factor minus the 
precision. Because the scaling factor is equal to the precision, no scaling 
takes place. After evaluating the scaling, the mask then adds two zeros after 
the decimal point, and justifies the result in a field of asterisks. Since the 
mask is not specified with a sufficient amount of asterisks to contain the 
result, only the 12 rightmost characters are displayed.

If the value of "z" is 78657767, the output looks as follows:

,657,767.00

print oconv(date(),"d2/") "r(#10)"

This example outputs the external format of the current system date, right 
justified, fill space, in a field of 10 characters.  The output is as follows:

bbmm/dd/yy
Purpose
Related basic.crt
basic.space
basic.iconv
basic.print
format.strings
basic.oconv
basic.input@
basic.fmt