第八十四章 Caché 函数大全 $ZDATEH 函数

验证日期并将其从显示格式转换为Caché内部格式。

大纲

$ZDATEH(date,dformat,monthlist,yearopt,startwin,endwin,mindate,maxdate,erropt,localeopt)
$ZDH(date,dformat,monthlist,yearopt,startwin,endwin,mindate,maxdate,erropt,localeopt)

参数

• date 该表达式的计算结果为显示格式的日期字符串。 $ZDATEH将此日期字符串转换为$HOROLOG格式。这可以是一个明确的日期（以各种格式指定），也可以是表示当前日期的字符串“T”或“t”。 “T”或“t”字符串可以选择包含有符号整数偏移量。例如，“T-7”表示当前日期之前的7天。见下面的日期。
• dformat 可选—一个整数代码，用于指定日期的日期格式选项。如果日期为“T”，则dformat必须为5、6、7、8、9或15。请参见下面的dformat。
• monthlist 可选-字符串或变量名称，用于指定一组月份名称。该字符串必须以分隔符开头，并且其12个条目必须由该分隔符分隔。请参阅下面的月列表。
• yearopt 可选—整数代码，用于指定是将年表示为两位数字还是四位数字的值。请参阅下面的yearopt。
• startwin 可选-滑动窗口的开始，在此期间，日期必须用两位数的年份表示。请参阅下面的startwin。
• endwin 可选-滑动窗口的末尾，其间用两位数的年份表示日期。请参阅下面的endwin。
• mindate 可选-有效日期日期范围的下限。指定为$HOROLOG整数日期计数，0表示1840年12月31日。可以指定为正整数或负整数。请参阅下面的提示。
• maxdate 可选-有效日期范围的上限。指定为$HOROLOG整数日期计数。请参阅下面的maxdate。
• erropt 可选-当hdate无效时返回的表达式。为该参数指定值将抑制与无效或超出范围的hdate值相关的错误代码。 $ZDATEH而不是发出错误消息，而是返回erropt。请参阅下面的错误提示。
• localeopt 可选-布尔值标志，用于指定dformat，monthlist，yearopt，minate和maxdate默认值以及其他日期特征（例如日期分隔符）使用的语言环境：localeopt = 0：当前的语言环境属性设置确定这些参数默认值。localeopt = 1：ODBC标准语言环境确定这些参数默认值。未指定localeopt：dformat值确定这些参数默认值。如果dformat = 3，则使用ODBC默认值。日文和回教日期dformatvalues使用其自己的默认值。对于所有其他dformat值，当前的语言环境属性设置用作默认值。请参阅下面的localeopt。

指定参数值之间的省略参数由占位符逗号指示。末尾的占位符逗号不是必需的，但允许使用。逗号之间允许有空格，以指示省略的参数。

描述

$ZDATEH函数验证指定的日期，并将其从$ZDATEH函数支持的任何格式转换为$HOROLOG格式。 $ZDATEH执行的确切操作取决于使用的参数。

简单的$ZDATEH格式

$ZDATEH（date）将MM / DD / [YY] YY格式的日期转换为$HOROLOG格式的第一个整数。 （$HOROLOG格式由两个整数组成：第一个整数是日期，第二个整数是时间。）在1900到1999之间的年份可以指定两位或四位数字。在1900年前的年份必须指定四位数字。或1999年以后。

可自定义的$ZDATEH格式

$ZDATEH（date，dformat，monthlist，yearopt，startwin，endwin，mindate，maxdate，erropt）将指定dformat的日期转换为$HOROLOG格式。 dformat，monthlist，yearopt，startwin，endwin，mindate，maxdate和erropt值与$ZDATE使用的值相同。但是，当使用5、6、7、8或9的dformat时，$ZDATEH会识别并转换为dformat代码1、2、3、5、6、7、8定义的任何外部日期格式的日期。和9（但不是dformat代码4。）它还识别特殊的相对日期格式，该格式由以字母T或t开头（表示“today”，）的字符串组成，可以选择在其后跟加号（+）或减号（-）号，以及当前日期之前或之后的整数天数。

参数

date

要转换为$HOROLOG格式的日期，指定为带引号的字符串。这可以是显式日期，也可以是隐式当前日期，由字符串“ T”或“ t”表示。

必须以dformat支持的格式之一指定显式日期。允许的格式取决于dformat参数。如果未指定dformat或为1、2、3或4，则仅允许使用一种日期格式。如果dformat为5、6、7、8、9或15，则允许使用多种日期格式。

