%DIFF (兩個日期、時間或時間戳記值之間的差異)

線上編輯


%DIFF(op1 : op2 : unit {: frac })

單位可以是 *MSECONDS、*SECONDS、*XX_ENCODE_CASE_CAPS_LOCK_ON *minutes、*hours、*days、*months 或 *Years。您也可以使用下列縮寫形式: *MS、*S、*MN、*H、*D、*M 或 *Y。

%DIFF 會產生兩個日期或時間值之間的差異 (持續時間)。第一個參數和第二個參數必須具有相同或相容的類型。可能的組合如下:

日期和日期
時間和時間
時間戳記和時間戳記
日期和時間戳記 (只考量時間戳記的日期部分)
時間和時間戳記 (只考量時間戳記的時間部分)。

第三個參數指定單位。下列單元有效:

若為兩個日期或一個日期及時間戳記: *Days、*MONES 及 *YEARS
兩次或一次時間及時間戳記: *SECONDS、*XX_ENCODE_CASE_CAPS_LOCK_ON minutes 及 *hours
兩個時間戳記: *MSECONDS、*SECONDS、*XX_ENCODE_CASE_CAPS_LOCK_ON *minutes、*hours、*days、*months 及 *Years

*MONTHS 和 *YEARS 的結果可能令人驚訝。請參閱非預期的結果。

如果第三個運算元是 *SECONDS 或 *S ，且兩個運算元都是時間戳記，則您可以指定第四個參數，指出要傳回的小數秒數。您可以指定 0 到 12 之間的值。這代表所傳回秒數中的小數位數。

此差異的計算方式是從第一個運算元中減去第二個運算元。

結果會向下捨入，並捨棄任何餘數。例如， 61 分鐘等於 1 小時， 59 分鐘等於 0 小時。

函數傳回的值與類型數值及類型持續時間相容。您可以將結果新增至數字 (類型數值) 或日期、時間或時間戳記 (類型持續時間)。

如果您要求相隔超過 32 年 9 個月的兩個時間戳記之間的差異 (以微秒為單位) ，則您將超出持續時間值的 15 位數限制。這會導致錯誤或截斷。不過，您可以透過要求以秒為單位的差異加上 6 個小數秒，然後將結果值乘以 1000000 ，來取得任兩個日期之間的微秒數。例如，如果以秒為單位的差異為 1041379205.123456，則以微秒為單位的差異為 1041379205123456。

如需相關資訊，請參閱日期作業或內建函數。

圖 1. 使用 %DIFF 的結果作為數值

D due_date        S               D   INZ(D'2005-06-01')
D today           S               D   INZ(D'2004-09-23')
D num_days        S             15P 0

D start_time      S               Z

D time_taken      S             15P 0                

 /FREE

     // Determine the number of days between two dates.

     // If due_date has the value 2005-06-01 and
     // today has the value 2004-09-23, then
     // num_days will have the value 251.

     num_days = %DIFF (due_date: today: *DAYS);      

     // If the arguments are coded in the reverse order,
     // num_days will have the value -251.

     num_days = %DIFF (today: due_date: *DAYS);  

     // Determine the number of seconds required to do a task:
     //  1. Get the starting timestamp
     //  2. Do the task
     //  3. Calculate the difference between the current
     //     timestamp and the starting timestamp

     start_time = %timestamp();
     process();
     time_taken = %DIFF (%timestamp() : start_time : *SECONDS);

 /END-FREE

圖 2. 使用 %DIFF 的結果作為持續時間

D estimated_end...
D                 S               D
D prev_start      S               D   INZ(D'2003-06-21')
D prev_end        S               D   INZ(D'2003-06-24')

 /FREE     

     // Add the number of days between two dates
     // to a third date

     // prev_start is the date a previous task began
     // prev_end is the date a previous task ended.

     // The following calculation will estimate the
     // date a similar task will end, if it begins
     // today.

     // If the current date, returned by %date(), is
     // 2003-08-15, then estimated_end will be
     // 2003-08-18.

     estimated_end = %date() + %DIFF(prev_end : prev_start : *days);

 /END-FREE