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:

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.

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:

Positive-format;negative-format;zero-format;null-format

Special characters

The following table lists characters that have special meaning in number 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] 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

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

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

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