如果dformat为5、6、7、8或9，则ZDATEH接受所有明确的欧洲日期格式。下面提供了有效日期格式的列表。请注意，dformat = 4不是有效的美国日期格式，因为$ZDATEH无法区分02/03/02（表示2002年2月3日）和欧洲02/03/02（表示2002年3月2日）。如果以不允许的格式指定日期或不存在的日期（例如2002年2月31日），则$ZDATEH会生成错误代码。 （$ZDATEH会检查leap年日期，允许2004年2月29日，但不允许2003年2月29日。）

在俄语，乌克兰语和捷克语语言环境中，日期必须用句点而不是斜杠指定，作为日期部分的分隔符：DD.MM.YYYY。

隐式日期指定为由字母“ T”或“ t”组成的字符串，表示当前日期（今天）。该字符串可以选择包括一个加号或减号以及一个整数，它们指定从当前日期开始偏移的天数。例如，“ t + 9”（当前日期之后的九天）或“ t-12”（当前日期之前的十二天）。仅当dformat为5、6、7、8、9或15时才允许使用隐式日期。唯一允许的隐式日期格式为“ T”（或“ t”）和“ T”（或“ t”），后跟一个符号和整数。如果指定非整数，算术表达式，不带符号的整数或不带符号的整数，则Caché会生成错误。允许使用“ T + 0”和“ T-0”，并返回当前日期。如果指定的偏移量会导致$HOROLOG日期超出有效日期范围，则Caché会生成<VALUE OUT OF RANGE>错误。

默认情况下，最早的有效日期是1840年12月31日（内部$HOROLOG表示形式为0）。默认情况下，日期限制为正整数，因为DateMinimum属性默认为0。如果当前语言环境的DateMinimum属性设置为更大或相等的负整数，则可以将更早的日期指定为负整数。有效的最低DateMinimum值的最低值是-672045，对应于0001年1月1日。Caché使用了多功的格里高利历，将格里高利历回溯到“ Year 1”，符合ISO 8601标准。这在一定程度上是因为公历是在不同国家的不同时间采用的。例如，许多欧洲大陆在1582年采用了它；大不列颠及美国在1752年采用了它。因此，在当地采用格里高利历之前的Caché日期可能与根据当时有效的当地历法记录的历史日期不符。有关1840年之前的日期的更多详细信息，请参考mindate参数。

dformat

返回日期的格式。有效值为：

其中

dformat Default

如果省略dformat或将其设置为-1，则dformat的默认值取决于localeopt参数和NLS DateFormat属性：

• 如果localeopt = 1，则dformat的默认值为ODBC格式。 monthlist，yearopt，mindate和maxdate参数的默认值也设置为ODBC格式。这与设置dformat = 3相同。
• 如果localeopt = 0或未指定，则dformat默认值来自NLS DateFormat属性。如果DateFormat = 3，则dformat的默认值为ODBC格式。但是，DateFormat = 3不会影响在当前NLS语言环境定义中指定的monthlist，yearopt，mindate和maxdate参数默认值。

若要确定语言环境的默认日期属性，请调用GetFormatItem（）NLS类方法：

DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("DateFormat"),!
4
 
DHC-APP> WRITE ##class(%SYS.NLS.Format).GetFormatItem("DateSeparator")
/

欧洲日期格式（dformat = 4，DD / MM / YYYY顺序）是许多（但不是全部）欧洲语言的默认格式，包括英式英语，法语，德语，意大利语，西班牙语和葡萄牙语（使用“ /”日期分隔符）字符），以及捷克语（csyw），俄语（rusw），斯洛伐克语（skyw），斯洛文尼亚语（svnw）和乌克兰语（ukrw）（使用“。” DateSeparator字符）。

dformat Settings

如果dformat为3（ODBC格式的日期），则ODBC格式的默认值也用于monthlist，yearopt，mindate和maxdate参数的默认值。日期分隔符将始终为“-”。当前的语言环境默认值将被忽略。

如果dformat是16或17（日语日期格式），则日期格式与语言环境设置无关。要使用日语格式的日期，必须具有UnicodeCaché实例。在8位Caché实例上，将dformat指定为16或17会导致<ERWIDECHAR>错误。

如果dformat为18、19、20或21（伊斯兰日期格式）并且未指定localeopt，则参数默认为伊斯兰默认值，而不是当前区域设置默认值。 monthlist参数默认为阿拉伯语月份名称，并用拉丁字符音译。 yearopt，mindate和maxdate参数默认为ODBC默认值。日期分隔符默认为回教默认值（空格），而不是ODBC默认值或当前区域设置DateSeparator属性值。如果localeopt = 0，则将当前语言环境属性默认值用于这些参数。如果localeopt = 1，则将ODBC默认值用于这些参数。

