utcdatetime [AX 2012]
Updated: September 21, 2011
Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012
The utcdatetime data type is intrinsic to X++. It combines date and timeOfDay types into one type. A utcdatetime variable also holds time zone information, though this information is not accessible to X++ code.
The following table describes the range and precision of the utcdatetime data type.
Attribute of utcdatetime
The smallest unit of time in utcdatetime is one second.
Default and Null
A utcdatetime variable that has been declared but not initialized has the default value of 1900-01-01T00:00:00. This is the value returned by DateTimeUtil ::minValue().
Some functions treat an input parameter of this minimum value as null. For instance, the DateTimeUtil ::toStr method returns an empty string, however, the DateTimeUtil ::addSeconds method returns a fully usable utcdatetime value.
This matches the upper range of date and timeOfDay.
When you add a utcdatetime field to a table, we recommend that you base the field on an extended data type (EDT). In MorphX, when you set the TimezonePreference property to Auto or User on the EDT, all fields based on the EDT are treated in the same consistent manner. The proper time zone offset is applied to all displays and to all filtering. A plain utcdatetime field has no TimezonePreference property.
The Table Browser form that the Application Object Tree (AOT) provides for each table can add and display utcdatetime values. This form treats utcdatetime fields differently depending on whether the fields are based on an EDT. Unless you understand and want that kind of different treatment among your utcdatetime fields, you should base all your utcdatetime fields on an EDT.
The format for a utcdatetime literal is yyyy-mm-ddThh:mm:ss, with the uppercase T being a required literal character. This format is understood by X++ without quotes, as shown in these examples:
utcdatetime myUtc2 = 1988-07-20T13:34:45;
int iDay = DateTimeUtil ::day(1988-07-20T13:34:45)
This same format is expected as a quoted string parameter into the DateTimeUtil ::parse method:
utcdatetime myUtc4 = DateTimeUtil ::parse("1988-07-20T13:34:45");
There are no automatic or implicit conversions for the utcdatetime data type.
The DateTimeUtil class provides many methods for manipulating utcdatetime values. The Microsoft Dynamics AX system provides the conversion functions str2datetime and datetime2str. Also, the Global class provides the conversion methods utcDateTime2SystemDateTime and CLRSystemDateTime2UtcDateTime to support common language runtime (CLR) interop.
Announcements: To see known issues and recent fixes, use Issue search in Microsoft Dynamics Lifecycle Services (LCS).