第八十三章 Caché 函数大全 $ZDATE 函数

第八十三章 Caché 函数大全 $ZDATE 函数

验证日期并将其从内部格式转换为指定的显示格式。

大纲

$ZDATE(hdate,dformat,monthlist,yearopt,startwin,endwin,mindate,maxdate,erropt,localeopt)
$ZD(hdate,dformat,monthlist,yearopt,startwin,endwin,mindate,maxdate,erropt,localeopt)

参数

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

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

描述

$ZDATE函数将内部存储格式（$HOROLOG格式）的指定日期转换为几种备用日期显示格式之一。 $ZDATE返回的值取决于使用的参数。

简单的$ZDATE格式

$ZDATE（hdate）是$ZDATE的最基本形式，它以与指定hdate对应的显示格式返回日期。 hdate是自1840年12月31日起经过的天数的整数。范围从0到2980013（从12/31/1840到12/31/9999）。

默认情况下，$ZDATE（hdate）用两位数字表示1900年到1999年之间的年份。它用四位数字表示1900年之前或1999年之后的年份。例如：

/// d ##class(PHA.TEST.Function).ZDATE()
ClassMethod ZDATE()
{
    WRITE $ZDATE(21400),!  ; returns 08/04/1899
    WRITE $ZDATE(50000),!  ; returns 11/23/77
    WRITE $ZDATE(60000),!  ; returns 04/10/2005
    WRITE $ZDATE(0),!      ; returns 12/31/1840
}

DHC-APP> d ##class(PHA.TEST.Function).ZDATE()
08/04/1899
11/23/77
04/10/2005
12/31/1840

当提供$HOROLOG日期到$ZDATE时，仅使用日期部分。以$HOROLOG格式，日期和时间显示为两个整数，中间用逗号分隔。遇到逗号（非数字字符）时，$ZDATE会忽略字符串的其余部分。在以下示例中，$ZDATE使用$HOROLOG格式值返回04/10/2005和当前日期：

DHC-APP>WRITE !,$ZDATE("60000,12345")
 
04/10/2005
DHC-APP>WRITE !,$ZDATE($HOROLOG)
 
11/06/2020

可自定义日期默认

在Caché启动时，默认日期格式被初始化为dformat = 1，这是带有斜杠日期分隔符（MM / DD / [YY] YY）的美国日期格式。要将此格式和其他默认格式设置为当前语言环境的值，请设置以下全局变量：SET ^SYS("NLS","Config","LocaleFormat")=1。这会将所有进程的所有格式默认值设置为当前语言环境值。这些默认值将一直保留到更改此全局变量为止。

注意：本节介绍未定义localeopt或将其设置为0时应用的用户语言环境定义。当localeopt = 1时，$ZDATE使用预定义的ODBC语言环境。

可以使用NLS（国家语言支持）覆盖当前进程的格式默认值。可以将所有格式的默认值更改为指定语言环境的值，也可以更改单个格式的值。

• 要将所有格式默认值（包括日期格式默认值）设置为指定语言环境的属性，请调用以下方法调用：SET fmt=##class(%SYS.NLS.Format).%New("lname") ，其中lname是所需语言环境的NLS名称。 （例如，deuw =German，espw = Spanish，fraw = French，ptbw = Brazilian Portuguese，rusw = Russian，jpnw = Japanese。在管理门户中找到完整的语言环境列表：System，Configuration，NLS Settings，Locale Definitions ）要将这些默认设置设置为当前语言环境的属性，请指定lname为“ current”或空字符串（“”）。
• 要将默认日期格式设置为指定的dformat格式，请调用SetFormatItem（）方法：SET rtn=##class(%SYS.NLS.Format).SetFormatItem("DateFormat",n)，其中n是希望将其设为默认值的dformat值。

下面的示例演示如何将所有格式默认设置为俄语语言环境，以默认格式（俄语）从$ZDATE返回日期，然后将格式默认值重置为当前语言环境默认值。请注意，俄语语言环境使用句点而不是斜杠作为日期部分分隔符：

