D365 Business Central : Understanding Duration Data Type

Duration can be a useful tool for calculating time intervals in various scenarios. In this blog post, we will explore on how to use Duration data type and its behavior in different scenarios.

According to Microsoft Learn, Duration data type represents the difference between two DateTimes. This value can be negative. It is stored as a 64-bit integer. The integer value is the number of milliseconds during the duration.

Let’s take a look at an example of how to use Duration data type in a simple procedure:

local procedure CalcDurationDateTime()
var
    MyDuration: Duration;
    DateTime1: DateTime;
    DateTime2: DateTime;
begin
    DateTime1 := CreateDateTime(20200101D, 010000T); // 01 January 2020 at 01:00:00 AM
    DateTime2 := CreateDateTime(20200115D, 053001T); // 15 January 2020 at 05:30:01 AM
    MyDuration := DateTime2 - DateTime1;
    Message('%1', MyDuration);
end;

In this example, the Duration value is displayed as 14 days 4 hours 30 minutes 1 second. It is stored as the total number of milliseconds in the variable.

By dividing it by one, we can get the numerical value of the duration in milliseconds.

Message('%1 milliseconds', MyDuration / 1);

We can easily convert the duration to other units of time, such as seconds, minutes, hours, and days using these conversions:

milliseconds = duration / 1
seconds = duration / 1000
minutes = duration / 60000
hours = duration / 3600000
days = duration / 86400000

In the following example, we divide the Duration value by 3600000 to get the hours value.

local procedure CalcDurationDateTime()
var
    MyDuration: Duration;
    DateTime1: DateTime;
    DateTime2: DateTime;
begin
    DateTime1 := CreateDateTime(20200101D, 010000T); // 01 January 2020 at 01:00:00 AM
    DateTime2 := CreateDateTime(20200115D, 053001T); // 15 January 2020 at 05:30:01 AM
    MyDuration := DateTime2 - DateTime1;
    Message('%1 hours.', MyDuration / 3600000)
end;

We get 340.500277777777778 hours as the result.

Although the documentation mentions that Duration data type is used for calculating the difference between two DateTimes, it can also be used with Dates or Times. Let’s take a look at an example using Time:

local procedure CalcDurationTime()
var
    MyDuration: Duration;
    Time1: Time;
    Time2: Time;
begin
    Time1 := 010000T; // 01:00:00 AM
    Time2 := 053001T; // 05:30:01 AM
    MyDuration := Time2 - Time1;
    Message('%1. \ Numerical Value %2.', MyDuration, MyDuration / 1);
end;

We get 16,201,000 milliseconds which translates to 4 hours 30 minutes 1 second.

However, when using Duration with Dates, we need to be aware of a different behavior.

local procedure CalcDurationDate()
var
    MyDuration: Duration;
    Date1: Date;
    Date2: Date;
begin
    Date1 := 20200101D; // 01 January 2020
    Date2 := 20200115D; // 15 January 2020
    MyDuration := Date2 - Date1;
    Message('%1. \ Numerical Value %2.', MyDuration, MyDuration / 1);
end;

In this example, Duration is used to calculate the time interval between two Dates, but the result is displayed incorrectly as 14 milliseconds instead of 14 days. The numerical value is also in days, instead of milliseconds. This behavior should be taken into consideration when using Duration with Dates.

Duration can only be used to calculate the difference between two similar data types. If we try to mix different data types, such as DateTime with Time, we will encounter an error.

That’s it. Hopefully this post will help you understand more on how to effectively use duration.

GitHub link.