Defining display formats

Display formats are represented through masks, where certain
characters have special significance. PowerBuilder supports four kinds
of display formats, each using different mask characters:

• Numbers
• Strings
• Dates
• Times

For example, in a string format mask, each @ represents
a character in the string and all other characters represent themselves.
You can use the following mask to display phone numbers:

Combining formats

You can include different types of display format masks in
a single format. Use a space to separate the masks. For example,
the following format section includes a date and time format:

Using sections

Each type of display format can have multiple sections, with
each section corresponding to a form of the number, string, date,
or time. Only one section is required; additional sections are optional
and should be separated with semicolons (;). You cannot use sections in
edit masks. Semicolons can be used only in display formats.

The following format specifies different displays for positive
and negative numbers—negative numbers are displayed in
parentheses:

Using keywords

Enclose display format keywords in square brackets. For example,
you can use the keyword [General] when
you want PowerBuilder to determine the appropriate format for a number.

Using colors

You can define a color for each display format section by
specifying a color keyword before the format. The color keyword
is the name of the color, or a number that represents the color,
enclosed in square brackets: [RED] or [255]. The
number is usually used only when a color is required that is not
provided by name. The named color keywords
are:

• [BLACK]
• [BLUE]
• [CYAN]
• [GREEN]
• [MAGENTA]
• [RED]
• [WHITE]
• [YELLOW]

The formula for combining primary color values into a number
is:

where the amount of each primary color is specified as a value
from 0 to 255. For example, to specify cyan, substitute 255 for
blue, 255 for green, and 0 for red. The result is 16776960.

If you want to add text to a numeric display format and use
a color attribute, you must include the escape character ()
before each literal in the mask. For example:

Table 22-1 lists
the blue, green, and red values you can use in the formula to create
other colors.

Table 22-1: Numeric values used to create
colors

Blue	Green	Red	Number	Color
0	0	255	255	Red
0	255	0	65280	Green
0	128	0	32768	Dark green
255	0	0	16711680	Blue
0	255	255	65535	Yellow
0	128	128	32896	Brown
255	255	0	16776960	Cyan
192	192	192	12632256	Light gray

Using special characters