monthlist

该表达式可解析为月份名称或月份名称缩写的字符串，以分隔符分隔。 monthlist中的名称替换了来自当前语言环境的MonthAbbr属性的默认月份缩写值或来自MonthName属性的月份名称值。

仅当dformat为2、5、6、7、8、9、15、18或20时，monthlist才有效。如果dformat为任何其他值，$ZDATEH将忽略monthlist。

月列表字符串具有以下格式：

• 字符串的第一个字符是定界符（通常为空格）。同一分隔符必须出现在月份列表的第一个月份名称之前和每个月份名称之间。可以指定任何单字符定界符；必须在指定日期值的月，日和年部分之间指定此定界符，这就是为什么通常使用空格作为首选字符的原因。
• 月份名称字符串应包含十二个分隔值，分别对应于一月到十二月。可以指定多于或少于十二个月的名称，但是如果没有对应于日期月份的月份名称，则会生成<ILLEGAL VALUE>错误。

如果省略monthlist或将monthlist的值指定为-1，则$ZDATEH使用当前语言环境的MonthAbbr或MonthName属性中定义的月份名称列表，除非满足以下条件之一：如果localeopt = 1，则月份列表默认值为ODBC月列表（英文）。如果未指定localeopt且dformat为18或20（伊斯兰日期格式），则月列表默认值为伊斯兰月份列表（使用拉丁字母表示的阿拉伯名称），忽略MonthAbbr或MonthName属性值。

若要确定语言环境的默认月份名称和月份缩写，请调用GetFormatItem（）NLS类方法：

DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("MonthAbbr"),!
 Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
 
DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("MonthName"),!
 January February March April May June July August September October November December

yearopt

一个数字代码，指定是用两位数字还是四位数字表示年份。有效值为：

如果省略yearopt或将yearopt值指定为-1，则$ZDATEH使用当前语言环境的YearOption属性，除非满足以下条件之一：如果localeopt = 1，则yearopt默认为ODBC year选项。如果localeopt = 0或未指定，并且dformat是18、19、20或21（伊斯兰日期格式），则yearopt的默认值为ODBC year选项（4位数字的年份）；否则，默认值为ODBC年。回教日期将忽略YearOption属性值。

startwin

一个数字值，指定滑动窗口的开始，在此期间，日期必须用两位数的年份表示。当使用的yearopt为3或5时，必须提供startwin。startwin不适用于任何其他yearopt值。

当yearopt = 3时，startwin是$HOROLOG日期格式的绝对日期，指示滑动窗口的开始日期。

当yearopt = 5时，startwin是一个数字值，表示以当前年之前的年数表示的滑动窗口的开始年。滑动窗口始终在startwin中指定的一年的第一天（1月1日）开始。

endwin

一个数字值，指定滑动窗口的结束，在此期间内，日期用两位数的年份表示。当yearopt为3或5时，可以选择提供endwin。endwin不适用于任何其他yearopt值。

当yearopt = 3时，endwin是$HOROLOG日期格式的绝对日期，指示滑动窗口的结束日期。

当yearopt = 5时，endwin是一个数字值，它表示滑动窗口的结束年份，表示为当前年份之后的年数。滑动窗口始终在endwin或隐含的结束年份（如果省略endwin）中指定的年份的最后一天（12月31日）结束。

如果省略endwin（或指定为-1），则有效滑动窗口将为100年。 endwin值为-1是一种特殊情况，即使较高和较低endwin值返回错误，也总是返回日期值。因此，最好在指定100年窗口时省略endwin，并避免使用负endwin值。

如果同时提供startwin和endwin，则它们指定的滑动窗口的持续时间不得超过100年。

mindate

该表达式指定有效日期范围的下限（含）。可以指定为$HOROLOG整数日期计数（例如，2013年1月1日表示为62823）或$HOROLOG字符串值。可以包括或省略$HOROLOG日期的时间部分（例如“ 62823,43200”），但仅解析主意的日期部分。指定日期值早于mindate会生成<VALUE OUT OF RANGE>错误。

以下是受支持的提示值：

• 正整数：最常见的正念指定为正整数，以建立最早的允许日期为1840年12月31日之后的某个日期。例如，正念21550会将最早的允许日期建立为1900年1月1日。最高有效值是2980013（9999年12月31日）。
• 0：指定最小日期为1840年12月31日。这是DateMinimum属性的默认值。
• 负整数-2或更大：指定从1840年12月31日开始倒数的最小日期。例如，记号-14974将建立最早的允许日期为1800年1月1日。负记号值仅在DateMinimum属性为时才有意义。当前语言环境已设置为等于或大于负数。最低有效值为-672045。
• 如果省略（或指定为-1），则mindate默认为当前语言环境的DateMinimum属性值，除非以下条件之一为真：如果localeopt = 1，则minindate默认值为0。如果localeopt未指定且dformat = 3，预设值是0。如果未指定localeopt并且dformat是18、19、20或21（伊斯兰日期格式），则预设值是0。

