第九十六章 Caché 函数大全 $ZTIME 函数
验证时间，并将其从内部格式转换为指定的显示格式。
大纲
$ZTIME(htime,tformat,precision,erropt,localeopt)
$ZT(htime,tformat,precision,erropt,localeopt)
参数
- htime 可以指定为数值、变量名或表达式的内部系统时间。
- tformat 可选—一个整数值，指定要以何种格式返回时间值。
- precision 可选-一个数值，指定要用来表示时间的小数位数。如果省略，小数秒将被截断。
- erropt 可选-如果认为htime参数无效，则返回表达式。
- localeopt 可选-指定要使用的区域设置的布尔标志。为0时，当前区域设置确定时间分隔符以及用于格式化时间的其他字符、字符串和选项。为1时，ODBC区域设置确定这些字符、字符串和选项。ODBC区域设置不能更改；它用于格式化日期和时间字符串，这些字符串可以在做出不同国家语言支持(NLS)选择的Caché进程之间移植。默认值为0。
指定参数值之间的省略参数由占位符逗号表示。尾随占位符逗号不是必需的，但允许使用。逗号之间允许使用空格表示省略的参数。
描述
$ZTIME函数将内部系统时间(htime)转换为可打印格式，htime是以时间格式从特殊变量$HOROLOG或$ZTIMESTAMP指定的。如果不使用可选参数，时间将以“hh:mm:ss”格式返回；其中“hh”是24小时制中的小时,“mm”是分钟,“ss”是秒。否则，时间将以TF format和precision参数的值指定的格式返回。
参数
htime
该值表示自午夜以来经过的秒数。它是$HOROLOG值的第二个组成部分，可以使用$PIECE($HOROLOG,",",2)进行提取。 htime可以是整数，也可以是带有由precision指定的精度的小数位数的小数。
对于tformat值–1到4，htime有效值的整数部分必须在0到86399的范围内。（-0视为0。）此范围之外的值会产生错误。对于tformat值9和10，htime有效值还可以包括负数和大于86399的数。
tformat
支持的值如下：
| tformat | 描述 |
|---|---|
| -1 | 从当前语言环境的TimeFormat属性获取有效格式值，默认为1。这是默认行为，如果未指定tformat且localeopt未指定或为0。 |
| 1 | 以“ hh：mm：ss”的形式表示时间（24小时制）。 |
| 2 | 以“ hh：mm”的形式表示时间（24小时制）。 |
| 3 | 以“ hh：mm：ss [AM / PM]”的形式表示时间（12小时制）。 |
| 4 | 以“ hh：mm [AM / PM]”的形式表示时间（12小时制）。 |
| 9 | 对于MultiValue支持。与tformat 1（“ hh：mm：ss” 24小时制）相同，其数值介于0到86399之间。还接受负时间值和大于86399的时间值。 |
| 10 | 对于MultiValue支持。与tformat 2（“ hh：mm” 24小时制）相同，其数值介于0到86399之间。还接受负时间值和大于86399的时间值。 |
若要确定语言环境的默认时间格式，请调用GetFormatItem（）NLS类方法：。
DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimeFormat")
1
在12小时制的时钟格式中，早上和晚上由时间后缀表示，此处显示为AM和PM。若要确定语言环境的默认时间后缀，请调用以下NLS类方法：
DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("AM")
AM
DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("PM")
PM
tformat 9 and 10
提供了时间格式9和10以支持MultiValue。对于在ObjectScript允许范围内的所有内部时间值：0到86399，它们与tformats 1和2相同。与其他时间格式一样，-0被视为0。
时间格式9和10接受负数值，并返回相应的负时间值。 tformat 9返回一个负的htime作为“ -hh：mm：ss”（24小时制）。 tformat 10返回的负htime为“ -hh：mm”（24小时制）。对于时间格式10，“ – 59.9”返回“ –00：00”，“ – 60”返回“ –00：01”。
时间格式9和10接受大于86399的数值，并返回相应的时间。对于时间格式10，“ 86400”返回“ 24:00”，“ 400000”返回“ 111：06”。
时间格式9对于所有数值，返回整秒，并可选地返回小数秒。 precision参数指定小数秒的位数。
precision
该功能显示精确度参数中指定的小数秒后的小数秒数。例如，如果输入精度值3，则$ZTIME会将小数秒显示为小数点后三位。如果输入值9，$ZTIME将显示小数秒到小数点后九位。支持的值如下：
| Value | Description |
|---|---|
| -1 | 从当前语言环境的TimePrecision属性获取精度值，默认为0。这是默认行为，如果未指定precision。 |
| n | 大于或等于0的值导致将时间表示为n个小数位。 |
| 0 | 如果设置为0或默认值为0，则小数秒将被截断。 |
若要确定语言环境的默认时间精度，请调用GetFormatItem（）NLS类方法：
DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimePrecision")
0
erropt
此参数禁止显示与无效的htime值相关的错误消息。该函数将返回erropt指示的值，而不是生成错误<ILLEGAL VALUE>消息。
localeopt
此参数选择用户的当前语言环境定义（0）或ODBC语言环境定义（1）作为时间选项的来源。不能更改ODBC语言环境。它用于格式化日期和时间字符串，这些日期和时间字符串在做出了不同的国家语言支持（NLS）选择的Caché流程之间可移植。
ODBC语言环境时间定义如下：
- 时间格式默认为1。时间分隔符为“：”。时间精度为0（无小数秒）。
- AM和PM指示器分别为“AM”和“PM”。使用单词"Noon" and "Midnight"。
示例
要使用特殊变量$HOROLOG返回当前本地时间，必须使用$PIECE函数指定$HOROLOG的第二部分。以下内容以24小时制“13:55:11”返回时间：
DHC-APP>WRITE $ZTIME($PIECE($HOROLOG,",",2),1)
09:00:57
在下面的示例中，将htime设置为当前时间的$PIECE($HOROLOG,",",2)。这些示例说明如何使用$ZTIME的各种形式返回不同的时间格式。
以下示例在许多情况下以“13:28:55”的格式返回时间；但是，此格式取决于语言环境：
DHC-APP>SET htime=$PIECE($HOROLOG,",",2)
DHC-APP>WRITE $ZTIME(htime)
09:02:44
以下示例以“13：28：55.999”格式返回时间：
DHC-APP>SET htime=$PIECE($HOROLOG,",",2)
DHC-APP>WRITE $ZTIME(htime,1,3)
09:03:46.000
以下示例以“13：28：55.999999999”格式返回时间：
DHC-APP>SET htime=$PIECE($HOROLOG,",",2)
DHC-APP>WRITE $ZTIME(htime,1,9)
09:03:46.000000000
以下示例以“13:28”格式返回时间：
DHC-APP>SET htime=$PIECE($HOROLOG,",",2)
DHC-APP>WRITE $ZTIME(htime,2)
09:03
以下示例以“01:28:24 PM”格式返回时间：
DHC-APP>SET htime=$PIECE($HOROLOG,",",2)
DHC-APP>WRITE $ZTIME(htime,3)
09:03:46AM
以下示例以“01:28 PM”格式返回时间：
DHC-APP>SET htime=$PIECE($HOROLOG,",",2)
DHC-APP>WRITE $ZTIME(htime,4)
09:03AM
下面的示例以“13：45：56.021”的格式返回时间，即当前UTC时间，精度为小数点后三位：
DHC-APP>SET t=$ZTIME($PIECE($ZTIMESTAMP,",",2),1,3)
DHC-APP>WRITE "Current UTC time is ",t
Current UTC time is 01:05:47.548
注意
无效的参数值
- 如果指定了无效的tformat值，则会收到
<FUNCTION>错误。 - 如果htime指定的值超出0到86399（含）的允许范围，并且不提供
<ILLEGAL VALUE>错误值，则除9和10以外的所有tformat都会收到错误。
Decimal Delimiter
$ZTIME将使用当前语言环境的DecimalSeparator属性的值作为整数的整数和小数部分之间的分隔符。 DecimalSeparator的默认值为“。”；所有文档示例都使用此定界符。
若要确定语言环境的默认十进制分隔符，请调用GetFormatItem（）NLS类方法
DHC-APP> WRITE ##class(%SYS.NLS.Format).GetFormatItem("DecimalSeparator")
.
Time Delimiter
默认情况下，Caché使用当前语言环境的TimeSeparator属性的值来确定时间字符串的定界符。默认情况下，分隔符为“：”；所有文档示例都使用此定界符。
若要确定语言环境的默认时间分隔符，请调用以下NLS类方法：
DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimeSeparator")
:
时间后缀
默认情况下，Caché使用当前语言环境中的属性来确定其时间后缀的名称。对于$ZTIME，这些属性（及其相应的默认值）为：
- AM (“AM”)
- PM (“PM”)
本文档将始终对这些属性使用这些默认值。
若要确定语言环境的默认时间后缀，请调用以下NLS类方法：
DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("AM")
AM
DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("PM")
PM