dformat

Format for the returned date. Valid values are:

Value	Meaning
1	MM/DD/[YY]YY (07/01/97 or 02/22/2018) — American numeric format. The dateseparator character (/ or .) is taken from the current locale setting.
2	DD Mmm [YY]YY (01 Jul 97)
3	YYYY-MM-DD (2018-02-22) — ODBC format. By default this format is independent of your current locale settings, thus specifying dates and times in an ODBC standard interchange format. (The ODBC time format default is described in the tformat section, below.) To use your current date and time locale settings with this format, set localeopt to 0.
4	DD/MM/[YY]YY (01/07/97 or 22/02/2018) — European numeric format. The dateseparator character (/ or .) is taken from the current locale setting.
5	Mmm [D]D, YYYY (Jul 1, 1997)
6	Mmm [D]D YYYY (Jul 1 1997)
7	Mmm DD [YY]YY (Jul 01 1997)
8	YYYYMMDD (19970701) — Numeric format
9	Mmmmm [D]D, YYYY (July 1, 1997)
10	W (2) — Day number for the week, numbered from 0 (Sunday) through 6 (Saturday). Compare with the $SYSTEM.SQL.DAYOFWEEK()Opens in a new tab method.
11	Www (Tue) — Abbreviated day name
12	Wwwwww (Tuesday) — Full day name
13	[D]D/[M]M/YYYY (1/7/2549 or 27/11/2549) — Thai date format. Day and month are identical to European usage, except no leading zeros. The year is the Buddhist Era (BE) year, calculated by adding 543 years to the Gregorian year.
14	nnn (354) — Day number for the year
15	DD/MM/[YY]YY (01/07/97 or 22/02/2018) — European format (same as dformat=4). The dateseparator character (/ or .) is taken from the current locale setting.
16	YYYYc[M]Mc[D]Dc — Japanese date format. Year, month, and day numbers are the same as other date formats; leading zeros are omitted. The Japanese characters for “year”, “month”, and “day” (shown here as c) are inserted after the year, month, and day numbers. These characters are Year=$CHAR(24180), Month=$CHAR(26376), and Day=$CHAR(26085).
17	YYYYc [M]Mc [D]Dc — Japanese date format. Same as dformat 16, except that a blank space is inserted after the “year” and “month” Japanese characters.
18	[D]D Mmmmm YYYY — Tabular Hijri (Islamic) date format with full month name. Day leading zeros are omitted; year leading zeros are included. InterSystems IRIS date -445031 (07/19/0622 C.E.) = 1 Muharram 0001 AH.
19	[D]D [M]M YYYY — Tabular Hijri (Islamic) date format with month number. Day and month leading zeros are omitted; year leading zeros are included. InterSystems IRIS date -445031 (07/19/0622 C.E.) = 1 1 0001 AH.
20	[D]D Mmmmm YYYY — Observed Hijri (Islamic) date format with full month name. Defaults to Tabular Hijri (dformat 18). To override tabular calculation, use the class %Calendar.Hijri to add observations of new moon crescents.
21	[D]D [M]M YYYY — Observed Hijri (Islamic) date format with month number. Defaults to Tabular Hijri (dformat 19). To override tabular calculation, use the class %Calendar.Hijri to add observations of new moon crescents.
-1	Get effective dformat value from the user’s locale, fmt.DateFormat, where fmt is an instance of ##class(%SYS.NLS.Format) associated with the current process. This is the default behavior if you do not specify dformat. See “Customizable Date and Time Defaults” for further details.
-2	$ZDATETIME returns an integer specifying the count of seconds from a platform-specific origin date/time. This is the value returned by the time() library function, as defined in the ISO C Programming Language Standard. For example, on POSIX-compliant systems this value is the count of seconds from January 1, 1970 00:00:00 UTC. Fractional seconds in the input value are permitted, but ignored. (Currently, this date conversion potentially has the “local time variant boundary day” time conversion anomaly described for tformat values 5, 6, 7, and 8.) To convert this integer count of seconds to a PosixTime value, you can use the UnixTimeToLogical()Opens in a new tab method, as shown below. The following platform-specific formats are supported: 32-bit Linux: signed 32-bit integer; 64-bit Linux: signed 64-bit integer; Windows: unsigned 64-bit integer. The tformat, precision, monthlist, yearopt, startwin, and endwin arguments are ignored.
-3	$ZDATETIME takes a datetime value specified in $HOROLOG internal format, converts that value from local time to UTC Universal time, and returns the resulting value in the same internal format. The tformat, monthlist, yearopt, startwin, and endwin arguments are ignored. $ZDATETIMEH performs the inverse operation. (Currently, this date conversion has the time conversion anomalies described for tformat values 5, 6, 7, and 8. These potentially affect dates prior to 1970, dates after 2038, and local time variant boundary days, such as the beginning date or end date for Daylight Saving Time.)

Where:

Syntax	Meaning
YYYY	YYYY is a four-digit year. [YY]YY is a two-digit year if hdatetime falls within the active window for two-digit years; otherwise it is a four-digit year.
MM	Two-digit month: 01 through 12. [M]M indicates that the leading zero is omitted for months 1 through 9.
DD	Two-digit day: 01 through 31. [D]D indicates that the leading zero is omitted for days 1 through 9.
Mmm	Month abbreviation extracted from the MonthAbbr property of the current locale. An alternate month abbreviation (or name of any length) can be extracted from an optional list specified as the monthlist argument to $ZDATETIME. The MonthAbbr default values are: “Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec”
Mmmmm	Full name of the month as specified by the MonthName property of the current locale. The default values are: “January February March ... November December”
W	Number 0-6 indicating the day of the week: Sunday=0, Monday=1, Tuesday=2, etc.
Www	Weekday name abbreviation as specified by the WeekdayAbbr property of the current locale. The default values are: “Sun Mon Tue Wed Thu Fri Sat”
Wwwwww	Weekday full name as specified by the WeekdayName property of the current locale. The default values are: “Sunday Monday Tuesday Wednesday Thursday Friday Saturday”
nnn	Day number for the specified year, always three digits, with leading zeros if necessary. Values are 001 through 365 (or 366 on leap years).

dformat Default

If you omit dformat or set it to -1, the dformat default depends on the localeopt argument and the NLS DateFormat property:

If localeopt=1 the dformat default is ODBC format. The tformat, monthlist, yearopt, mindate and maxdate arguments are also set to ODBC format. This is the same as setting dformat=3.
If localeopt=0 or is unspecified, the dformat default is taken from NLS DateFormat property. If DateFormat=3, the dformat default is ODBC format. However, DateFormat=3 does not affect the tformat, monthlist, yearopt, mindate and maxdate argument defaults, which are as specified in the current NLS locale definition.

To determine the default date format for your locale, invoke the GetFormatItem()Opens in a new tab NLS class method:

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

European date format (dformat=4, DD/MM/YYYY order) is the default for many (but not all) European languages, including British English, French, German, Italian, Spanish, and Portuguese (which use a “/” DateSeparator character), as well as Czech (csyw), Russian (rusw), Slovak (skyw), Slovenian (svnw), and Ukrainian (ukrw) (which use a “.” DateSeparator character). For further details on default date formats for supported locales, refer to Dates.

dformat Settings

If dformat is 3 (ODBC date format), ODBC format defaults are also used for the monthlist, yearopt, mindate and maxdate argument defaults. Current locale defaults are ignored.

If dformat is -1, 1, 4, 13, or 15 (numeric date formats), $ZDATETIME uses the value of the DateSeparator property of the current locale as the delimiter between months, days, and the year. When dformat is 3 the ODBC date separator ( “-”) is used. For all other dformat values, a space is used as the date separator. The default value of DateSeparator in English is “/” and all documentation uses this delimiter.

If dformat is 11 or 12 (day names) and localeopt=0 or is unspecified the day name values come from the current locale properties. If localeopt=1, day names come from the ODBC locale. To determine the default weekday names and weekday abbreviations for your locale, invoke the following NLS class methods:

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

If dformat is -2 (Unix® time: UTC elapsed seconds since 1970-01-01 00:00:00), you can convert this value to an encoded PosixTime value using the UnixTimeToLogical()Opens in a new tab method. The following example uses dformat -2 to convert local time to elapsed seconds in UTC (Greenwich) time. It then converts this count of seconds to an encoded %PosixTimeOpens in a new tab value using UnixTimeToLogical(). It converts this PosixTime value back to a ODBC-format datetime in UTC time using LogicalToOdbc(). It also converts PosixTime back to elapsed seconds using LogicalToUnixTime(), then uses $ZDATETIMEH with dformat -2 to convert this UTC elapsed seconds count to local datetime:

  WRITE "local datetime: ",$ZDATETIME($HOROLOG,3),!
  SET secs=$ZDATETIME($HOROLOG,-2)
  WRITE "UTC seconds since 1970: ",secs,!
  SET posix=##class(%PosixTime).UnixTimeToLogical(secs)
  WRITE "PosixTime encoded value: ",posix,!
  SET datetime=##class(%PosixTime).LogicalToOdbc(posix)
  WRITE "UTC datetime: ",datetime,!
  SET secs2=##class(%PosixTime).LogicalToUnixTime(posix)
  WRITE "UTC seconds since 1970: ",secs2,!
  SET htime=$ZDATETIMEH(secs2,-2)
  WRITE "local datetime: ",$ZDATETIME(htime,3)

Note that Unix® time is a count of whole seconds, whereas Posix time counts fractional seconds with six decimal digits of precision.

If dformat is 16 or 17 (Japanese date formats), the returned date format is independent of the locale setting. Japanese-format dates can be returned from any InterSystems IRIS instance.

If dformat is 18, 19, 20, or 21 (Islamic date formats) and localeopt is unspecified, arguments default to Islamic defaults, rather than current locale defaults. The monthlist argument defaults to Arabic month names transliterated with Latin characters. The tformat, yearopt, mindate and maxdate arguments default to ODBC defaults. The date separator defaults to the Islamic default (a space), not the ODBC default or the current locale DateSeparator property value. If localeopt=0 current locale property defaults are used for these arguments. If localeopt=1 ODBC defaults are used for these arguments.

tformat

hdatetime