/// d ##class(PHA.TEST.Function).ZDATE1()
ClassMethod ZDATE1()
{
    IF $SYSTEM.Version.IsUnicode() {
        WRITE !,$ZDATE($HOROLOG)
        SET fmt=##class(%SYS.NLS.Format).%New("rusw")
        WRITE !,$ZDATE($HOROLOG)
        SET fmt=##class(%SYS.NLS.Format).%New("current")
        WRITE !,$ZDATE($HOROLOG)
    } ELSE {
        WRITE "此示例需要Caché的Unicode安装"
    }
}

DHC-APP>d ##class(PHA.TEST.Function).ZDATE1()
 
11/06/2020
06.11.2020
11/06/2020

下面的示例演示如何设置各个格式的默认值。第一个$ZDATE以默认格式返回日期。第一个SetFormatItem（）方法将默认值更改为dformat = 4或欧洲日期格式（DD / MM / [YY] YY），如第二个$ZDATE所示。第二个SetFormatItem（）方法更改日期分隔符的默认值（这会影响dformat -1、1、4和15）。在此示例中，日期分隔符字符设置为点（“。”），如第三个$ZDATE所示。最后，该程序将还原原始日期格式值：

/// d ##class(PHA.TEST.Function).ZDATE2()
ClassMethod ZDATE2()
{
InitialVals
    SET fmt=##class(%SYS.NLS.Format).GetFormatItem("DateFormat")
    SET sep=##class(%SYS.NLS.Format).GetFormatItem("DateSeparator")
    WRITE !,$ZDATE($HOROLOG)
ChangeVals
    SET x=##class(%SYS.NLS.Format).SetFormatItem("DateFormat",3)
    WRITE !,$ZDATE($HOROLOG)
    SET y=##class(%SYS.NLS.Format).SetFormatItem("DateSeparator",".")
    WRITE !,$ZDATE($HOROLOG)
RestoreVals
    SET x=##class(%SYS.NLS.Format).SetFormatItem("DateFormat",fmt)
    SET y=##class(%SYS.NLS.Format).SetFormatItem("DateSeparator",sep)
    WRITE !,$ZDATE($HOROLOG)
}

DHC-APP>d ##class(PHA.TEST.Function).ZDATE2()
 
11/06/2020
2020-11-06
2020-11-06
11/06/2020

参数

hdate

内部日期格式值，表示自1840年12月31日以来经过的天数。默认情况下，它必须是0到2980013之间的整数。可以将hdate指定为数字，字符串文字或表达式。 Caché将hdate转换为规范形式。它会在其第一个非数字字符处截断数字字符串（例如$HOROLOG值）。它将非数字字符串评估为整数0。不解析为整数的浮点数将生成错误。

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

CachéSQL支持Caché配置设置ZDateNULL。

• 当ZDateNULL = OFF（默认值）时，无效和超出范围的hdate值的行为以及由此产生的错误如erropt参数中所述。
• 当ZDateNULL = ON时，无效和超出范围的hdate值的行为以及由此产生的错误如下：
  • 有效日期范围是从1到94232（含），包括从01/01/1841到12/30/2098的日期。该日期范围是为具有三个或更少参数的任何$ZDATE函数调用设置的。如果$ZDATE函数调用具有三个以上的参数，则有效的日期范围是从mindate和maxdate参数（如果指定）中获取的，或者从为当前语言环境建立的日期范围中获取。
  • 无效的日期值将返回空字符串（“”），而不是发出错误。

dformat

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