To include a character in a mask that has special meaning
in a display format, such as [, precede the character with
a backslash (). For example, to display a single quotation
mark, enter ”.

Setting display formats at runtime

In scripts, you can use GetFormat to get
the current format for a column and SetFormat to
change the format for a column at runtime.

Number display formats

A number display format can have up to four sections. Only
the first is required. The three other sections determine how the
data displays if its value is negative, zero, or NULL.
The sections are separated by semi-colons:

Special characters

Table 22-2 lists
characters that have special meaning in number display formats.

Table 22-2: Characters with special meaning
in display formats

Character	Meaning
#	A number
0	A required number; a number will display for every 0 in the mask

Percent signs, decimal points, parentheses, and spaces display
as entered in the mask.

Use at least one 0 In general, a number display format should include at least
one 0. If users enter 0 in a field with the mask ###,
the field will appear to be blank if you do not provide a zero-format
section. If the mask is ###.##,
only the period displays. If you want two decimal places to display
even if both are 0, use the mask ##0.00.

Number keywords

You can use the following keywords as number display formats
when you want PowerBuilder to determine an appropriate format to use:

• [General]
• [Currency]

Note that [Currency(7)] and [Currency(n)] are
legal edit masks, but they are not legal display
formats.

Number and currency settings

To ensure that an application behaves the same in every country
where it is deployed, DataWindow expressions and the masks used in display
formats and edit masks require U.S. notation for numbers. That is,
when you specify a number in a DataWindow expression or in a number mask, a
comma always represents the thousands delimiter and a period always
represents the decimal place. You should also always use the $ sign
to represent the symbol for currency.

At runtime, the locally correct symbols are displayed for
numbers and currency. The comma and period are replaced by the delimiters
defined in the user’s Number settings in the Regional or
International Settings property sheet in the Windows Control Panel.
The $ sign in the mask is replaced by the local currency
symbol as defined in the user’s Currency setting in the
Windows Control Panel. For example, in countries where a comma represents
the decimal place and a period represents thousands, users see numbers
in those formats. In a Web DataWindow, you must set ClientFormatting
to true to display regional settings correctly.

Percentages

Use caution when defining an edit mask for a percentage. When
you enter a number in a column with a percent edit mask and tab
off the column, PowerBuilder divides the number by 100 and stores
the result in the buffer. For example, if you enter 23, PowerBuilder passes
.23 to the buffer. When you retrieve from the database, PowerBuilder multiplies
the number by 100 and, if the mask is ##0%,
displays 23%.

The datatype for the column must be numeric or decimal to
handle the result of a division by 100. If the column has an integer
datatype, a percentage entered as 333 is retrieved from the database
as 300, and 33 is retrieved as 0.

If you use an edit mask with decimals, such as ##0.00%,
the datatype must have enough decimal places to handle the division.
For example, if you enter 33.33, the datatype for the column must
have at least four decimal places because the result of the division
is .3333. If the datatype has only three decimal places, the percentage
is retrieved as 33.30.

Examples

Table 22-3 shows
how the values 5, –5, and .5 display when different format masks
are applied.

Table 22-3: Number display format examples

Format	5	-5	.5
[General]	5	-5	0.5
0	5	-5	1
0.00	5.00	-5.00	0.50
#,##0	5	-5	1
#,##0.00	5.00	-5.00	0.50
$#,##0;($#,##0)	$5	($5)	$1
$#,##0;-$#,##0	$5	-$5	$1
$#,##0;[RED]($#,##0)	$5	($5)	$1
[Currency]	$5.00	($5.00)	$0.50
$#,##0.00;($#,##0.00)	$5.00	($5.00)	$0.50
$#,##0.00;[RED]($#,##0.00)	$5.00	($5.00)	$0.50
##0%	500%	-500%	50%
##0.00%	500.00%	-500.00%	50.00%
0.00E+00	5.00E+00	-5.00E+00	5.00E-01

String display formats

String display formats can have two sections. The first is
required and contains the format for strings; the second is optional
and specifies how to represent NULLs:

In a string format mask, each at-sign (@)
represents a character in the string and all other characters represent
themselves.

Example

This format mask:

displays the string 800YESCELT in
red as:

Date display formats

Date display formats can have two sections. The first is required
and contains the format for dates; the second is optional and specifies
how to represent NULLs:

Special characters

Table 22-4 shows
characters that have special meaning in date display formats.

Table 22-4: Characters with special meaning
in data display formats

Character	Meaning	Example
d	Day number with no leading zero	9
dd	Day number with leading zero if appropriate	09
ddd	Day name abbreviation	Mon
dddd	Day name	Monday
m	Month number with no leading zero	6
mm	Month number with leading zero if appropriate	06
mmm	Month name abbreviation	Jun
mmmm	Month name	June
yy	Two-digit year	97
yyyy	Four-digit year	1997

Colons, slashes, and spaces display as entered in the mask.

About 2-digit years If users specify a 2-digit year in a DataWindow object, PowerBuilder assumes the
date is the 20th century if the year is greater than or equal to
50. If the year is less than 50, PowerBuilder assumes the 21st century.
For example:

• 1/1/85 is interpreted
  as January 1, 1985.
• 1/1/40 is interpreted as January 1,
  2040.

Date keywords

You can use the following keywords as date display formats
when you want PowerBuilder to determine an appropriate format to use:

• [ShortDate]
• [LongDate]

The format used is determined by the regional settings for
date in the registry. Note that [Date] is
not a valid display format.

Examples

Table 22-5 shows
how the date Friday, January 30, 1998, displays when different format
masks are applied.

Table 22-5: Date display format examples

Format	Displays
[red]m/d/yy	1/30/98 in red
d-mmm-yy	30-Jan-98
dd-mmmm	30-January
mmm-yy	Jan-98
dddd, mmm d, yyyy	Friday, Jan 30, 1998

Time display formats

Time display formats can have two sections. The first is required
and contains the format for times; the second is optional and specifies
how to represent NULLs:

Special characters

Table 22-6 shows
characters that have special meaning in time display formats.

Table 22-6: Characters with special meaning
in time display formats

Character	Meaning
h	Hour with no leading zero (for example, 1)
hh	Hour with leading zero if appropriate (for example, 01)
m	Minute with no leading zero (must follow h or hh)
mm	Minute with leading zero if appropriate (must follow h or hh)
s	Second with no leading zero (must follow m or mm)
ss	Second with leading zero (must follow m or mm)
ffffff	Microseconds with no leading zeros. You can enter one to six f’s; each f represents a fraction of a second (must follow s or ss)
AM/PM	Two-character, uppercase abbreviation (AM or PM as appropriate)
am/pm	Two-character, lowercase abbreviation (am or pm as appropriate)
A/P	One-character, uppercase abbreviation (A or P as appropriate)
a/p	One-character, lowercase abbreviation (a or p as appropriate)

Colons, slashes, and spaces display as entered in the mask.

24-hour format is the default Times display in 24-hour format unless you specify AM/PM,
am/pm, A/P, or a/p.

Time keyword

You can use the following keyword as a time display format
to specify the format specified in the Windows control panel:

• [Time]

Examples

Table 22-7 shows
how the time 9:45:33:234567 PM displays when different format masks
are applied.

Table 22-7: Time display format examples

Format	Displays
h:mm AM/PM	9:45 PM
hh:mm A/P	09:45 P
h:mm:ss am/pm	9:45:33 pm
h:mm	21:45
h:mm:ss	21:45:33
h:mm:ss:f	21:45:33:2
h:mm:ss:fff	21:45:33:234
h:mm:ss:ffffff	21:45:33:234567
m/d/yy h:mm	1/30/98 21:45

---