第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_SECONDSQL_TSI_SECONDSQL_TSI_MINUTESQL_TSI_HOURSQL_TSI_DAYSQL_TSI_WEEKSQL_TSI_MONTHSQL_TSI_QUARTERSQL_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范围内。超出此范围递增或递减返回 。 - 小于
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')}
以下示例将 5 个月添加到原始时间戳：
SELECT {fn TIMESTAMPADD(SQL_TSI_MONTH,5,'2022-12-20 12:00:00')}
以下示例将原始时间戳增加 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')}
