Understanding the Date, TimeofDay, and DateTime property types
A single application can be deployed worldwide. To support varied needs for time zones and locales, three different property types are available: Date, TimeofDay, and DateTime.
The system can have the following:
- Users who access servers located in different time zones and different locales from where they work
- Multiple, application-specific work calendars with different hours, days of the work week, and holidays
- Interfaces to and from external databases or systems that expect many different date or time formats
To support these varied needs, three different property types are available:
Date— A day of the Gregorian calendar, without reference to a time zone or locale. The unit is a whole day, such as July 23, 2018.TimeofDay— A time of day, without reference to a time zone or locale. The unit is seconds, such as 15 seconds after 1:25 P.M.DateTime— A date and time, stored internally to the millisecond if available, in a known time zone. For example 15.452 seconds after midnight on July 23, 2018 in London, U. K.
When presented with a DateTime value, a corresponding date and a
time-of-day (in a specified time zone) can be determined.
However, the converse is not usually true: when starting with a
Date
and a
TimeofDay
value, multiple differing but "correct"
DateTime
values can be constructed, depending on assumptions about time zone, Daylight Savings Time,
and other considerations. For example, when the date is January 1 in London, it can be
December 31 in New York.
Likewise, when comparing two values, or computing with dates, times, and
DateTime
values, context is important. A time of 6:15 P.M. in London is earlier, not later, than 6:16 P.M. in New York.
Different languages and locales use different formats to present dates and times;
Pega Platform
supports many output and import formats while using only three property types:
Date,
TimeofDay, and
DateTime.
The internal representations
The internal representations are efficient for sorting and comparisons and Java operations, but may not be familiar to business users:
- The internal representation of a
Datevalue is eight digits in the format yyyyMMdd, for example,20181214represents December 14, 2018. - The internal representation of
Time of Dayvalue is six digits in the format HHmmss, where the hours portion ranges from 00 to 23. For example,153025represents 25 seconds after 3:30 P.M. - For
DateTimevalues, the internal representation is stored in the GMT timezone in the format yyyyMMddTHHmmss.SSS GMT, where GMT and T are literal characters, MM represents a month, dd is a day, yyyy is a year, HH is an hour value between 00 and 23, mm is a minute value between 00 and 59, ss is a second value between 00 and 59, and SSS is milliseconds. For example,20181016T032300.000 GMTrepresents 3:23 A.M. on October 16, 2018 in the GMT time zone
Entering date and time constants (developer)
When a developer enters a value corresponding to a
Time of Day
or
DateTime
into a rule form, no format conversion occurs, but certain
shortcuts are available.
Date values
You can enter a date using either two or four digits for the year. If the year contains two digits, the system uses an algorithm to determine a "reasonable" century based on the current date. During 2016, the system prefers dates between 2007 and 2107.
TimeofDay values
To enter a constant
TimeofDay
value into a rule form, enter either all
six digits or omit the seconds portion.
DateTime values
When entering a DateTime value in a rule form, the second and millisecond
values default to zero. If the year is input as two digits, the system uses an algorithm to
determine a "reasonable" century based on the current date. During 2006, the system prefers
dates between 1997 and 2097. If you omit the time zone, the date and time are converted from
the current server time zone to the GMT time zone by adding or subtracting hours.
Date constants
When entering a
Date
literal constant as an entire expression, be sure to
include double quotes, to distinguish:
"20181215"the date December 15, 2018 from:
20181215an integer that is converted to 20,181,215.
Entering and presenting values in an application context
Pega Platform supports dozens of formats that your application can choose to present dates and times in ways familiar to application users. The formats that apply in specific cases depend on the selected non-auto-generated control rule or the configuration of the pxDateTime auto-generated control rule (Rule-HTML-Property rule type) associated with the property or the form and the locale.
Many formats are locale-specific, changing automatically based on the value set on each user's workstation, or the locale of a user as recorded in the Operator ID data instance.
For example, the date 20181214 can appear as any of the following:
12/14/1814/12/18December 14, 201814 décembre 2018Similarly, many different formats and shortcuts are available for input. These date and time formats are based on version 1.3 of the Unicode Common Locale Data Repository (CLDR).
Time zone and Daylight Savings Time conversions
Pega Platform uses the time zones provided by the JVM on which it runs. The JVM typically uses data provided by the Olson TZ database. Details on this database are available from https://www.iana.org/time-zones.
Testing input and output formats
To see the effect of a specific control rule on input and output formats for a property:
- Open the Property form.
- Click Preview.
- Enter a value in the Input field.
- Click Show output.
The Locale settings tool is also useful in understanding the effect of locales on date and time formats by temporarily changing your locale. To access the Locale settings tool, click .
Converting or comparing a DateTime value to a Date value
The first eight characters of a DateTime value match the structure of a
Date value that is formatted as yyyyMMdd, for example 20180930 represents
September 30, 2018. Accordingly, a simple way to compare a Date value with
a DateTime value is to first select a substring of the
DateTime value, consisting of the initial eight characters. Both values
then have a common string format and length, and a normal string comparison works.
For example, the Property-Set method "converts" a DateTime value to a
Date value by selecting the first eight characters.
When the DateTime value is 20181201T011532.006 GMT, the resulting value
for the Date property MyDate is 20181201.
However, this approach ignores the time zone information in the DateTime
value, because the Date value conveys no time zone.
Use the FormatDateTime function to convert a DateTime value to a Date value as shown below:
@FormatDateTime(.pyExpireDateTime, "yyyyMMdd", "", "")Converting or comparing a DateTime value to a TimeOfDay value
The substring of a DateTime value from character position 10 to character
position 15 contains a time-of-day value, in the format HHmmss expected by a property that
has a Type of TimeOfDay.
Similarly to
Date
conversion, you can "convert" or extract this
TimeOfDay
value from a DateTime value with a Property-Set assignment.
When the DateTime value is 20181201T011532.006 GMT, the resulting value
for the Time property MyTime is 011532.
However, this approach ignores the time zone information in the
DateTime
value, because the
Time
value conveys no time zone.
Use the FormatDateTime function to convert a DateTime value to a TimeOfDay value as shown below:
@FormatDateTime(.pyExpireDateTime, "HHmmss", "", "")Converting Date or TimeOfDay values to DateTime values
See Data type conversions in expressions and property assignments.
Oracle, Microsoft SQL Server and IBM Db2 notes
Because vendors have implemented variations from SQL standards, mappings between Pega Platform data types and database column types vary by vendor. For the PegaRULES database, Pega Platform uses the mappings described here.
This information may be helpful when your application uses Connect SQL rules to access an external database that uses the vendor's software.
Oracle
The Oracle data type DATE corresponds to the Pega Platform
DateTime property type. To save a Pega Platform
Date property into an Oracle database, use VARCHAR2(8), not
DATE, as the Oracle data type.
The Oracle TIMESTAMP data type is supported throughout the Pega Platform data layer. For more information, see the Pega Community
article DateTime property mapping in Oracle for Pega 7.
IBM Db2
IBM's Db2 DATE data type corresponds to the Pega Platform
Date property type. This data type does not contain any time information.
Use the Db2 TIMESTAMP data type with the Pega Platform
DateTime property to store a date with the time.
The Db2
TIME
data type does not correspond to any
Pega Platform
property type. Use a Db2 VARCHAR(8) to map a Time property to a
Db2 column.
When feasible in external Db2 databases, use the Db2
TIMESTAMP
data type
instead of DATE or TIME. If not feasible, use a
Pega Platform
property
type of
Text
to hold the value, which can be converted (cast).
Microsoft SQL Server
The Microsoft
DATETIME
data type corresponds to the
DateTime
property type.
- Constants in expressions
- Contrasting time-qualified rules and historical processing
- Java date pattern
A Java date pattern is a sequence of one or more letters that controls the presentation of a date, or date and time. For example, the pattern MM/dd/yyyy is a request for a date to be presented in the format 07/04/1976 for July 4, 1976.
- The DateTime parse tester tool
Use the Date/Time Parse Tester tool to test whether a text input matches the DateTime patterns used by Pega Platform, which are based directly on Java standards.
- Evaluation of symbolic dates
You can use symbolic dates for values of Date and DateTime properties in reports. Some symbolic dates identify a single day, such as Yesterday or Tomorrow. Other symbolic dates define a period (an inclusive range of dates), such as Current Month or Previous Quarter.
Previous topic Date time (calendar) control Next topic Evaluation of symbolic dates