第139章 SQL函数 TIMESTAMPDIFF

一个标量日期/时间函数，它返回指定日期部分的两个时间戳之间差异的整数计数。

大纲

{fn TIMESTAMPDIFF(interval-type,startdate,enddate)}

参数

interval-type - 返回值将表示的时间/日期间隔类型。
startdate - 时间戳值表达式。
enddate - 将与 startdate 进行比较的时间戳值表达式。

描述

TIMESTAMPDIFF 函数返回指定日期部分间隔（秒、天、周等）的两个给定时间戳之间的差异（即，从另一个中减去一个时间戳）。返回的值是一个 INTEGER，即两个时间戳之间的这些间隔数。（如果 enddate 早于 startdate，则 TIMESTAMPDIFF 返回负 INTEGER 值。）

开始日期和结束日期是时间戳。这些时间戳可以是 %Library.TimeStamp 数据类型格式 (yyyy-mm-dd hh:mm:ss.ffff) 或 %Library.PosixTime 数据类型格式（编码的 64 位有符号整数）。

间隔类型参数可以是以下时间戳间隔之一：

SQL_TSI_FRAC_SECOND
SQL_TSI_SECOND
SQL_TSI_MINUTE
SQL_TSI_HOUR
SQL_TSI_DAY
SQL_TSI_WEEK
SQL_TSI_MONTH
SQL_TSI_YEAR

这些时间戳间隔可以使用单引号或双引号来指定，带或不带引号。它们不区分大小写。

TIMESTAMPDIFF 和 DATEDIFF 不处理季度quarters （3 个月间隔）。

请注意，TIMESTAMPDIFF 只能用作 ODBC 标量函数（使用大括号语法）。可以使用 DATEDIFF 通用函数对时间戳执行类似的时间/日期比较操作。

%TimeStamp 格式化

如果 startdate 或 enddate 参数采用 %Library.TimeStamp 数据类型格式 (yyyy-mm-dd hh:mm:ss.ffff)，则适用以下规则：

如果任一时间戳表达式仅指定时间值并且间隔类型指定日期间隔（天、周、月或年），则在计算结果间隔计数之前，时间戳的缺失日期部分默认为“1900–01–01” .
如果任一时间戳表达式仅指定日期值并且间隔类型指定时间间隔（小时、分钟、秒、小数秒），则在计算结果间隔计数之前，时间戳的缺失时间部分默认为“00:00:00.000” .
可以包含或省略任意位数精度的小数秒。 SQL_TSI_FRAC_SECOND 以千分之一秒的整数计数形式返回小数秒的差异（精度为三位数）。 %PosixTime 值始终包含六位精度。

范围和值检查

TIMESTAMPDIFF 对输入值执行以下检查。

startdate 和 enddate 的所有指定部分必须有效，然后才能执行任何 TIMESTAMPDIFF 操作。
日期字符串必须完整且格式正确，其中包含适当数量的元素和每个元素的数字，以及适当的分隔符。年份必须指定为四位数。无效的日期值会导致 SQLCODE -8 错误。
日期值必须在有效范围内。年：0001 到 9999。月：1 到 12。日：1 到 31。小时：00 到 23。分：0 到 59。秒：0 到 59。一个月中的天数必须与月和年相匹配。例如，日期“02–29”仅在指定年份是闰年时有效。无效的日期值会导致 SQLCODE -8 错误。
小于 10（月和日）的日期值可能包括或省略前导零。不允许使用其他非规范整数值。因此，Day 值“07”或“7”有效，但“007”、“7.0”或“7a”无效。
时间值可以全部或部分省略。如果 startdate 或 enddate 指定了不完整的时间，则为未指定的部分提供零。
小于 10 的小时值必须包含前导零。省略此前导零会导致 SQLCODE -8 错误。

示例

以下示例返回 7，因为第二个时间戳 (2017-12-20 12:00:00) 比第一个大 7 个月：

SELECT {fn TIMESTAMPDIFF(SQL_TSI_MONTH,'2017-5-19 00:00:00','2017-12-20 12:00:00')}7

以下示例返回 566，因为第二个时间戳 ('12:00:00')) 比第一个时间戳 (02:34:12) 大 566 分钟：

SELECT {fn TIMESTAMPDIFF(SQL_TSI_MINUTE,'02:34:12','12:00:00')}566

以下示例返回 -1440，因为第二个时间戳比第一个小一天（1440 分钟）：

SELECT {fn TIMESTAMPDIFF(SQL_TSI_MINUTE,'2017-12-06','2017-12-05')}-1440