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:
mmmm/dd/yyyy h:mm
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:
$#,##0;($#,##0)
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:
256*256*blue + 256*green + red=number
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:
[red]\D\e\p\t\: ###
The following table lists the blue, green, and red values you can use in the formula to create other 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.
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:
Positive-format;negative-format;zero-format;null-format
Special characters
The following table lists characters that have special meaning in number display formats.
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] and [Currency(n)] are legal edit masks, but they are not legal display formats.
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
The following table shows how the values 5, –5, and .5 display when different format masks are applied.
|
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 can have two sections. The first is required and contains the format for strings; the second is optional and specifies how to represent NULLs:
string-format;null-format
In a string format mask, each at-sign (@) represents a character in the string and all other characters represent themselves.
Special characters for string edit masks
String edit masks use different special characters. See The EditMask edit style.
Example
This format mask:
[red](@@@) @@@-@@@@
displays the string 800YESCELT in red as:
YES-CELT
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:
date-format;null-format
Special characters
The following table shows characters that have special meaning in date 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
The following table shows how the date Friday, January 30, 1998, displays when different format masks are applied.
|
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 can have two sections. The first is required and contains the format for times; the second is optional and specifies how to represent NULLs:
time-format;null-format
Special characters
The following table shows characters that have 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
The following table shows how the time 9:45:33:234567 PM displays when different format masks are applied.
|
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 |
