Returns a date and/or time formatted as text based on an argument formatted in the manner of $HOROLOG. For information on the format of $HOROLOG, refer to Chapter 8: “Intrinsic Special Variables”.
The format for the $ZDATE function is:
$ZD[ATE](expr1[,expr2[,expr3[,expr4]]]])
The first expression specifies in $HOROLOG format the date and/or time that $ZDATE() returns in text format. If the output requires only the date or the time, the other piece of the argument that is delimited by a comma (,) may be null.
The optional second expression specifies a string providing $ZDATE() with a "picture" of the desired output format. If this argument is missing or null, $ZDATE() uses the default format string "MM/DD/YY". If the optional second expression exceeds 64 characters, $ZDATE() generates a run-time error.
The optional third expression specifies a list of 12 month codes, separated by commas (,), that $ZDATE() uses in formatting text months called for by the "MON" picture, (that is, $ZDATE() outputs $PIECE(expr3,",",month-number) when "MON" appears in the second expression). If this argument is missing or null, $ZDATE() uses three-character English abbreviations for months.
The optional fourth expression specifies a list of seven day codes, separated by commas (,), which $ZDATE() uses in formatting text days of the week called for by the "DAY" picture, $ZDATE() outputs $PIECE (expr4,",",day-of-week-number) when "DAY" appears in the second expression; if this argument is missing or null, $ZDATE() uses three-character English abbreviations for days of the week.
$ZDATE() returns 31-Dec-1840 as a date representation of day 0.
$ZDATE() provides an easy and flexible tool for putting M internal date/time ($HOROLOG) formats into more user-friendly formats.
![[Caution]](../common/images/caution.jpg) | Warning |
|---|---|
$ZDATE() generates an error for input date values greater than 31-Dec-999999 (364570088) or less than 01-JAN-1840 (-365) and for time values greater than a second before midnight (86399) or less than 0 (zero). |
The Intrinsic Special Variable $ZDATEFORM determines the output format for years. The default value is zero (0), in which case $ZDATE() with one argument (no format specification) uses a "YY" (two digit) format for all years. If $ZDATEFORM is one (1), a "YYYY" (four digit) format is used for years later than 1999. For all other values of $ZDATEFORM, "YYYY" (four digit) format is used for all years. $ZDATEFORM does not affect $ZDATE() when the format argument is specified.
The following table summarizes the usage of $ZDATE() when only first argument is specified.
|
Value of $ZDATEFORM |
$ZDATE() Output Format |
|---|---|
|
0 |
2 digits |
|
1 |
4 digits for years 2000 and after 2 digits otherwise (for years ranging between 1840, 1999) |
|
other |
4 digits |
This section lists the $ZDATE format specification elements. $ZDATE() format specifications must appear in upper case. When any alphabetic characters in format specifications are in lower case, $ZDATE() generates a run-time error.
YY: Outputs the rightmost two digits of the year.
YEAR or YYYY: Outputs the year as a four-digit number.
YYYYYY: Outputs the year as a six-digit number.
MM: Outputs the month as a two-digit zero-filled number between 01 and 12.
MON: Outputs the month as a three-letter abbreviation. (You can modify the output further using expr3).
DD: Outputs the day of the month as a two-digit zero-filled number between 01 and 31.
DAY: Outputs the day of the week as a three-letter abbreviation. (You can modify the output further using expr4).
24: Outputs the hour of the day as a zero-filled number between 00 and 23.
12: Outputs the hour of the day as a zero-filled number between 01 and 12.
60: Outputs the minute of the hour as a zero-filled number between 00 and 59.
SS: Outputs the second of the minute as a zero-filled number between 00 and 59.
AM: Outputs the letters AM and PM depending on the time.
+: Inserts a plus sign (+) in the output string
-: Inserts a minus sign (-) in the output string.
.: Inserts a period (.) in the output string.
,: Inserts a comma (,)in the output string.
/: Inserts a slash (/) in the output string.
:: Inserts a colon (:) in the output string.
;: Inserts a semi-colon (;) in the output string.
*: Inserts an asterisk (*) in the output string.
![[Note]](../common/images/note.jpg) | Note |
|---|---|
A blank space inserts a blank space in the output string. |
Example:
GTM>write $horolog,!,$zdate($H) 62109,60946 01/18/11 GTM>
This displays $HOROLOG and then uses $ZDATE() to display today's date. The output shown would appear if today were the eighteenth day of January, 2011.
Example:
GTM>write $zdate($H,"DD-MON-YEAR") 18-JAN-2011 GTM>
This uses the second argument to specify a text format different from the default.
Example:
GTM>set m="Januar,Februar,Marz,April,Mai,Juni,Juli,August," GTM>set m=m_"September,October,November,Dezember" GTM>write $zdate($horolog,"DD-MON-YEAR",m) 18-Januar-2011 GTM>
This is similar to the prior example, however it uses the third argument to specify the months in German.
Example:
GTM>set d="Dimanche,Lundi,Mardi,Mercredi,Jeudi,Vendredi,Samedi" GTM>write $zdate($H,"DAY, DD/MM/YY","",d) Mardi, 18/01/2011 GTM>
This example displays the eighteenth of January, however it uses the fourth argument to specify the days of the week in French.
Example:
GTM>write !,$zdate($H,"12:60:SS AM") 10:35:51 PM GTM>
This example shows hours, minutes, and seconds in a 12 hour clock with an AM/PM indicator.
Example:
GTM>write !,$zdate(",36524","24-60")
10-08
GTM>This example shows hours and minutes on a 24 hour clock. Notice that the first argument must provide the time in the second comma delimiter piece to match $HOROLOG format.
Example:
GTM>write $zdateform 0 GTM>write $zdate($H) 01/18/11 GTM>set $zdateform=1 GTM>write $zdate($horolog) 01/18/2011 GTM>write $zdate($horolog,"MM/DD/YY") 01/18/11
This example converts the output format for years from the default ("YY") format to the four digit format ("YYYY") using the Intrinsic Special Variable $ZDATEFORM.
Example:
GTM>write $zdate(123456789,"DAY MON DD, YYYYYY") FRI MAR 17, 339854 GTM>
This example displays year as a six-digit number.
