Database application development is a feature of JBuilder Professional and Enterprise. Distributed application development is a feature of JBuilder Enterprise.
All data stored internally as numbers, dates, etc., is entered and displayed as text strings. Formatting is the conversion from the internal representation to a string equivalent. Parsing is the conversion from string representation to internal representation. Both conversions are defined by rules specified by string-based patterns.
All formatting and parsing of data in the DataSet
package is controlled by the VariantFormatter
class,
which is uniquely defined for every Column
in a DataSet
. To simplify the use of this class,
there are corresponding string properties which, when set, construct a VariantFormatter
for the Column
using the basic pattern syntax defined in the JDK java.text.Format
classes.
There are four distinct kinds of patterns based on the data type of the item you are controlling.
See "String-based patterns (masks)" in the DataExpress Library Reference for more information on patterns.
The Column
level properties that work with these string-based patterns are:
displayMask
property, which defines the pattern used for basic data formatting and data entry.
editMask
property, which defines the pattern used for more advanced keystroke-by-keystroke data entry (also called parsing).
exportDisplayMask
property, which defines the pattern used when importing and exporting data to text files.
The default VariantFormatter
implementations for each Column
are simple implementations which were written to be fast. Those columns using punctuation characters, such as dates, use a default pattern derived from the column's locale. To override the default formatting (for example, commas for separating groups of thousands, or a decimal point), explicitly set the string-based pattern for the property you want to set (displayMask
, editMask
, or exportDisplayMask
).
Setting a displayMask
, editMask
, or exportDisplayMask
to an empty string or null has special meaning; it selects its pattern from the default Locale
. This is the default behavior of JBuilder for columns of type Date, Time, Timestamp, Float, Double, and
BigDecimal. By doing this, JBuilder assures that an application using the defaults will automatically select the proper display format when running under a different locale.
To override the default formats for numeric and date values that are stored in locale files, set the displayMask
, editMask
, or exportDisplayMask
property (as appropriate) on the Column
component of the DataSet
.
The formatting capabilities provided by DataExpress package string-based patterns are typically sufficient for most formatting needs. If you have more specific formatting needs, the format mechanism includes general-purpose interfaces and classes that you can extend to create custom format classes.
Column
, for example, in a JdbTable
. Display masks can add spaces or special characters within a data item for display purposes.
Display masks are also used to parse user input by converting the string input back into the correct data type for the Column
. If you enter data which cannot be parsed using the specified display mask pattern, you will not be able to leave the field until data entered is correct.
Tip: User input that cannot be parsed with the specified pattern generates validation messages. These messages appear on the JdbStatusLabel
control when the JdbStatusLabel
and the UI component that displays the data for editing (for example, a JdbTable
) are set to the same DataSet
.
Column
and to parse the string data into the Column
keystroke-by-keystroke.
In a Column
with a specified edit mask, literals included in the pattern display may be optionally saved with the data. Positions in the pattern where characters are to be entered display as underscores (_) by default. As you type data into the Column
with an edit mask, input is validated with each key pressed against characters that the pattern allows at that position in the mask.
Characters that are not allowed at a given location in the pattern are not accepted and the cursor moves to the next position only when the criteria for that location in the pattern is satisfied.
exportDisplayMask
property. Use the exportDisplayMask
to format the data being imported. Often, data files contain currency formatting characters which cannot be read directly into a numeric column. You can use an exportDisplayMask
pattern to read in the values without the currency formatting. Once in JBuilder, set display and/or edit masks to re-establish currency (or other formatting) as desired.
When exporting data, JBuilder uses the exportDisplayMask
to format the data for export. At the same time, it creates a .SCHEMA file with these settings so that data can be easily imported back into a DataExpress component.
Numeric Column
components always have display and edit masks. If you do not set these properties explicitly, default patterns are obtained using the following search order:
Column
component's locale.
Column
, from the DataSet
object's locale.
DataSet
, from the default system locale. Numeric data displays with three decimal places by default.
Numeric columns allow any number of digits to the left of the decimal point; however, masks restrict this to the number of digits specified to the left of the decimal point in the mask.
To ensure that all valid values can be entered into a Column
, specify sufficient digits to the left of the decimal point in your pattern specification.
In addition, every numeric mask has an extra character positioned at the left of the data item that holds the sign for the number.
The code that sets the display mask to the first pattern in the table below is:
column1.setDisplayMask(new String("###%"));
The following table explains the pattern specifications for numeric data:
Pattern specification | Data values | Formatted value | Meaning |
###% | 85 | 85% | All digits are optional, leading zeros do not display, value is divided by 100 and shown as a percentage |
#,##0.0#^ cc;-#,##0.0#^ cc |
500.0 -500.5 004453.3211 -00453.3245 |
500.0 cc -500.5 cc 4,453.32 cc -453.32 cc |
The "0" indicates a required digit, zeroes are not suppressed. Negative numbers are preceded with a minus sign. The literal "cc" displays beside the value. The cursor is positioned at the point of the carat (^) with digits moving to the left as you type each digit. |
$#,###.##;($#,###.##) |
4321.1 -123.456 |
$4,321.1 ($123.46) |
All digits optional, includes a thousands separator, decimal separator, and currency symbol. Negative values enclosed in parenthesis. Typing in a minus sign (-) or left parenthesis (() causes JBuilder to supply parenthesis surrounding the value. |
Column
component's locale.
Column
, from the DataSet
object's locale.
DataSet
, from the default system locale.
For example, the code that sets the edit mask to the first pattern listed below is:
column1.setDisplayMask(new String("MMM dd, yyyyG"));
The following table explains the pattern specifications for date and time data:
Pattern specification | Data values | Formatted value | Meaning |
MMM dd, yyyyG |
January 14, 1900 February 2, 1492 |
Jan 14, 1900AD Feb 02, 1492AD |
Returns the abbreviation of the month, space (literal), two digits for the day, 4 digits for year, plus era designator |
MM/d/yy H:m |
July 4, 1776 3:30am March 2, 1997 11:59pm |
07/4/76 3:30 03/2/92 23:59 |
Returns the number of the month, one or two digits for the day (as applicable), two digits for the year, plus the hour and minute using a 24-hour clock |
For example, the code that sets the display and edit masks to the first pattern listed below is:
column1.setDisplayMask(new String("00000{-9999}"));
column1.setEditMask(new String("00000{-9999}"));
The following table explains some pattern specifications:
Pattern specification | Data values | Formatted value | Meaning |
00000{-9999} |
950677394 00043 1540001 |
95067-7394 00043 00154-0001 | Display leading zeros for the left 5 digits (required), optional remaining characters include a dash literal and 4 digits. Use this pattern for U.S. postal codes. |
L0L 0L0 |
H2A2R9 M1M3W4 |
H2A 2R9 M1M 3W4 |
The L specifies any letter A-Z, entry required. The 0 (zero) specifies any digit 0-9, entry required, plus (+) and minus (-) signs not permitted. Use this pattern for Canadian postal codes.
|
{(999)} 000-0000^!;0 | 4084311000 | (408) 431-1000 | A pattern for a phone number with optional area code enclosed in parenthesis. The carat (^) positions the cursor at the right side of the field and data shifts to the left as it is entered. To ensure data is stored correctly from right to left, use the ! symbol. (Numeric values do this automatically.) The zero (0) indicates that literals are not stored with the data. |
The BooleanFormat
component uses a string-based pattern that is helpful when working with values that can have two values, stored as true or false. Data that falls into each category is formatted using string values you specify. This formatter also has the capability to format null or unassigned values.
For example, you can store gender information in a column of type boolean but can have JBuilder format the field to display and accept input values of "Male" and "Female" as shown in the following code:
column1.setEditMask("Male;Female;");
column1.displayMask("Male;Female;");
The following table illustrates valid boolean patterns and their formatting effects:
Pattern specification |
Format for true values | Format for false values | Format for null values |
male;female | male | female | (empty string) |
T,F,T | T | F | T |
Yes,No,Don't know | Yes | No | Don't know |
smoker;; | smoker | (empty string) | (empty string) |
smoker;nonsmoker; | smoker | nonsmoker | (empty string) |