可以获取并设置DateMinimum属性，如下所示：

/// d ##class(PHA.TEST.Function).ZDATEH()
ClassMethod ZDATEH()
{
  SET min=##class(%SYS.NLS.Format).GetFormatItem("DateMinimum")
  WRITE "initial DateMinimum value is ",min,!
Permit18thCenturyDates
  SET x=##class(%SYS.NLS.Format).SetFormatItem("DateMinimum",-51498)
  SET newmin=##class(%SYS.NLS.Format).GetFormatItem("DateMinimum")
  WRITE "set DateMinimum value is ",newmin,!!
RestrictTo19thCenturyDates
  WRITE $ZDATEH("05/29/1805",1,,,,,-14974),!!
ResetDateMinimumToDefault
  SET oldmin=##class(%SYS.NLS.Format).SetFormatItem("DateMinimum",min)
  WRITE "reset DateMinimum value from ",oldmin," to ",min
}

DHC-APP> d ##class(PHA.TEST.Function).ZDATEH()
initial DateMinimum value is 0
set DateMinimum value is -51498
 
-13000
 
reset DateMinimum value from -51498 to 0

可以指定有或没有maxdate的提示。指定大于maxdate的提示时，会产生<ILLEGAL VALUE>错误。

maxdate

该表达式指定有效日期范围的上限（含）。可以指定为$HOROLOG整数日期计数（例如1/1/2100表示为94599）或$HOROLOG字符串值。可以包括或省略$HOROLOG日期的时间部分（例如“94599,43200”），但仅会解析maxdate的日期部分。

如果省略了maxdate或将其指定为-1，则最大日期限制是从当前语言环境的DateMaximum属性获取的，该属性默认为$HOROLOG日期部分的最大允许值：2980013（对应于9999年12月31日） ）。但是，DateMaximum属性的应用由localeopt设置控制。当localeopt = 1（dformat = 3的默认值）时，最大的默认日期是ODBC值（2980013），与当前的语言环境设置无关。回教日期格式也采用ODBC默认值。泰文日期格式（dformat = 13）的最大日期为BE 31/12/9999，对应于$HOROLOG 2781687。

指定大于maxdate的date会产生<VALUE OUT OF RANGE>错误。

如果指定的最大日期大于2980013，则会产生<ILLEGAL VALUE>错误。

可以指定maxdate或不指定。指定的maxdate小于mindate会生成<ILLEGAL VALUE>错误。

erropt

为该参数指定值将抑制与无效或超出范围日期值相关的<ILLEGAL VALUE> or <VALUE OUT OF RANGE>错误。 $ZDATEH函数返回错误值，而不是生成或错误。

Caché对日期执行标准的数字评估，该评估必须评估为mindate / maxdate范围内的整数。因此，7，“ 7”，+ 7、0007、7.0，“ 7 draw”和--7的值均等于同一日期值：01/07/1841。默认情况下，大于2980013或小于0的值会生成错误。分数值会产生<ILLEGAL VALUE>错误。非数字字符串（包括空字符串）的值为0，因此返回$HOROLOG初始日期：12/31/1840。

erropt参数仅抑制由于无效或超出日期范围值而生成的错误。无论是否提供错误提示，由于其他参数无效或超出范围而产生的错误将始终产生错误。例如，当$ ZDATEH指定一个滑动窗口，其中endwin早于startwin时，总是生成错误。同样，当maxdate小于mindate时，会生成<ILLEGAL VALUE>错误。

localeopt

此布尔值参数将用户的当前语言环境定义或ODBC语言环境定义指定为语言环境指定的参数dformat，monthlist，yearopt，minate和maxdate的默认值的来源：

• 如果localeopt = 0，则所有这些参数均采用当前的语言环境定义默认值。
• 如果localeopt = 1，则所有这些参数均采用ODBC默认值。
• 如果未指定localeopt，则dformat参数确定这些参数的默认值。如果dformat = 3，则使用ODBC默认值。如果dformat为18、19、20或21，则无论当前语言环境定义如何，都使用回教日期格式默认值。对于所有其他dformat值，使用当前的语言环境定义默认值。

不能更改ODBC语言环境。它用于格式化日期字符串，这些日期字符串在选择了不同的国家语言支持（NLS）的Caché流程之间可移植。如果localeopt = 1，则ODBC区域设置日期定义如下：

