第138章 SQL函数 TIMESTAMPADD

一个标量日期/时间函数，它返回一个新的时间戳，该时间戳是通过将指定日期部分的多个间隔添加到时间戳来计算的。

大纲

{fn TIMESTAMPADD(interval-type,integer-exp,timestamp-exp)}

参数

• interval-type - integer-exp 表示的时间/日期间隔类型，指定为关键字。
• integer-exp - 要添加到 timestamp-exp 的整数值表达式。
• timestamp-exp - 时间戳值表达式，将增加 integer-exp 的值。

描述

TIMESTAMPADD 函数通过将指定的日期部分增加指定的单位数来修改日期/时间表达式。例如，如果 interval-type 是 SQL_TSI_MONTH 并且 integer-exp 是 5，则 TIMESTAMPADD 将 timestamp-exp 增加五个月。还可以通过为 integer-exp 指定负整数来减少日期部分。

TIMESTAMPADD 返回与输入timestamp-exp 数据类型相同的时间戳。此时间戳可以是 %Library.TimeStamp 数据类型格式 (yyyy-mm-dd hh:mm:ss.ffff) 或 %Library.PosixTime 数据类型格式（编码的 64 位有符号整数）。

请注意，TIMESTAMPADD 只能用作 ODBC 标量函数（使用大括号语法）。

可以使用 DATEADD 通用函数对时间戳执行类似的时间/日期修改操作。

Interval Types

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

• SQL_TSI_FRAC_SECOND
• SQL_TSI_SECOND
• SQL_TSI_MINUTE
• SQL_TSI_HOUR
• SQL_TSI_DAY
• SQL_TSI_WEEK
• SQL_TSI_MONTH
• SQL_TSI_QUARTER
• SQL_TSI_YEAR

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

增加或减少时间戳间隔会导致其他间隔被适当地修改。例如，增加午夜过后的小时数会自动增加天数，而这又会增加月数，依此类推。 TIMESTAMPADD 总是返回一个有效的日期，考虑到一个月的天数，并计算闰年。例如，将 1 月 31 日增加一个月会返回 2 月 28 日（该月中的最高有效日期），除非指定的年份是闰年，在这种情况下它会返回 2 月 29 日。

可以按三位精度的小数秒递增或递减。将小数秒指定为千分之一秒的整数计数（001 到 999）。

DATEADD 和 TIMESTAMPADD 处理季度（3 个月间隔）； DATEDIFF 和 TIMESTAMPDIFF 不处理宿舍。

%TimeStamp 格式化

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

• 如果 timestamp-exp 仅指定时间值，则在计算生成的时间戳之前，timestamp-exp 的日期部分设置为“1900-01-01”。
• 如果 timestamp-exp 仅指定一个日期值，则在计算结果时间戳之前，timestamp-exp 的时间部分会设置为“00:00:00”。
• timestamp-exp 可以包括或省略小数秒。 timestamp-exp 可以包含任意位数的精度，但间隔类型 SQL_TSI_FRAC_SECOND 指定精确的三位精度。尝试指定小于或大于三位数的 SQL_TSI_FRAC_SECOND 可能会产生不可预知的结果。

范围和值检查

TIMESTAMPADD 对 %Library.TimeStamp 输入值执行以下检查：

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

示例

以下示例将 1 周添加到原始时间戳：

SELECT {fn TIMESTAMPADD(SQL_TSI_WEEK,1,'2017-12-20 12:00:00')}

image.png

以下示例将 5 个月添加到原始时间戳：

SELECT {fn TIMESTAMPADD(SQL_TSI_MONTH,5,'2022-12-20 12:00:00')}

image.png

以下示例将原始时间戳增加 45 分钟：

SELECT {fn TIMESTAMPADD(SQL_TSI_MINUTE,45,'2017-12-20 00:00:00')}

以下示例将原始时间戳减少 45 分钟：

SELECT {fn TIMESTAMPADD(SQL_TSI_MINUTE,-45,'2017-12-20 00:00:00')}