Date and Time Utilities

The date and time utilities are:

%D: Displays the current date using the [d]d-mmm-[yy]yy format.

%DATE: Converts input date to the $HOROLOG format.

%H: Converts date and time to and from $HOROLOG format.

%T: Displays the current time in [h]h:mm AM/PM format.

%TI: Converts time to $HOROLOG format.

%TO: Converts the current time from $HOROLOG format to [h]h:mm AM/PM format.

The “%” sign has been removed from the topic headings below, intentionally.

The Intrinsic Special Variable $ZDATEFORM interprets year inputs with two digits as described in the following table:


$ZDATEFORM	INTERPRETATION OF 2 DIGIT YEAR	OUTPUT OF %D
0:	20th century (1900 - 1999)	2 digits
1:	current century (2000 - 2099)	4 digits
(1841-9999):	the next 99 years starting from $ZDATEFORM (x - x+99)	4 digits
other:	current century (2000 - 2099)	4 digits

Example:

If $ZDATEFORM is 1965, an input year of 70 would be interpreted as 1970, whereas an input year of 10 would be taken as 2010.

%D

The %D utility displays the current date using the [d]d-mmm-[yy]yy format. If a routine uses this function repetitively, put the utility code directly into the M program.

Utility Labels

INT: Sets variable %DAT to current date.

FUNC[()]: Invokes an extrinsic function returning today’s date.

Output Variables

%DAT: Contains the current date..

Examples of %D

For the following examples, $ZDATEFORM is assumed to be one (1).

Example:

GTM>DO ^%D
22-NOV-2010

This example invokes %D in Direct Mode. Then %D displays the current date.

Example:

GTM>DO INT^%D
GTM>ZWRITE
%DAT="22-NOV-2010"

This example invokes %D with the label INT (INT^%D). The variable %DAT contains the current date. ZWRITE displays the contents of the output variable.

Example:

GTM>WRITE $$FUNC^%D 
22-NOV-2010

This example invokes %D as an extrinsic function with the label FUNC. $$FUNC^%D returns today’s date.

%DATE

The %DATE utility converts an input date to the $HOROLOG format. The $HOROLOG format represents time as the number of days since December 31, 1840. The routine has entry points for interactive or non-interactive use.

Utility Labels

INT: Converts %DS input non-interactively, if defined, otherwise the current date.

FUNC(t): Invokes an extrinsic function returning $HOROLOG format of the argument.

Prompts

Date: Interactively requests a date for conversion to $HOROLOG format.

Input Variables

%DS: Contains input date; refer to %DATE Input Formats table.

Output Variables

%DN: Contains output date in $HOROLOG format

Date Input Formats Table


%DATE Input Formats
ELEMENT	DESCRIPTION	EXAMPLES
DAYS	1 or 2 digits	1,01,24
MONTHS	1 or 2 digits	3,03,12
	Abbreviations accepted	MAR
	Numeric months precede days	1/5 is 5 Jan
	Alpha months may precede or follow days	3 MAR MAR 3
YEARS	2 or 4 digits	11/22/98 11/22/2002
	A missing year defaults to current year	11/22
TODAY	Abbreviation accepted	T[ODAY]
	t+/- N. no. of days	t+1 t-3
TOMORROW	Abbreviation accepted	TOM[ORROW]
YESTERDAY	Abbreviation accepted	Y[ESTERDAY]
NULL INPUT	Defaults to today
DELIMITERS	All non-alphanumeric character(s) except the + or - offset	11/22/98 11 Nov 98 22 Nov, 2002 11-22-2002

Examples of %DATE

Example:

GTM>DO ^%DATE
Date:
GTM>ZWRITE
%DN=62047

This example invokes %DATE at the GTM> prompt. After pressing at the Date: prompt, %DATE converts today’s date (for example, 11/22/2010) to the $HOROLOG format. ZWRITE displays the contents of the output variable.

Example:

GTM>DO INT^%DATE
GTM>ZWRITE
%DN=59105

This example invokes INT^%DATE, which converts the current date non-interactively into $HOROLOG format. ZWRITE displays the contents of the output variable.

Example:

GTM>SET %DS="10/20/2010"
GTM>DO INT^%DATE
GTM>ZWRITE
%DN=62019
%DS="10/20/2010"

