第六十章 SQL函数 GETUTCDATE

日期/时间函数，返回当前UTC日期和时间。

大纲

GETUTCDATE([precision])

参数

precision - 可选-一个正整数，指定时间精度为小数秒的位数。
默认值是0(没有小数秒);
这个默认值是可配置的。

描述

GETUTCDATE返回通用时间常数(UTC)日期和时间作为时间戳。由于UTC时间在地球上的任何地方都是相同的，不依赖于当地时区，也不受当地时差(如夏令时)的影响，因此当不同时区的用户访问同一数据库时，此函数对于应用一致的时间戳非常有用。

GETUTCDATE可以返回%TIMESTAMP数据类型格式(yyyy-mm-dd hh：mm：ss.ffff)或%PosiTime数据类型格式(编码的64位有符号整数)的时间戳。以下规则确定返回哪种时间戳格式：

如果当前UTC时间戳被提供给数据类型为%PosiTime的字段，则此时间戳值将以POSIXTIME数据类型格式返回。例如，WHERE PosixField=GETUTCDATE() or INSERT INTO MyTable (PosixField) VALUES (GETUTCDATE())。
如果当前UTC时间戳被提供给数据类型为%TIMESTAMP的字段，则此时间戳值以TIMESTAMP数据类型格式返回。其ODBC类型为TIMESTAMP，长度为16，精度为19。例如， WHERE TSField=GETUTCDATE() or INSERT INTO MyTable (TSField) VALUES (GETUTCDATE())。
如果当前UTC时间戳是在没有上下文的情况下提供的，则此时间戳值以TIMESTAMP数据类型格式返回。例如，SELECT GETUTCDATE()。

要更改默认日期时间字符串格式，请使用带有各种日期和时间选项的set option命令。

GETUTCDATE的典型用法是在SELECT语句SELECT列表或查询的WHERE子句中。在设计报表时，可以使用GETUTCDATE在每次生成报表时打印当前日期和时间。GETUTCDATE对于跟踪活动也很有用，比如记录事务发生的时间。

GETUTCDATE可用于创建表中以指定字段的默认值。

Other SQL Functions

GETUTCDATE以时间戳或POSIXTIME格式将当前UTC日期和时间作为时间戳返回。

所有其他TIMESTAMP函数都返回本地日期和时间：GETDATE、CURRENT_TIMESTAMP、NOW和SYSDATE以TIMESTAMP或POSIXTIME格式将当前本地日期和时间作为时间戳返回。

GETDATE和CURRENT_TIMESTAMP提供精度参数。

NOW，无参数CURRENT_TIMESTAMP和SYSDATE不提供精度参数；它们采用系统范围的默认时间精度。

CURDATE和CURRENT_DATE返回当前本地日期。CURTIME和CURRENT_TIME返回当前本地时间。这些函数使用日期或时间数据类型。这些函数都不支持精度。

TIMESTAMP数据类型以相同的格式存储和显示其值。POSIXTIME数据类型将其值存储为编码的64位有符号整数。时间和日期数据类型将它们的值存储为$HOROLOG格式的整数，并可以多种格式显示。

请注意，除GETUTCDATE外，所有 SQL时间戳函数都特定于本地时区设置。要获得通用的当前时间戳(独立于时区)，还可以使用ObjectScript $ZTIMESTAMP特殊变量。请注意，可以设置GETUTCDATE的精度；$ZTIMESTAMP始终返回精度3。

小数秒精度

GETUTCDATE最多可以返回9位精度。返回的精度位数是使用Precision参数设置的。可以使用以下内容配置精度参数的默认值：

使用TIME_PRECISION选项设置选项。
系统范围的$SYSTEM.SQL.Util.SetOption()方法配置选项DefaultTimePrecision。要确定当前设置，请调用$SYSTEM.SQL.CurrentSettings()，它显示默认的时间精度；默认值为0。
转到管理门户，依次选择系统管理、配置、SQL和对象设置、SQL。查看和编辑GETDATE()、CURRENT_TIME和CURRENT_TIMESTAMP的默认时间精度的当前设置。

为要返回的默认精度小数位数指定一个从0到9(包括0到9)的整数。默认值为0。返回的实际精度取决于平台；超出系统可用精度的精度位数将作为零返回。

小数秒始终被截断，而不是舍入到指定的精度。

示例

以下示例将当前日期和时间作为UTC时间戳和本地时间戳返回，两者均采用时间戳格式：

SELECT GETUTCDATE() AS UTCDateTime,
       GETDATE() AS LocalDateTime


2022/2/12 7:49:53   2022/2/12 15:49:53

下面的示例返回当前的UTC日期和时间，其中小数秒具有两位精度：

SELECT GETUTCDATE(2) AS DateTime

2022/2/12 7:50:19

下面的嵌入式SQL示例比较本地(特定于时区)和通用(独立于时区)时间戳：

ClassMethod GetDate()
{
    &sql(SELECT GETDATE(),GETUTCDATE() INTO :a,:b)
    if SQLCODE'=0 {
        w !,"Error code ",SQLCODE }
    else {
        w !,"Local timestamp is:  ",a
        w !,"UTC timestamp is:    ",b
        w !,"$ZTIMESTAMP is:      ",$ZDATETIME($ZTIMESTAMP,3,,3)
    }
}

DHC-APP> d ##class(PHA.TEST.SQLCommand).GetDate()

Local timestamp is:  2022-02-12 15:40:34
UTC timestamp is:    2022-02-12 07:40:34
$ZTIMESTAMP is:      2022-02-12 07:40:34.978

下面的示例将Orders表的选定行中的LastUpdate字段设置为当前UTC日期和时间。如果LastUpdate是数据类型%TIMESTAMP，则GETUTCDATE将当前UTC日期和时间作为ODBC时间戳返回；如果LastUpdate是数据类型%PosiTime，则GETUTCDATE将当前UTC日期和时间作为编码的64位有符号整数返回：

UPDATE Orders SET LastUpdate = GETUTCDATE()
  WHERE Orders.OrderNumber=:ord

在以下示例中，CREATE TABLE语句使用GETUTCDATE为OrderRcvd字段设置默认值：

CREATE TABLE Orders(
     OrderId     INT NOT NULL,
     ItemName    CHAR(40) NOT NULL,
     Quantity    INT NOT NULL,
     OrderRcvd   TIMESTAMP DEFAULT GETUTCDATE())