值	含义
1	MM/DD/[YY]YY(07/01/97或03/27/2002)-美国数字格式。日期分隔符(/或.)。取自当前区域设置。
2	DD Mmm [ YY ]YY (01 Jul 97 or 27 Mar 2002)
3	YYYY-MM-DD (1997-07-01 or 2002-03-27) ODBC格式。默认情况下，此格式与当前的语言环境设置（localeopt = 1）无关，从而以ODBC标准交换格式指定日期。要以这种格式使用当前的日期语言环境设置，请设置localeopt = 0。
4	DD/MM/[YY]YY (01/07/97 or 27/03/2002) 欧洲数字格式。日期分隔符（/或。）取自当前的语言环境设置。
5	Mmm [D]D, YYYY (Jul 1, 1997 or Mar 27, 2002)
6	Mmm [D]D YYYY (Jul 1 1997 or Mar 27 2002)
7	Mmm DD [YY]YY (Jul 01 97 or Mar 27 2002)
8	YYYYMMDD (19970701 or 20020327) 数值格式
9	Mmmmm [D]D, YYYY (July 1, 1997 or March 27, 2002)
10	W（2）-一周中的天数，从0（星期日）到6（星期六）编号。与$SYSTEM.SQL.DAYOFWEEK（）方法进行比较。
11	Www（Tue）-缩写的日期名称
12	Wwwwww (Tuesday)）—全天名称
13	[D]D/[M]M/YYYY (1/7/2549 or 27/11/2549) 泰文日期格式。除无前导零外，日和月与欧洲用法相同。该年是佛教时代（BE）年，通过在公历年中增加543年而得出。
14	nnn（354）-年的天数
15	DD/MM/[YY]YY (01/07/97 or 27/03/2002) 欧洲格式（与dformat = 4相同）。日期分隔符（/或。）取自当前的语言环境设置。
16	YYYYc[M]Mc[D]Dc —日文日期格式。年，月和日的编号与其他日期格式相同；前导零被省略。在年，月和日编号之后插入“年”，“月”和“日”的日语字符（在此处显示为c）。这些字符是Year = $CHAR（24180），Month = $CHAR（26376）和Day = $CHAR（26085）。
17	YYYYc [M]Mc [D]Dc —日文日期格式。与dformat 16相同，除了在“ year”和“ month”日语字符之后插入空格。
18	[D]D Mmmmm YYYY - 具有完整月份名称的表格回历（伊斯兰）日期格式。省略了日期前导零。包括年份前导零。教堂日期-445031（公元07/19/0622）= 1穆罕默德0001。
19	[D]D [M]M YYYY 带月号的表格回历（伊斯兰）日期格式。日和月的前导零被省略；包括年份前导零。教堂日期-445031（西元07/19/0622）= 1 1 0001。
20	[D]D Mmmmm YYYY —观察到的回历（伊斯兰）日期格式，并带有完整的月份名称。默认为表格回历（dformat 18）。要覆盖表格计算，请使用％Calendar.Hijri类添加对新月新月的观测。
21	[D]D [M]M YYYY —观察到的回历（伊斯兰）日期格式和月数。默认为表格回历（dformat 19）。要覆盖表格计算，请使用％Calendar.Hijri类添加对新月新月的观测。
-1	从用户的语言环境（如果localeopt = 0或未定义）或从ODBC语言环境（默认为dformat = 3）获取有效的dformat值。如果dformat是从用户的语言环境中获取的，则它是fmt.DateFormat的值，其中fmt是与当前进程关联的## class（％SYS.NLS.Format）的实例。如果不指定dformat，则这是默认行为。

其中

语法	含义
YYYY	YYYY是四位数的年份。 [YY]如果hdate落在活动窗口内达两位数年份，则YY为两位数年份；否则为四位数年份。
MM	两位数的月份：01到12。[M] M表示在月份1到9中省略了前导零。
DD	两位数的日期：01到31。[D] D表示第1到9天省略了前导零。
Mmm	从当前语言环境的MonthAbbr属性中提取的月份缩写。可以从指定为$ ZDATE的monthlist参数的可选列表中提取备用月份的缩写（或任何长度的名称）。 MonthAbbr的默认值是：“Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec”
Mmmmm	由当前语言环境的MonthName属性指定的月份的全名。默认值为：“January February March ... November December”
W	数字0-6表示星期几：Sunday=0, Monday=1, Tuesday=2, etc.
Www	工作日名称缩写，由当前语言环境的WeekdayAbbr属性指定。默认值为：“Sun Mon Tue Wed Thu Fri Sat”
Wwwwww	由当前语言环境的WeekdayName属性指定的工作日全名。默认值为：“Sunday Monday Tuesday ... Friday Saturday”
nnn	指定年份的天数，始终为三位数，如有必要，前导零。值是001到365（leap年时是366）。

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类方法：

WRITE ##class(%SYS.NLS.Format).GetFormatItem("DateFormat")

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

dformat Settings

如果dformat为3（ODBC日期格式），则ODBC格式默认值也用于monthlist，yearopt，minate和maxdate参数默认值。当前的语言环境默认值将被忽略。

