FORMAT attribute

The FORMAT attribute defines the data formatting for numeric and date time fields, for input and display.

Syntax

FORMAT = "format-string"
  1. format-string is a string of characters that specifies a data format.

Usage

The FORMAT attribute can be set to define a input and display format for numeric and date fields.

When this attribute is not used, environment variables define the default format: For MONEY and numeric fields such as DECIMAL fields, a format can be specified with the DBMONEY or DBFORMAT environment variables. For DATE fields, the format is defined by the DBDATE environment variable.

The data format is used when converting the input buffer to the program variable, and when displaying program variable data to form fields. For example, when defining a FORMAT="yyyy-mm-dd" for a form field bound to a program variable defined as a DATE, the user can input a date as 2013-12-24, and the date value will be displayed in the same manner.

Do not confuse the FORMAT and PICTURE attributes: The PICTURE attribute is used to define an input mask for character string fields, such as vehicle registration numbers.

If the 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 Table 1. 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 attribute
FORMAT attribute 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:

Date formats

Table 3. Format-string symbols for DATE 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.
other 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 attribute 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
EDIT f001 = order.thedate, FORMAT = "mm/dd/yyyy";