$ZDate()

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]]]])

$ZDATE() provides an easy and flexible tool for putting M internal date/time ($HOROLOG) formats into more user-friendly formats.

[Caution] 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

$ZDATE Format Specification Elements

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] Note

A blank space inserts a blank space in the output string.

Examples of $ZDATE()

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.