{Begin SubSec Date And Time Functions}
{Title Date And Time Functions}
{Text


{FnDef {FnName DATE} {FnArgs FORMAT}
{Text
Returns the current date and time as a string with format {lisp "{arg DD}-{arg MM}-{arg YY} {arg HH}:{arg MMM}:{arg SS}"}, where {arg DD} is day, {arg MM} is month, {arg YY} year, {arg HH} hours, {arg MMM} minutes, {arg SS} seconds, e.g., {lisp " 7-Jun-85 15:49:34"}.

If {arg FORMAT} is a date format as returned by {fn DATEFORMAT} (below), it is used to modify the format of the date string returned by {fn DATE}.
}}


{FnDef {FnName IDATE} {FnArgs STR}
{Text
{arg STR} is a date and time string.  {fn IDATE} returns {arg STR} converted to a number such that if {arg DATE{sub 1}} is before (earlier than) {arg DATE{sub 2}}, then {lisp (IDATE {arg DATE{sub 1}})} < {lisp (IDATE {arg DATE{sub 2}})}.  If {arg STR} is {lisp NIL}, the current date and time is used.

Note that different Interlisp implementations can have different internal date formats.  However, {fn IDATE} always has the essential property that {lisp (IDATE {arg X})} is less than {lisp (IDATE} {arg Y}) if {arg X} is before {arg Y}, and {lisp (IDATE (GDATE {arg N}))} equals {arg N}.  Programs which do arithmetic other than numerical comparisons between {fn IDATE} numbers may not work when moved from one implementation to another.

Generally, it is possible to increment an {fn IDATE} number by an integral number of days by computing a "1 day" constant, the difference between two convenient {lisp IDATE's}, e.g. {lisp (IDIFFERENCE (IDATE " 2-JAN-80 12:00") (IDATE " 1-JAN-80 12:00"))}.  This "1 day" constant can be evaluated at compile time.

{fn IDATE} is guaranteed to accept as input the dates that {fn DATE} will output.  It will ignore the parenthesized day of the week (if any).  {fn IDATE} also correctly handles time zone specifications for those time zones registered in the list {var TIME.ZONES} ({PageRef Var TIME.ZONES}).
}}



{FnDef {FnName GDATE} {FnArgs DATE FORMAT {anonarg}}
{Text
Like {fn DATE}, except that {arg DATE} can be a number in internal date and time format as returned by {fn IDATE}.  If {arg DATE} is {lisp NIL}, the current time and date is used.
}}


{FnDef {Name DATEFORMAT} {Args KEY{sub 1} {ellipsis} KEY{sub N}}
{Type NLAMBDA NOSPREAD}
{Text
{fn DATEFORMAT} returns a date format suitable as a parameter to {fn DATE} and {fn GDATE}.  {arg KEY{sub 1}} {ellipsis} {arg KEY{sub N}} are a set of keywords (unevaluated).  Each keyword affects the format of the date independently (except for {lisp SLASHES} and {lisp SPACES}).  If the date returned by {lisp (DATE)} with the default formatting was {lisp " 7-Jun-85 15:49:34"}, the keywords would affect the formatting as follows:

{Begin LabeledList DATEFORMAT keywords}

{Name {lisp NO.DATE}}
{Text Doesn't include the date information, e.g. {lisp "15:49:34"}.}

{Name {lisp NUMBER.OF.MONTH}}
{Text Shows the month as a number instead of a name, e.g. {lisp " 7-06-85 15:49:34"}.}

{Name {lisp YEAR.LONG}}
{Text Prints the year using four digits, e.g. {lisp " 7-Jun-1985 15:49:34"}.}

{Name {lisp SLASHES}}
{Text Separates the day, month, and year fields with slashes, e.g. {lisp " 7/Jun/85 15:49:34"}.}

{Name {lisp SPACES}}
{Text Separates the day, month, and year fields with spaces, e.g. {lisp " 7 Jun 85 15:49:34"}.}

{Name {lisp NO.LEADING.SPACES}}
{Text By default, the day field will always be two characters long.  If {lisp NO.LEADING.SPACES} is specified, the day field will be one character for dates earlier than the 10th, e.g. {lisp "7-Jun-85 15:49:34"} instead of {lisp " 7-Jun-85 15:49:34"}.}

{Name {lisp NO.TIME}}
{Text Doesn't include the time information, e.g. {lisp " 7-Jun-85"}.}

{Name {lisp TIME.ZONE}}
{Text Includes the time zone in the time specification, e.g. {lisp " 7-Jun-85 15:49:34 PDT"}.}

{Name {lisp NO.SECONDS}}
{Text Doesn't include the seconds, e.g. {lisp " 7-Jun-85 15:49"}.}

{Name {lisp DAY.OF.WEEK}}
{Text Includes the day of the week in the time specification, e.g. {lisp " 7-Jun-85 15:49:34 PDT (Friday)"}.}

{Name {lisp DAY.SHORT}}
{Text If {lisp DAY.OF.WEEK} is specified to include the day of the week, the week day is shortened to the first three letters, e.g. {lisp " 7-Jun-85 15:49:34 PDT (Fri)"}.  Note that {lisp DAY.SHORT} has no effect unless {lisp DAY.OF.WEEK} is also specified.}

{End LabeledList DATEFORMAT keywords}
}}




{FnDef {FnName CLOCK} {FnArgs N {anonarg}}
{Text
If {arg N}=0, {fn CLOCK} returns the current value of the time of day clock i.e., the number of milliseconds since last system start up.

If {arg N}=1, returns the value of the time of day clock when the user started up this Interlisp, i.e., difference between {lisp (CLOCK 0)} and {lisp (CLOCK 1)} is number of milliseconds (real time) since this Interlisp system was started.

If {arg N}=2, returns the number of milliseconds of {it compute} time since user started up this Interlisp (garbage collection time is subtracted off).

If {arg N}=3, returns the number of milliseconds of compute time spent in garbage collections (all types).
}}


{FnDef {Name SETTIME} {Args DT}
{Text
Sets the internal time-of-day clock.  If {arg DT} = {lisp NIL}, {fn SETTIME} attempts to get the time from the communications net;  if it fails, the user is prompted for the time.  If {arg DT} is a string in a form that {fn IDATE} recognizes, it is used to set the time.
}}


The following variables are used to interpret times in different time zones.  {var \TimeZoneComp}, {var \BeginDST}, and {var \EndDST} are normally set automatically if your machine is connected to a network with a time server.  For standalone machines, it may be necessary to set them by hand (or in your init file, see {PageRef Term Init files}) if you are not in the Pacific time zone.


{VarDef {Name TIME.ZONES}
{Text
Value is an association list that associates time zone specifications (PDT, EST, GMT, etc.) with the number of hours west of Greenwich (negative if east).  If the time zone specification is a single letter, it is appended to "DT" or "ST" depending on whether daylight saving time is in effect.  Initially set to:

{lispcode
((8 . P) (7 . M) (6 . C) (5 . E) (0 . GMT))}

This list is used by {fn DATE} and {fn GDATE} when generating a date with the {lisp TIME.ZONE} format is specified, and by {fn IDATE} when parsing dates.
}}


{indexX {Name TimeZoneComp} {Type Variable}
{Text {lisp \TimeZoneComp}} }

{VarDef {Name \TimeZoneComp}
{Text
This variable should be initialized to the number of hours west of Greenwich (negative if east).  For the U.S. west coast it is 8.  For the east coast it is 5.
}}

{indexX {Name BeginDST} {Type Variable}
{Text {lisp \BeginDST}} }
{indexX {Name EndDST} {Type Variable}
{Text {lisp \EndDST}} }

{VarDef {Name \BeginDST}}
{VarDef {Name \EndDST}
{Text
{var \BeginDST} is the day of the year on or before which Daylight Savings Time takes effect (i.e., the Sunday on or immediately preceding this day); {var \EndDST} is the day on or before which Daylight Savings Time ends.  Days are numbered with 1 being January 1, and counting the days as for a leap year.  In the USA where Daylight Savings Time is observed, {var \BeginDST} = 121 and {var \EndDST} = 305.  In a region where Daylight Savings Time is not observed at all, set {var \BeginDST} to 367.
}}


}{End SubSec Date And Time Functions}