Appendix
Data Format Masks  
  A format mask is a character string that can be used to define how data is to be displayed or printed in ProvideX (PRINT Directive). Masks can also be applied to filter data being received from the keyboard (INPUT Directive) or in the conversion/validation of a string (STR( ) Function).

For further information on data input and output in ProvideX, refer to Terminal Input/Output in the ProvideX User’ Guide.

   
Assigning a Format Mask To assign a format mask in ProvideX syntax, place a colon before the mask following the given data value:

value:mask$

Where:

mask$ Is a literal string, a string variable, substring, or a string expression.
value Is the value (string or numeric) that is to be converted.

For Example:

0010 PRINT "The total is ",A:"$#,###,##0.00CR"
or
0010 LET MASK$="000-0000"
0020 PRINT "Phone: ",T:MASK$

The number of characters defined in a mask must be equal to or larger than the number of characters to be displayed. One output character is generated for each character present in the format mask.

When more characters exist in the data value than are specified in the format mask, the result will generate an Error #43: Format mask invalid; e.g., outputting 1000 with a mask of "##0" causes an error.

The system parameters 'FI', 'F,' and 'FO'= can be specified to handle overflows without generating errors.

   
Format Defaults If no format mask is specified when outputting numeric values, the system formats the value as follows:
  • The first character output will indicate the sign of the value. A space will be output if positive, a minus sign if negative.
  • If the absolute value is greater than 10E+14 or is less than 10E-14 (but not zero), the value is output using scientific notation.
  • The number is rounded to the current precision in effect and output suppressing all leading zeroes and all trailing zeroes following the decimal point. The decimal point is suppressed if no digits remain after it.

For example, assuming precision of two:

->0010 PRINT 3/2, 6/3, 3-4, 2/3
1.5 2-1 .67

   
Numeric Format Masks Numeric format mask characters are used to convert numeric data (from literals, variables, or numeric expressions) to ASCII. Format masks allow for the generation of fixed format data with the insertion of fill characters (usually a space) to suppress leading/trailing zeroes.

The recognized numeric format mask characters are described below:

Character Description
0 Zero. Outputs one digit from the numeric value. Outputs one digit of the number unless the digit is zero and no
# digits have been output yet, in which case it outputs a fill character. (Suppresses leading zeroes).
. Outputs/aligns decimal point. One occurrence allowed per mask.
! Treated as '.' but causes output to be replaced with spaces if the value is 0 (zero); i.e., 'Blank when Zero'.
_ In front end of a mask, inserts '-' (if value negative) or a fill character (if positive) just before the first digit. In the trailing end of a mask, outputs either a '-' or a fill character. Within the mask, outputs a dash regardless of the value.
+ Outputs either a '-' if the number is < 0 otherwise outputs a '+'. If this format mask character is in front of the number, the output is placed just before the first digit. (floating +)
, Outputs a comma if some digits have been output; otherwise it outputs a fill character.
$ If at the front of the number, indicates that a dollar sign is to be output in front of the first digit of the number (floating dollar sign). Anywhere else, indicates that a dollar sign is to be output.
* If before any digits of the number, causes asterisks to be used as the fill character instead of a space. If it occurs anywhere else within the mask, it causes an asterisk to be output.
( or ) Outputs parentheses if the value is negative; otherwise it outputs a fill character.
CR Outputs CR if the value is negative; otherwise it outputs two fill characters.
DR Outputs CR if the value is negative; otherwise it outputs DR.
B Outputs a space.
other Outputs the character.
   
  Before being output, the number is rounded to the number of decimal places specified in the format mask. If no sign indication is specified (i.e., no -, +, (, ), CR, or DR in mask), no sign will be output.

The following table shows the results of various masks used on different values:

Value Mask Result
1 "000000" "000001"
1 "####0" " 1"
-2.4 "-###0.00" " -2.400"
1000.9 "#,##0+" "1,001+"
-10.5 "$#,##0.00BDR" " $10.50 CR"
5551212 "000-0000" "555-1212"(Phone)
2359 "00:00" "23:59"(Time)
-45 "###0" " 45"
   
String Format Masks String data can also be converted through the use of format masks. Unlike numeric format masks, string format masks are typically used to validate that the contents of a string match a pre-defined format.

The recognized string format mask characters are described below:

Character Description
0 Zero. String must contain either a digit (0-9) in this position.
A String must contain an alphabetic letter (A-Z, a-z) in this position. The output of the format mask is converted to uppercase.
a String must contain an alphabetic letter (A-Z, a-z) in this position.
X String can contain any character in this position. The output of the format mask is converted to Upper case.
x String can contain any character in this position.
Z String must contain an alphabetic letter (A-Z, a-z) or a digit (0-9) in this position. The output of the format mask is converted to Upper case.
z String must contain an alphabetic letter (A-Z, a-z) or a digit (0-9) in this position.
(nn) A numeric value surrounded by parenthesis may be used to specify a repeat count for the preceding format character. For example AAAAAmay also be specified as A(5).
other Outputs the character.