如果dformat为-1、1、4、13或15（数字日期格式），则$ZDATE使用当前语言环境的DateSeparator属性的值作为月，日和年之间的分隔符。当dformat为3时，使用ODBC日期分隔符（“-”）。对于所有其他dformat值，空格用作日期分隔符。 DateSeparator的英语默认值为“ /”，并且所有文档都使用此分隔符。

如果dformat是11或12（日期名称）且localeopt = 0或未指定，则日期名称值来自当前的语言环境属性。如果localeopt = 1，则日期名称来自ODBC语言环境。若要确定语言环境的默认工作日名称和工作日缩写，请调用以下NLS类方法：

  WRITE ##class(%SYS.NLS.Format).GetFormatItem("WeekdayName"),!
  WRITE ##class(%SYS.NLS.Format).GetFormatItem("WeekdayAbbr"),!

如果dformat为16或17（日语日期格式），则返回的日期格式与语言环境设置无关。可以从任何UnicodeCaché实例返回日语格式的日期。在8位Caché实例上，将dformat指定为16或17会导致错误。

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

monthlist

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

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

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

• 字符串的第一个字符是定界符（通常为空格）。同一分隔符必须出现在月份列表的第一个月份名称之前和每个月份名称之间。可以指定任何单字符定界符；该分隔符出现在返回日期值的月，日和年部分之间，这就是为什么通常使用空格作为首选字符的原因。

• 月份名称字符串应包含十二个分隔值，分别对应于一月到十二月。可以指定多于或少于十二个月的名称，但是如果没有对应于hdate中月份的月份名称，则会生成错误。

如果省略monthlist或将monthlist值指定为-1，则$ZDATE使用在当前语言环境的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

以下示例列出了月份名称的默认语言环境，将此过程的语言环境更改为俄语语言环境，然后列出了俄语月份名称并显示了带有俄语月份名称的当前日期。然后，它将语言环境默认值恢复为当前语言环境，并再次显示当前日期，这次是默认的月份名称。

/// d ##class(PHA.TEST.Function).ZDATE4()
ClassMethod ZDATE4()
{

    WRITE ##class(%SYS.NLS.Format).GetFormatItem("MonthName"),!
    SET fmt=##class(%SYS.NLS.Format).%New("rusw")
    WRITE fmt.MonthName,!
    WRITE $ZDATE($HOROLOG,9),!
    SET fmt=##class(%SYS.NLS.Format).%New()
    WRITE $ZDATE($HOROLOG,9)
}

yearopt

使用dformat值1、2、4、7或15，这是一个整数代码，用于指定将年显示为两位数值的时间窗口。对于所有其他dformat值，将忽略yearopt。有效的yearopt值为：

值	描述
-1	从当前语言环境的YearOption属性获取有效的yearopt值，该值默认为0。如果未指定yearopt，则这是默认行为。
0	除非有效的过程特定的滑动窗口（通过％DATE实用程序建立），否则用两位数的年份表示20世纪日期（1900年至1999年），而所有其他日期则用4位年份表示。如果这样的窗口有效，则仅将落在滑动窗口中的那些日期表示为两位数年份，而将所有其他日期表示为四位数年份。
1	代表20世纪的日期用两位数的年份表示，其他所有日期用4位数的年份表示。
2	用两位年份表示所有日期。
3	这些日期用两位数的年份表示由startwin和（可选）endwin定义的滑动时间范围内的日期。用四位数字的年份表示所有其他日期。当yearopt = 3时，startwin和endwin是$HOROLOG格式的绝对日期。
4	用四位数年份表示所有日期。 ODBC年选项。
5	用两位数年份表示所有日期，它们都落在startwin和（可选）endwin定义的滑动时间窗口内。用四位数字的年份表示所有其他日期。当yearopt = 5时，startwin和endwin是相对年份。
6	用两位数字年份代表当前世纪的所有日期，而用四位数年份代表所有其他日期。

若要确定语言环境的默认年份选项，请调用GetFormatItem（）NLS类方法：

DHC-APP> WRITE ##class(%SYS.NLS.Format).GetFormatItem("YearOption")
0

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

解决2000年以前的年份是2位数

