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.

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.

INT: Sets variable %DAT to current date.

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

%DAT: Contains the current date..

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.

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.

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

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

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

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

%DN: Contains output date in $HOROLOG format

%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

Example:

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

This example invokes %DATE at the GTM> prompt. After pressing <RETURN> 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.

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

%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.

%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.

%DAT: Contains converted output date,

%TIM: Contains converted output time,

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.

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.

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

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

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

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.

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.

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.

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

%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

%TN: Contains output time in $HOROLOG format

Example:

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

This example invokes %TI, which prompts for an input time. Press <RETURN> 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.

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.

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

%TN: Contains input time in $HOROLOG format.

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

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.

PrevA UpA Next
A HomeA