This example sets the input variable %DS prior to invoking INT^%DATE, which converts that date non-interactively to $HOROLOG format.

Example:

GTM>WRITE $$FUNC^%DATE("10/20/2010")
62010

This example invokes %DATE with the label FUNC as an extrinsic function to convert an input date to $HOROLOG. If the invocation does not supply a date for $$FUNC^%DATE, FUNC converts the current date.

Example:

GTM>WRITE $ZDATEFORM
1975
GTM>WRITE $$FUNC^%DATE("10/20/80")
51062
GTM>WRITE $ZDATE(51062)
10/20/1980
GTM>WRITE $$FUNC^%DATE("10/20/10")
62019
GTM>WRITE $ZDATE(62019)
10/20/2010

This example shows the use of a year limit in $ZDATEFORM. Two digit years are interpreted to be in the interval (1975, 2074) since $ZDATEFORM is 1975; the input year “80” is interpreted as the year “1980” and “10” is interpreted as the year “2010”. The example invokes FUNC^%DATE to convert the input date to $HOROLOG format. $ZDATE() is used to convert the $HOROLOG format date to mm/dd/yyyy format.

%H

The %H utility converts date and time to and from $HOROLOG format.

Utility Labels

%CDS: Converts %DT $HOROLOG input date to mm/dd/yyyy format.

%CTS: Converts %TM $HOROLOG input time to external format.

%CDN: Converts %DT input date to $HOROLOG format.

%CTN: Converts %TM input time to $HOROLOG format.

CDS(dt): Extrinsic entry that converts the $HOROLOG argument to external date format.

CTS(tm): Extrinsic entry that converts the $HOROLOG argument to external time format.

CDN(dt): Extrinsic entry that converts the argument to $HOROLOG format.

CTN(tm): Extrinsic entry that converts the argument to $HOROLOG format.

Input Variables

%DT: Contains input date in either $HOROLOG or mm/dd/[yy]yy format, depending on the format expected by the utility entry point.

%TM: Contains input time in either $HOROLOG or [h]h:mm:ss format, depending on the format expected by the utility entry point.

Output Variables

%DAT: Contains converted output date,

%TIM: Contains converted output time,

Examples of %H

Example:

GTM>SET %DT=+$H DO %CDS^%H
GTM>ZWRITE
%DAT="10/20/2010"
%DT=62047

This example sets %DT to the current date in $HOROLOG format and converts it to mm/dd/yyyy format by invoking %H at the label %CDS. %H returns the converted date in the variable %DAT. ZWRITE displays the contents of the variables.

Example:

GTM>SET %DT="10/20/2002" DO %CDN^%H
GTM>ZWRITE
%DAT=59097
%DT="10/20/2002"

This example sets the variable %DT to a date in mm/dd/yyyy format and invokes %H at the label %CDN. %H returns the converted date in the variable %DAT. ZWRITE displays the contents of the variables.

Example:

GTM>SET %TM=$P($H,",",2) DO %CTS^%H
GTM>ZWRITE
%TIM="17:41:18" 
%TM=63678

This example sets the variable %TM to the current time in $HOROLOG format using a $PIECE() function to return only those digits of the $HOROLOG string that represent the time. The example then invokes %H at the label %CTS. %H returns the converted time in the variable %TIM. ZWRITE displays the contents of the variables.

Example:

GTM>SET %TM="17:41:18" DO %CTN^%H
GTM>ZWRITE
%TIM=63678
%TM="17:41:18"

This example sets the variable %TM to a time in hh:mm:ss format, and invokes %H at the label %CTN. %H returns the converted time in the variable %TIM. ZWRITE displays the contents of the variables.

Example:

GTM>WRITE $$CDS^%H(62019)
11/17/2010

This invokes CDS^%H as an extrinsic function to convert the external argument to external date format.

Example:

GTM>WRITE $ZDATEFORM
1980
GTM>WRITE $$CDN^%H("10/20/02")
59097
GTM>WRITE $ZDATE(59097)
10/20/2002
GTM>WRITE $$CDN^%H("10/20/92")
55445
GTM>WRITE $ZDATE(55445)
10/20/1992