DHC-APP>w $Zd($h-2000)
05/22/2015
DHC-APP>w $Zd($h-20000)
02/08/66
DHC-APP>w $Zd($h-20000,,,4)
02/08/1966

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中指定的当年12月31日结束。如果未指定endwin，则默认为startwin后100年的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的日期部分。早于mindate指定hdate值会生成错误。

以下是受支持的提示值：

• 正整数：最常见的正念指定为正整数，以建立最早的允许日期为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).ZDATE5()
ClassMethod ZDATE5()
{
 SET min=##class(%SYS.NLS.Format).GetFormatItem("DateMinimum")
  WRITE "初始DateMinimum值为 ",min,!
Permit18thCenturyDates
  SET x=##class(%SYS.NLS.Format).SetFormatItem("DateMinimum",-51498)
  SET newmin=##class(%SYS.NLS.Format).GetFormatItem("DateMinimum")
  WRITE "设置DateMinimum值为 ",newmin,!!
RestrictTo19thCenturyDates
  WRITE $ZDATE(-13000,1,,,,,-14974),!!
ResetDateMinimumToDefault
  SET oldmin=##class(%SYS.NLS.Format).SetFormatItem("DateMinimum",min)
  WRITE "从重置DateMinimum值",oldmin," to ",min
}

DHC-APP>d ##class(PHA.TEST.Function).ZDATE5()
初始DateMinimum值为 0
设置DateMinimum值为 -51498
 
05/29/1805
 
从重置DateMinimum值-51498 to 0

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

ODBC Date Format (dformat 3)

DateMinimum属性的应用由localeopt设置控制。当localeopt = 1（dformat = 3的默认值）时，无论当前的区域设置如何，最小日期均为0。因此，采用ODBC格式（dformat = 3），可以使用以下命令指定1840年12月31日之前的日期：

• 指定早于指定日期的提示：

DHC-APP> WRITE $ZDATE(-30,3,,,,,-365)
1840-12-01

• 指定早于指定日期的DateMinimum属性值，并设置localeopt = 0：

DHC-APP> DO ##class(%SYS.NLS.Format).SetFormatItem("DateMinimum",-365)
 
DHC-APP>WRITE $ZDATE(-30,3,,,,,,,,0)
1840-12-01

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）的最大日期是$HOROLOG 2781687，对应于BE 31/12/9999。

指定大于maxdate的hdate会产生错误。

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

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

erropt

为该参数指定值将抑制与无效或超出范围的hdate值相关的 错误。 $ZDATE函数返回错误值，而不是生成或错误。

• 验证：Caché对hdate执行规范的数字转换。 hdate字符串的解析在第一个非数字字符处停止。因此，hdate字符串（例如64687AD）与64687相同。非数字日期（包括空字符串）的计算结果为0。因此，空字符串hdate返回$HOROLOG初始日期：1840年12月31日。但是，如果hdate不会计算为整数（包含非零小数），它会生成错误。
• 范围：hdate必须计算为mindate / maxdate范围内的整数。默认情况下，大于2980013或小于0的日期值会生成错误。通过将mindate设置为负数，可以扩展1840年12月31日之前的有效日期范围。但是，对于dformat 18、19、20或21（回教伊斯兰历）日期，-445031之前的任何日期都会生成即使将mindate设置为较早的日期，也会出现错误。

erropt参数仅抑制由于hdate的无效值或超出范围的值而生成的错误。无论是否提供错误提示，由于其他参数无效或超出范围而产生的错误将始终产生错误。

例如，当$ZDATE指定一个滑动窗口，其中endwin早于startwin时，总是生成错误。同样，当maxdate小于mindate时，会生成错误。

ZDateNull的无效日期处理

可以使用ZDateNull设置$ZDATE的行为，为hdate赋予无效值时。若要为当前进程设置此行为，请使用％SYSTEM.Process类的ZDateNull（）方法。可以通过设置Config.Miscellaneous类的ZDateNull属性来建立系统范围的默认行为。 $ZDATE可以发出错误，也可以返回空值。

系统范围的默认行为是可配置的。转到管理门户，选择“系统”，“配置”，“兼容性设置”。查看和编辑ZDateNull的当前设置。默认值为“false”，表示$ZDATE返回错误。

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日期计数）。
• 使用英语月份名称，月份缩写，工作日名称和工作日缩写。