• 日期格式默认为3。因此，如果dformat未定义或为-1，则使用日期格式3。
• 日期分隔符默认为“ /”。但是，日期格式默认为3，该格式始终使用“-”作为日期分隔符。
• Year选项默认为4位数字。
• 最小和最大日期：0和2980013（$HOROLOG日期计数）。
• 使用英语月份名称，月份缩写，工作日名称和工作日缩写。

示例

下面的示例返回$HOROLOG日期为1983年6月12日：

DHC-APP>WRITE $ZDATEH("06/12/83")
52204

以下示例返回1902年6月12日的$HOROLOG日期：

DHC-APP>WRITE $ZDATEH("06/12/02")
22619

注意：默认情况下，两位数年份被认为是20世纪的日期。对于21世纪的日期，请指定四位数的年份，或者通过指定yearopt，startwin和endwin参数来更改两位数的滑动窗口。也可以为区域设置此滑动窗口。

以下示例显示dformat参数如何用于允许多种日期输入格式：

/// d ##class(PHA.TEST.Function).ZDATEH1()
ClassMethod ZDATEH1()
{
    WRITE !,$ZDATEH("November 2, 1954",5)
    WRITE !,$ZDATEH("Nov 2, 1954",5)
    WRITE !,$ZDATEH("Nov. 2 1954",5)
    WRITE !,$ZDATEH("11/2/1954",5)
    WRITE !,$ZDATEH("11.02.54",5)
    WRITE !,$ZDATEH("11 02 1954",5)
}

DHC-APP>d ##class(PHA.TEST.Function).ZDATEH1()
 
41578
41578
41578
41578
41578
41578

在以下示例中，假设当前日期是2007年1月16日：

  WRITE $HOROLOG

返回60646,37854，其第一个整数是当前日期（第二个整数是当前时间，以秒为单位）。

下一个示例使用“T”日期返回今天的日期（此处为2007年1月16日）：

DHC-APP>WRITE $ZDATEH("T",5)
65694

下面的示例返回当前日期，其偏移量为正2天和负2天：

DHC-APP>WRITE !,$ZDATEH("T+2",5)
 
65696
DHC-APP>WRITE !,$ZDATEH("T-2",5)
 
65692

最后一个示例说明，如果未指定年份，则$ZDATEH假定为当前年份（在本例中为2007）：

DHC-APP>WRITE $ZDATEH("25 Nov",5)
65708

注意

$ZDATEH的值无效

在以下情况下，收到<FUNCTION> 错误：

• 如果指定了无效的dformat代码（-1、1、2、3、4、5、6、7、8、9或15以外的整数，零或非整数值）
• 如果指定了无效的Yearopt代码（小于-1或大于6的整数，零值或非整数值）
• 如果在yearopt为3或5时未指定startwin值

在以下情况下，会收到<ILLEGAL VALUE>错误：

• 如果为任何日期单位（天，月或年）指定了无效的值。如果指定，则返回<ILLEGAL VALUE>.错误值，而不是发出。
• 如果为ODBC日期中的任何日期单位（日，月或年）指定多余的前导零。例如，可以将2007年2月3日表示为“ 2007–2–3”或“ 2007–02–03”，但会收到“ 2007–002–03”的<ILLEGAL VALUE>.。如果指定，则返回<ILLEGAL VALUE>.错误值，而不是发出。
• 如果给定的月份数大于monthlist中的月份数。
• 如果maxdate小于主意。
• 如果endwin小于startwin。
• 如果startwin和endwin指定滑动时间窗口，其持续时间大于100年。

在以下情况下，收到<VALUE OUT OF RANGE>错误：

• 如果指定的日期（或“T”的偏移量）早于1840年12月31日或晚于9999年12月31日，并且不提供错误值
• 如果指定了其他有效日期（或“T”的偏移量），则超出了mindate和maxdate的范围，并且不提供错误的值。

dformat 5到9和15的可接受日期格式

$ZDATEH dformat日期格式5到9接受任何明确的美国格式日期值。 $ZDATEH dformat日期格式15接受任何明确的欧洲格式日期值。如果指定的日期不包含年份，则这些日期格式将采用当前年份。

支持以下格式：

MMDD不是实现的格式。

使用$ZDATEH代替实用程序

需要在$ZDATEH函数和date实用程序之间进行选择时，请记住以下几点：

• 可以使用$ZDATEH函数代替％DATE和％DI实用程序的现有入口点。
• $ZDATEH和$ZDATE比调用％DATE，％DI或％DO.DATE，％DI或％DO的入口点快得多。