format

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

The format property defines the display format for a numeric or date field.

To set the format property, supply a format string. A format string is a string of characters that specifies a data display format. Enclose the format string in quotation marks (").

Important:

If the defined format string is smaller than the width of the field where the string is to be displayed, you will get a compile time warning. The form, however, is usable.

If the format property is not used, environment variable 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.

For further information on these enviromental variables, see the Genero Business Development Language User Guide.

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

This topic provides basic instruction for using the FORMAT property. For full details you should spend additional time reviewing the FORMAT attribute and Formatting data topics in the Genero Business Development Language User Guide.

Numeric formats

The placeholder symbols for creating an numeric format string, along with several examples, are provided below. For a more detailed explanation, please refer to Formatting numeric values in the Genero Business Development Language User Guide.

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
Placeholder	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 hash placeholder is used to define the position of a digit, it is used to specify a maximum width for the resulting string. The # 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 if the value is negative, or a blank if the value is positive. When you group several minus signs in the format string, a single minus sign floats immediately to the left of the first digit.
`+`	Displays a minus sign if the value is negative, or a plus sign if the value is positive. When you group several plus signs in the format string, a single plus sign floats immediately to the left of the first digit.
`(`	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 first digit.
`)`	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 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 DBFORMAT. When you group several consecutive dollar signs, a single front currency symbol floats immediately to the left of the first digit. The front currency symbol can be defined in DBFORMAT with more than one character (EUR, USD).
`@`	The "at" sign is the placeholder for the back currency symbol defined in 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. Numeric formatting examples
Format String	Value	DBFORMAT	Result string
`[######.##]`	`0`	`:.:,:`	`[______,__]`
`[######.##]`	`-1234.56`	`:.:,:`	`[__1234,56]` (no sign!)
`[######.##]`	`-1234567.89`	`:.:,:`	`[*********]` (overflow)
`[######.##]`	`+1234.56`	`:.:,:`	`[__1234,56]`
`[#####&.&&]`	`0`	`:.:,:`	`[_____0,00]`
`[****.]`	`0`	`:.:,:`	`[******,00]`
`[****.]`	`-12.34`	`:.:,:`	`[****12,34]` (no sign!)
`[****.]`	`+12.34`	`:.:,:`	`[****12,34]`
`[<<<<<<.<<]`	`-12.34`	`:.:,:`	`[12,34]` (no sign!)
`[<<<<<<.<<]`	`+12.34`	`:.:,:`	`[12,34]`
`[---,--&.&&]`	`-1234.56`	`:.:,:`	`[_-1.234,56]`
`[+++,++&.&&]`	`-1234.56`	`:.:,:`	`[_-1.234,56]`
`[+++,++&.&&]`	`+1234.56`	`:.:,:`	`[_+1.234,56]`
`[$---,--&.&&]`	`-1234.56`	`E:.:,:`	`[E_-1.234,56]`
`[$---,--&.&&]`	`+1234.56`	`E:.:,:`	`[E__1.234,56]`
`[$$$---,--&.&&]`	`+1234.56`	`E:.:,:`	`[_E___1.234,56]`
`[$$$---,--&.&&]`	`+1234.56`	`EUR:.:,:`	`[EUR__1.234,56]`
`[-,---,-$&.&&]`	`-12.34`	`E:.:,:`	`[_____-E12,34]`
`[-,---,-$&.&&]`	`-1234.56`	`E:.:,:`	`[__-E1.234,56]`
`[-,-$$,$$&.&&]`	`-12.34`	`E:.:,:`	`[__-___E12,34]`
`[-,-$$,$$&.&&]`	`-1234.56`	`E:.:,:`	`[__-E1.234,56]`
`[---,--&.&&@]`	`-1234.56`	`:.:,:E`	`[_-1.234,56E]`
`[---,--&.&&@]`	`+1234.56`	`:.:,:E`	`[__1.234,56E]`
`[---,--&.&&@@@]`	`+1234.56`	`:.:,:EUR`	`[__1.234,56EUR]`
`[($---,--&.&&)]`	`-1234.56`	`E:.:,:`	`[(E_-1.234,56)]`
`[($###,##&.&&)]`	`-1234.56`	`E:.:,:`	`[(E__1.234,56)]` (no sign!)
`[((((,(($.&&)]`	`0`	`E:.:,:`	`[_______E,00_]`
`[((((,(($.&&)]`	`-12.34`	`E:.:,:`	`[____(E12,34)]` (no sign!)
`[((((,(($.&&)]`	`+12.34`	`E:.:,:`	`[_____E12,34_]`
`[((((,(($.&&)]`	`-1234.56`	`E:.:,:`	`[_(E1.234,56)]` (no sign!)
`[((((,(($.&&)]`	`+1234.56`	`E:.:,:`	`[__E1.234,56_]`

Note:

In the first and last columns, the strings are shown with opening and closing square brackets. These brackets mark the start and the end of the string. In the result column, underscore characters are used to represent spaces. This is important when examining the result string, as it shows where spaces exist.

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.

Numeric formatting example

"$---,--&.&&"

Date formats

The placeholder symbols for creating an date format string, along with several examples, are provided below. For a more detailed explanation, please refer to Formatting DATE values in the Genero Business Development Language User Guide.

Table 3. Format-string symbols for DATE values
Placeholder	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.
`yyy`	Year as a 3-digit number (Ming Guo format only)
`yyyy`	Year as a 4-digit number.
`c1`	Ming Guo format modifier.

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

Table 4. Date formatting examples
Format String	Date value	Result string
`dd/mm/yyyy`	`2011-10-24`	`24/10/2011`
`[dd/mm/yy]`	`2011-10-24`	`[24/10/11]`
`[ddd-mmm-yyyy]`	`0141-10-24`	`[Tue-Oct-0141]`
`(ddd.) mmm. dd, yyyy`	`1999-09-23`	`(Thu.) Sep. 23, 1999`

Date formatting example

"mm/dd/yyyy"

Datetime formats

The placeholder symbols for creating a datetime format string, along with several examples, are provided below. For a more detailed explanation, please refer to Formatting DATETIME values in the Genero Business Development Language User Guide.

Table 5. Format-string symbols for DATETIME values
Placeholder	Description
`%a`	The abbreviated name of the day of the week. Note: When parsing a datetime string, `%a` and `%A` are equivalent to detect the name of the day of the week in abbreviated form or full day name.
`%A`	The full name of the day of the week.
`%b` or `%h`	The abbreviated month name. Note: When parsing a datetime string, `%b`/`%h` and `%B` are equivalent to detect the month name in abbreviated form or full month name.
`%B`	The full month name.
`%c`	The date and time representation.
`%C`	The century number (0-99)
`%D`	Equivalent to `%m/%d/%y`
`%d`	The day of month with 2 digits (01-31)
`%e`	The day of month with one or 2 digits (1-31)
`%F`	The fractional part of a second
`%H`	The hour with 2 digits (00-23).
`%I`	The hour on a 12-hour clock (1-12)
`%y`	The year on 2 digits (91)
`%Y`	The year on 4 digits (1991)
`%m`	The month as 2 digits (01-12)
`%M`	The minutes (00-59)
`%n`	A newline character
`%p`	The locale's equivalent of AM or PM
`%r`	The 12-hour clock time. In the POSIX locale equivalent to `%I:%M:%S %p`
`%R`	Equivalent to `%H:%M`
`%S`	The seconds (00-59)
`%t`	A tab character
`%T`	Equivalent to `%H:%M:%S`
`%x`	The date, using the locale's date format.
`%X`	The time, using the locale's time format.
`%w`	The ordinal number of the day of the week (0-6), with Sunday = 0.
`%y`	The year within century (0-99)
`%Y`	The year, including the century (for example, 1991)

Table 6. Datetime formatting examples
Format String	Datetime value	Result string
`%d/%m/%Y %H:%M`	`2011-10-24 11:23:45`	`24/10/2011 11:23`
`[%d %b %Y %H:%M:%S]`	`2011-10-24 11:23:45`	`[24 Oct 2011 11:23:45]`
`(%a.) %b. %d, %Y`	`1999-09-23`	`(Thu.) Sep. 23, 1999`

Example: entering a format string for a datetime variable

"%d/%m/%Y %H:%M"

Interval formatting

The placeholder symbols for creating an interval format string, along with several examples, are provided below. For a more detailed explanation, please refer to Formatting INTERVAL values in the Genero Business Development Language User Guide.

Table 7. Format-string symbols for INTERVAL values
Placeholder	Description
`%Y`	Years (0-999999999)
`%m`	Months (0-999999999 if highest INTERVAL qualifier is MONTH(n), 0-11 otherwise)
`%d`	Days (0-999999999)
`%H`	Hours (0-999999999 if highest INTERVAL qualifier is HOUR(n), 00-23 otherwise)
`%M`	Minutes (0-999999999 if highest INTERVAL qualifier is MINUTE(n), 00-59 otherwise)
`%S`	Seconds (0-999999999 if highest INTERVAL qualifier is SECOND(n), 00-59 otherwise)
`%F[n]`	The fractional part of a second, where n specifies the number of digits in the fractional part (1 to 5)
`%t`	A tab character
`%n`	A newline character

Table 8. Interval formatting examples
Format String	Interval value	Result string
`%d days %H:%M`	`54561 11:23`	`54561 days 11:23`
`%d days %H:%M:%S%F5`	`54561 11:23:45.12345`	`54561 days 11:23:45.12345`
`[%Y years and %m months]`	`1023-03`	`[1023 years and 03 months]`

Example: entering a format string for an interval variable

"%d days %H:%M"