示例

日期格式示例

下面的示例说明$ZDATE如何返回当前日期的各种dformat格式。 yearopt采用默认值。当然，日期分隔符以及月份和星期几的名称和缩写取决于语言环境。本示例使用当前的用户区域设置定义：

/// d ##class(PHA.TEST.Function).ZDATE6()
ClassMethod ZDATE6()
{
    WRITE $ZDATE($HOROLOG),  "   default date format",!
    WRITE $ZDATE($HOROLOG,1),"   1=American numeric format",!
    WRITE $ZDATE($HOROLOG,2),"   2=Month abbreviation format",!
    WRITE $ZDATE($HOROLOG,3),"   3=ODBC numeric format",!
    WRITE $ZDATE($HOROLOG,4),"   4=European numeric format",!
    WRITE $ZDATE($HOROLOG,5),"   5=Month abbreviation format",!
    WRITE $ZDATE($HOROLOG,6),"   6=Month abbreviation format",!
    WRITE $ZDATE($HOROLOG,7),"   7=Month abbreviation format",!
    WRITE $ZDATE($HOROLOG,8),"   8=Numeric format no spaces",!
    WRITE $ZDATE($HOROLOG,9),"   9=Month name format",!
    WRITE $ZDATE($HOROLOG,10),"  10=Day-of-week format",!
    WRITE $ZDATE($HOROLOG,11),"  11=Day abbreviation format",!
    WRITE $ZDATE($HOROLOG,12),"  12=Day name format",!
    WRITE $ZDATE($HOROLOG,13),"  13=Thai numeric format",!
    WRITE $ZDATE($HOROLOG,14),"  14=Day-of-year format",!
    WRITE $ZDATE($HOROLOG,15),"  15=European numeric format",!
    WRITE $ZDATE($HOROLOG,16),"  16=Japanese date format",!
    WRITE $ZDATE($HOROLOG,17),"  17=Japanese date format with spaces"
}

DHC-APP>d ##class(PHA.TEST.Function).ZDATE6()
11/11/2020   default date format
11/11/2020   1=American numeric format
11 Nov 2020   2=Month abbreviation format
2020-11-11   3=ODBC numeric format
11/11/2020   4=European numeric format
Nov 11, 2020   5=Month abbreviation format
Nov 11 2020   6=Month abbreviation format
Nov 11 2020   7=Month abbreviation format
20201111   8=Numeric format no spaces
November 11, 2020   9=Month name format
3  10=Day-of-week format
Wed  11=Day abbreviation format
Wednesday  12=Day name format
11/11/2563  13=Thai numeric format
316  14=Day-of-year format
11/11/2020  15=European numeric format
2020年11月11日  16=Japanese date format
2020年 11月 11日  17=Japanese date format with spaces

下面的示例将日期与区域设置进行比较，该区域设置默认为当前用户区域设置与日期（当localeopt = 1激活ODBC区域设置定义时）。为了使该示例更有趣，将当前用户区域设置设置为法语：

/// d ##class(PHA.TEST.Function).ZDATE7()
ClassMethod ZDATE7()
{
    SET fmt=##class(%SYS.NLS.Format).%New("fraw")
    WRITE "default: local=",$ZDATE($HOROLOG),"   ODBC=",$ZDATE($HOROLOG,,,,,,,,,1),!
    WRITE "-1:      local=",$ZDATE($HOROLOG,-1),"   ODBC=",$ZDATE($HOROLOG,-1,,,,,,,,1),!!
    FOR x=1:1:17 {
        WRITE x,": local=",$ZDATE($HOROLOG,x),"   ODBC=",$ZDATE($HOROLOG,x,,,,,,,,1),! 
    }
}

DHC-APP>d ##class(PHA.TEST.Function).ZDATE7()
default: local=11/11/2020   ODBC=2020-11-11
-1:      local=11/11/2020   ODBC=2020-11-11
 
