Simply about applyTimeZoneOffset and removeTimeZoneOffset methods of DateTimeUtil

In this post I want to describe simple rules of working with an unbound UtcDateTimeEdit control in a form:
1) from the database to the user -> applyTimeZoneOffset
2) from the user to the database -> removeTimeZoneOffset
Continue reading for the details.

Problem description
Define how to set and store value of an unbound UtcDateTimeEdit control in a form.

Hints
Play with bound and unbound UtcDateTimeEdit controls in a form.

Solution
Let's create a form with 2 UtcDateTimeEdit controls:
- BoundUtcDateTimeEdit is bound to EcoResDateTimeValue.DateTimeValue table field
- UnboundUtcDateTimeEdit is unbound and is based on AttributeValueDateTime EDT.

The user time zone is set to GMT+02:00:

Case 1. Set a value to Unbound control
Assume that Unbound control value is updated in modified method of Bound control like this:
UnboundUtcDateTimeEdit.dateTimeValue(EcoResDateTimeValue.DateTimeValue);

When today is set into Bound control, Unbound control has 2 hours difference:

Why? Because the user time zone is GMT+2 and table field value is saved in UTC time zone, so EcoResDateTimeValue.DateTimeValue field has "2/3/2017 10:00:00 pm". The same value is presented in Unbound control.
The user time zone must be applied to UTC field value to display correct value in Unbound control:

UnboundUtcDateTimeEdit.dateTimeValue( DateTimeUtil::applyTimeZoneOffset(EcoResDateTimeValue.DateTimeValue, DateTimeUtil::getUserPreferredTimeZone()));

Case 2. Store a value from Unbound control
Assume that utcDateTime table field is updated in modified method of Unbound control like this:
EcoResDateTimeValue.DateTimeValue = UnboundUtcDateTimeEdit.dateTimeValue();

When today is set into Unbound control, Bound control has again 2 hours difference:

Why? The value from Unbound control "2/4/2017 12:00:00 am" is treated as UTC time zone value in EcoResDateTimeValue.DateTimeValuefield. The user time zone is applied by kernel to UTC time zone field value, so Bound control has "2/4/2017 02:00:00 am".
The user time zone must be removed from control value to get UTC time zone value, which can be set to table field:

EcoResDateTimeValue.DateTimeValue = DateTimeUtil::removeTimeZoneOffset(UnboundUtcDateTimeEdit.dateTimeValue(), DateTimeUtil::getUserPreferredTimeZone());

Conclusions
DateTime value is stored in database in UTC.
The user time zone is usually different from UTC.
When a value from the database must be presented in unbound control, the user time zone offset must be applied to the value. Use DateTimeUtil::applyTimeZoneOffset() method.
When a value entered by the user into unbound control must be stored in database, the user time zone offset must be removed to get UTC value. Use DateTimeUtil::removeTimeZoneOffset() method.
Bound control values are handled automatically by kernel.