This example shows the use of a year limit in $ZDATEFORM. Two digit years are interpreted to be in the interval of 1980 - 2079; since $ZDATEFORM is 1980, the input year “02” is interpreted as “2002” and “92” is interpreted as “1992”. This example invokes CDN^%H to convert the argument in mm/dd/yy format to $HOROLOG format. $ZDATE() is used to conver the $HOROLOG format date to mm/dd/yyyy format.

%T

The %T utility displays the current time in [h]h:mm AM/PM. If a routine uses this function repetitively, put the utility code directly into the M program.

Utility Labels

INT: Sets %TIM to current time in [h]h:mm AM/PM format.

FUNC[()]: Invokes an extrinsic function returning the current time.

Output Variables

%TIM: Contains current time in [h]h:mm AM/PM format.

Examples of %T

Example:

GTM>DO ^%T
8:30 AM

This example invokes %T, which prints the current time and does not set %TIM.

Example:

GTM>DO INT^%T
GTM>ZWRITE
%TIM="8:30 AM"

This example invokes INT^%T, which sets the variable %TIM to the current time. ZWRITE displays the contents of the variable.

Example:

GTM>WRITE $$FUNC^%T
8:30 AM

This example invokes FUNC as an extrinsic function, which returns the current time.

%TI

The %TI utility converts time to $HOROLOG format. The $HOROLOG format represents time as the number of seconds since midnight. %TI returns the converted time in the variable %TN. The routine has entry points for interactive or non-interactive use.

Utility Labels

INTNon-interactively converts %TS to $HOROLOG format; if %TS is not defined, then current time is converted.

FUNC[(ts)]Invokes an extrinsic function returning $HOROLOG format of the argument, or if no argument, the $HOROLOG format of the current time.

Prompts

Time: Requests time in [h]h:mm:ss format to convert to $HOROLOG format.

Input Variables

%TS Contains input time.

The following table summarizes input formats accepted by %TI.


%TI Input Formats
ELEMENT	DESCRIPTION	EXAMPLES
HOURS	1 or 2 digits	3,03,12
MINUTES	2 digits	05,36
AM or PM	AM or PM required	9:00 AM or am 9:00 PM or pm
	Abbreviation accepted	9:00 A or a 9:00 P or p
NOON	Abbreviation accepted	N[OON]
MIDNIGHT or MIDNITE	Abbreviation accepted	M[IDNIGHT] or m[idnight] M[IDNITE] or m[idnite]
MILITARY	No punctuation (hhmm)	1900, 0830
NULL INPUT	Defaults to current time
DELIMITERS	Colon between hours and minutes	3:00

Output Variables

%TN: Contains output time in $HOROLOG format

Examples of %TI

Example:

GTM>DO ^%TI
Time: 4:02 PM
GTM>ZWRITE
%TN=57720

This example invokes %TI, which prompts for an input time. Press to convert the current time. ZWRITE displays the contents of the output variable.

Example:

GTM>ZWRITE
GTM>DO INT^%TI
GTM>ZWRITE
%TN=40954

This example invokes INT^%TI to convert the current time non-interactively. ZWRITE displays the contents of the output variable %TN.

Example:

GTM>SET %TS="8:30AM"
GTM>DO INT^%TI
GTM>ZWRITE
%TN=30600
%TS="8:30AM"

This example sets the variable %TS prior to invoking INT^%TI. %TI uses %TS as the input time. ZWRITE displays the contents of the variables.

Example:

GTM>WRITE $$FUNC^%TI("8:30AM")
30600

This example invokes %TI as an extrinsic function to convert the supplied time to $HOROLOG format. If there is no argument (i.e., $$FUNC^%TI), %TI converts the current time.

%TO

The %TO utility converts the input time from $HOROLOG format to [h]h:mm AM/PM format. Put the utility code directly into the M program if the routine uses this function repetitively.

Utility Labels

INT: Converts non-interactively %TS, or if %TS is not defined the current time to [h]h:mm AM/PM format.

Input Variables

%TN: Contains input time in $HOROLOG format.

Output Variables

%TS: Contains output time in [h]h:mm AM/PM format.

Examples of %TO

Example:

GTM>DO INT^%TI,^%TO 
GTM>ZWRITE
%TN=62074
%TS="5:14 PM"

This example invokes INT^%TI to set %TN to the current time and invokes %TO to convert the time contained in %TN to the [h]h:mm AM/PM format. %TO returns the converted time in the variable %TS. ZWRITE displays the contents of the variables.