1: local=11/11/2020   ODBC=11/11/2020
2: local=11 Nov 2020   ODBC=11 Nov 2020
3: local=2020-11-11   ODBC=2020-11-11
4: local=11/11/2020   ODBC=11/11/2020
5: local=Nov 11, 2020   ODBC=Nov 11, 2020
6: local=Nov 11 2020   ODBC=Nov 11 2020
7: local=Nov 11 2020   ODBC=Nov 11 2020
8: local=20201111   ODBC=20201111
9: local=Novembre 11, 2020   ODBC=November 11, 2020
10: local=3   ODBC=3
11: local=Mer   ODBC=Wed
12: local=Mercredi   ODBC=Wednesday
13: local=11/11/2563   ODBC=11/11/2563
14: local=316   ODBC=316
15: local=11/11/2020   ODBC=11/11/2020
16: local=2020年11月11日   ODBC=2020年11月11日
17: local=2020年 11月 11日   ODBC=2020年 11月 11日

两位数的年份滑动窗口示例

为了说明如何使用显式滑动窗口，假设在1997年输入以下函数调用。59461的日期表示2003年10月19日； hd的日期为2003年10月19日。 dformat 1允许它返回两位数或四位数的年份，yearopt 5可以指定四位数年份的滑动窗口。由于使用了yearopt设置，因此通过加法和减法来计算相对于当年（在本例中为1997）的startwin和endwin。

DHC-APP>WRITE $ZDATE(59461,1,,5,90,10)
10/19/03

用于将年份显示为两位数的滑动窗口从1/1/1907扩展到12/31/2006。因此，Caché将日期显示为10/19/03。

日期范围示例

下面的示例使用mindate和maxdate测试可能的出生日期。 maxdate假定出生日期不能在将来。这位思想家假设列出的任何人都不会超过124岁。日期以$HOROLOG格式指定：

/// d ##class(PHA.TEST.Function).ZDATE8()
ClassMethod ZDATE8()
{
    SET bdateh(1)=62142
    SET bdateh(2)=16800
    SET bdateh(3)=70000
    DO $SYSTEM.Process.ZDateNull(1)
    SET maxdate=$PIECE($HOROLOG,",",1)+1
    SET mindate=maxdate-(365.25*124)
    FOR x=1:1:3 {
        SET bdate=$ZDATE(bdateh(x),,,,,,mindate,maxdate)
        IF bdate="" {WRITE "Birth date ",bdateh(x)," is out of range",!}
        ELSE {WRITE "Birth date ",bdateh(x)," is ",bdate,!}
    }
}

DHC-APP>d ##class(PHA.TEST.Function).ZDATE8()
Birth date 62142 is 20/02/2011
Birth date 16800 is out of range
Birth date 70000 is out of range

上面的$ZDATE输入值中有两个不在出生日期测试的日期范围之内：16800（12/30/1886）在124年前，而70000（08/26/2032）在将来。默认情况下，这些$ZDATE调用将生成错误，但是由于设置了ZDateNull（1），它们将返回空字符串（“”）。

注意

$ZDATE的值无效

在以下情况下，收到 错误：

• 如果指定了无效的dformat代码（小于-1或大于17的整数值，或者非整数值）。
• 如果在yearopt为3或5时未指定startwin值。

在以下情况下，会收到错误：

• 如果为hdate指定了无效值，并且不提供错误值或设置ZDateNull（如下所述）。
• 如果给定的月份数大于monthlist中的月份数。
• 如果maxdate小于主意。
• 如果endwin小于startwin。
• 如果startwin和endwin指定滑动时间窗口，其持续时间大于100年。

在以下情况下，收到错误：

• 如果指定的hdate值超出有效日期范围。对于标准Caché，它是0到298013。对于ISM兼容的Caché，它是1到94232。可以使用％SYSTEM.Process类的ZDateNull（）方法来设置日期范围和当前进程的无效日期行为。
• 如果指定的其他有效日期超出了为maxdate和mindate假定的值所定义的范围，并且不提供错误的值。

使用$ZDATE代替实用程序

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

• 可以使用$ZDATE函数代替％DO或％D实用程序的大多数现有入口点。
• 可以直接调用$ZDATE（$HOROLOG，7）而不是调用INT ^％D。这以“ MM DD [YY] YY”格式提供当前日期。
• $ZDATEH和$ZDATE比调用％DATE，％DI或％DO的入口点快得多。