format

The format property controls the format of numeric and date time fields for output displays.

Usage

Supply the format-string for the format property.

Note:

format-string is a string of characters that specifies a data display format.
You must enclose format-string within quotation marks ( " ).
If format-string is smaller than the field width, you get a compile-time warning, but the form is usable.

The format property can be set to define a display format for numeric and date fields. When this property is not used, environment variable settings define the default format. For MONEY and numeric fields such as DECIMAL fields, a global format can be specified with the DBMONEY or DBFORMAT environment variables. For DATE fields, the global format is defined by the DBDATE environment variable.

Understand that the format property is applied when displaying program variable data to formFields. In order to control user input with a mask, you must use the picture property instead. The picture property is typically used to specify an input mask for formatted character string fields.

If format-string is smaller than the field width, you get a compile-time warning, but the form is usable.

Numeric formats

For DECIMAL, MONEY, SMALLFLOAT, and FLOAT data types, format-string consists of a set of place holders that represent digits, currency symbols, thousands and decimal separators. For example, "###.##@" defines three places to the left of the decimal point and exactly two to the right, plus a currency symbol at the end of the string.

When used with numeric values, the format-string must use normalized place holders described in format. The place holders will be replaced by the elements defined in the DBMONEY or DBFORMAT environment variables.

Field input cannot be supported if the format is not defined with normalized place holders.

If the numeric value is too large to fit in the number of characters defined by the format, an overflow text is displayed (****).

If the actual number displayed requires fewer characters than format-string specifies, numbers are right-aligned and padded on the left with blanks.

If necessary to satisfy the format-string specification, the number values are rounded before display.

Table 1. Format-string symbols for Numeric data types
Character	Description
`*`	The star placeholder fills with asterisks any position that would otherwise be blank.
`&`	The ampersand placeholder is used to define the position of a digit, and is replaced by a zero if that position would otherwise be blank.
`#`	The sharp placeholder is used to define the position of a digit, it is used to specify a maximum width for the resulting string. This wildcard character does not change any blank positions in the display: The character is replaced by a blank if no digit is to be displayed at that position.
`<`	Consecutive less than characters cause left alignment and define digit positions.
`-`	Displays a minus sign or a blank at that position. `USING` displays a minus sign when the expression is lower than zero, and otherwise a blank character. When you group several minus signs in the format string, a single minus sign floats immediately to the left of the displayed number.
`+`	Displays a plus or minus sign at that position. `USING` displays a plus sign when the expression is greater than or equal to zero, and a minus sign when the value is less than zero. When you group several plus signs in the format string, a single plus sign floats immediately to the left of the displayed number.
`(`	Displayed as left parenthesis for negative numbers. It is used to display accounting parentheses instead of a minus sign for negative numbers. Consecutive left parentheses display a single left parenthesis to the left of the number being printed.
`)`	Displayed as right parenthesis for negative numbers. This wildcard character is used in conjunction with a open brace to display accounting parentheses for negative numbers.
`,` (comma)	The comma placeholder is used to define the position for the thousand separator defined in DBFORMAT. The thousand separator will only be displayed if there is a number on the left of it.
`.` (period)	The period placeholder is used to define the position for the decimal separator defined in DBMONEY or DBFORMAT. You can only have one decimal separator in a number format string.
`$`	The dollar sign is the placeholder for the front currency symbol defined in DBMONEY or DBFORMAT. When you group several consecutive dollar signs, a single front currency symbol floats immediately to the left of the number being printed. The front currency symbol can be defined in DBFORMAT with more than one character.
`@`	The at sign is the placeholder for the back currency symbol defined in DBMONEY or DBFORMAT. Put several consecutive @ signs at the end of the format string to display a currency symbol defined in DBFORMAT with more than one character.

Table 2. Combinations of DBFORMAT setting and FORMAT property
FORMAT property	Numeric value	DBFORMAT	Result string
---,--&.&&	-1234.56	:.:,:	-1.234.56
$---,--&.&&	-1234.56	E:.:,:	E -1.234,56
---,--&.&&@	-1234.56	:.:,:E	-1,234.56E

When the user enters numeric or currency values in fields, the runtime system behaves as follows:

If a symbol is entered that was defined as a decimal separator in DBFORMAT, it is interpreted as the decimal separator.
For MONEY fields, it disregards any front (leading) or back (trailing) currency symbol and any thousands separators that the user enters.
For DECIMAL fields, the user must enter values without currency symbols.

Date formats

Table 3. Format-string symbols for DATE and DATETIME data type
Character	Description
`dd`	Day of the month as a 2-digit integer.
`ddd`	Three-letter English-language abbreviation of the day of the week. For example: Mon, Tue.
`mm`	Month as a 2-digit integer.
`mmm`	Three-letter English-language abbreviation of the month. For example: Jan, Feb.
`yy`	Year, as a 2-digits integer representing the 2 trailing digits.
`yyyy`	Year as a 4-digit number.

Any other character is interpreted as a literal and will be displayed as is in the field.

Table 4. Format-string examples and corresponding display formats for a DATE field
FORMAT property	Date value	DBDATE	Result string
None (DBDATE applies)	1999-09-23	DMY4/	23/09/1999
dd-mm-yyyy	1999-09-23	DMY4/	23-09-1999
dd-mm-yy	1999-09-23	DMY4/	23-09-99
(ddd.) mmm. dd, yyyy	1999-09-23	DMY4/	(Thu.) Sep. 23, 1999

Example

"mm/dd/yyyy"