01/03/91 date_time_


The date_time_ system is a utility which encodes, decodes, adjusts, or
formats a Multics standard calendar clock value.  The clock reading is
assumed to be in microseconds relative to 1901-01-01 0:00 gmt.  The
ASCII times involved may be one of several languages and in a choice of
time zones around the world.


Entry points in date_time_:
   (List is generated by the help command)


:Entry:  date_time_:  03/04/85 date_time_$date_time_


Function:  The date_time_ subroutine converts a system clock value to
ASCII representation.  It will be in terms of the process default
language and zone.


Syntax:
declare date_time_ entry (fixed bin(71), char(*));
call date_time_ (clock, str);


Arguments:
clock
   is the clock value to be formatted.  (Input)
str
   is the resultant character string.  (Output)


Notes:  The format string which produces the resultant string is:
       "^my/^dm/^yc  ^Hd^99v.9MH ^xxxxza^xxxxda"
which produces strings like this:
       mm/dd/yy  HHMM.M zzzddd
       07/14/83  1435.4 mst Thu
See time_strings.gi for a description of acceptable strings.

The ASCII representation of time, which date_time_ attempts to return
in string, is 24 characters long.  If string is declared by the caller
with a length of N and N is less than 24, then only the first N
characters are returned.  If N is greater than 24, then the result is
returned padded on the right with spaces.

If clock is not a valid date, "01/01/01 0000.0 gmt Tue" is returned.


:Entry:  format:  03/04/85 date_time_$format


Function:  This entry does a generalized formatting of a Multics
standard calendar clock value.  A format string is supplied which
describes the layout and content of the desired result.  The zone
and/or language in which the result is to be displayed may be
specified.


Syntax:
declare date_time_$format entry (char(*), fixed bin(71), char(*),
     char(*)) returns (char(250) var);
result = date_time_$format (time_format, clock, zone, lang);


Arguments:
time_format
   either a keyword, or an ioa-like control string describing the
   desired result in terms of literal characters and date/time
   selectors.  (Input) See time_format.gi.info for details.
clock
   a clock value to be displayed.  (Output)
zone
   the short name of the zone in which output time value is expressed.
   (Input) "system_zone" means use the system default zone.  "" means
   use the per-process default zone.  (Input)
lang
   the language in which month names, day names and time zones are
   expressed.  (Input) "system_lang" means use the system default time
   language.  "" means use per-process default time language.
result
   is the string which is the result of the conversion.  (Output)


Time format:
The control string to date_time_$format is either a keyword or a
character string consisting of text and/or selectors.  The selectors
are always identified by a leading circumflex character (^).  There are
2 types of selectors:  ^<keyword>, which allows a keyword to be
imbedded within a format; and the general form ^XX.  XX is a 2 letter
code which specifies what information is wanted.  An optional PL/I
picture specification may be placed between the ^ and XX if the default
form is not adequate.  If the control string does not contain any
circumflex characters, it must then be one of the known set of
keywords.  Each keyword identifies a control string for a predetermined
format named by that keyword.


List of format keywords:
all
   ^9999yc-^my-^dm__^Hd:^MH:^99.(6)9UM^zd_^za_^da ^fi
   ^(6)9fw ^ma dy^dy dc^dc Uc^Uc
calendar_clock
   ^9999yc-^my-^dm__^Hd:^MH:^99.(6)9UM_^za_^da
clock
   ^9999yc-^my-^dm ^Hd:^MH:^99.(6)9UM ^za ^da
date
   the process default value for date
date_time
   the process default value for date and time
iso_date
   ^9999yc-^my-^dm


iso_date_time
   ^9999yc-^my-^dm ^Hd:^MH:^SM ^za
iso_long_date
   ^9999yc-^my-^dm ^da
iso_long_date_time
   ^9999yc-^my-^dm ^Hd:^MH:^99.(6)9UM ^za
iso_long_time
   ^Hd:^MH:^99.(6)9UM
iso_time
   ^Hd:^MH:^SM
multics_date
   ^my/^dm/^yc
multics_date_time
   ^my/^dm/^yc ^Hd^99v.9MH ^xxxxza^xxxda


multics_time
   ^Hd:^MH
request_id
   ^yc^my^dm^Hd^MH^99.(6)9UM
system_date_time
   the system default value for date and time
system_date
   the system default value for date
system_time
   the system default value for time
time
   the process default value for time


   A site may change the "system" keywords.  To list the "system"
   keywords for your site, type:

      print_time_defaults -system

   For an application which depends upon the historic date/time
   formats, the 3 builtin "multics" keywords are available.


:Entry:  format_max_length:  03/04/85 date_time_$format_max_length


Function:  This entry returns the length of the longest result which a
format can generate.  The zone and/or language in which to work may be
specified.


Syntax:
declare date time_$format_max_length entry (char(*), char(*), char(*))
     returns (fixed bin);
max_len = date_time_$format_max_length (format, zone, lang);


Arguments:
format
   a control string intended to be given to date_time_$format.  (Input)
   b..argx zone the short name of the zone in which conversion will be
   done.  (Input) "system_zone" means use the system default zone.  ""
   means use the per-process default zone.  (input)
lang
   the language in which month names and time zones are expressed.
   "system_lang" means use the system default time language.  "" means
   use per-process default time language.
max_len
   is the length of the longest string which can result from processing
   the given format.  (Output)


:Entry:  from_clock:  03/04/85 date_time_$from_clock


Function:  Given a Multics standard calendar clock value and an output
time zone name, return the month, day of the month, the year, the hour
of the day, the minute of the hour, the second of the minute, the
number of microseconds, the day in week, the day in year, and the day
in clock.  The caller may specify one of the time zones in the
time_info_ in which the decoded clock value is to be expressed, or may
request that the value be expressed in one of the default time zones.


Syntax:
declare date_time_$from_clock entry (fixed bin(71), char(*), ptr, fixed
     bin(35));
call date_time_$from_clock (clock, zone, addr(time_value), code);


Arguments:
clock
   is the binary clock value to be decoded.  (Input)
zone
   the short name of the zone in which output time value is expressed.
   (Input) "system_zone" means use the system default zone.  "" means
   use the per-process default zone.
time_value
   is the structure containing time parts.  (Output)
code
   is a standard status code.  (Output)


:Entry:  from_clock_interval:  03/04/85 date_time_$from_clock_interval


Function:  Given two clock values, return the number of years, months,
weeks, days, hours, minutes, seconds, and microseconds between them.
The set of units to use is specified, as well as whether any are to
include the fractional remainder.


Syntax:
declare date_time_$from_clock_interval entry (fixed bin(71), fixed
     bin(71), ptr, fixed bin(35));
call date_time_$from_clock_interval (clock1, clock2, addr
     (time_offsets), code);


Arguments:
clock1
   is the base time value.  (Input) The output is expressed relative to
   this binary clock value.
clock2
   is the offset time value.  (Input) clock1 is in essence subtracted
   from this value.  If this value is later than clock1, all results
   will be positive.  If this value is earlier, all results will be
   negative.
time_offsets
   is the structure containing resulting time values.  (Output) The
   structure is defined in time_offset.incl.pl1
code
   is a standard status code.  (Output)


:Entry:  fstime:  03/04/85 date_time_$fstime


Function:  This entry performs the same function as date_time_ given a
36-bit storage system date value.


Syntax:
declare date_time_$fstime entry (bit(36) aligned, char(*));
call date_time_$fstime (ssclock, str);


Arguments:
ssclock
   is an internal storage system clock value.  (Input)
str
   is the resultant character string.  (Output)


:Entry:  offset_to_clock:  03/04/85 date_time_$offset_to_clock


Function:  This entry point creates a new Multics clock value by
adjusting an input clock value to a specified day-of-week and then
adding relative date/time offsets.  The relative date/time values
include a year offset, month offset, week offset, day offset, hour
offset, minute offset, second offset, and microsecond offset.  Any of
these values may be zero (no offset from input clock value) or negative
(backwards offset from input clock value).  In addition, an input time
zone is specified.


Syntax:
declare date_time_$offset_to_clock entry (ptr, fixed bin(71), char(*),
     fixed bin(71), fixed bin(35));
call date_time_$offset_to_clock (addr(time_offset), clock_in, zone,
     clock, code);


Arguments:
time_offset
   is the structure containing time offsets to be applied.  (Input)
   Structure is defined in time_offset.incl.pl1.
clock_in
   is the clock value to which offsets are applied.  (Input)
zone
   is the zone in which clock_in is to be interpreted.  (Input)
clock
   is the resulting clock value.  (Output)
code
   is a standard status code.  (Output)


:Entry:  set_lang:  03/04/85 date_time_$set_lang


Function:  This entry sets or resets the user's default time language.


Syntax:
declare date_time_$set_lang entry (char(*), fixed bin(35));
call date_time_$set_lang (lang, code);


Arguments:
lang
   the language which is to be made current.  (Input) "system_lang"
   means use the system default time language.
code
   is a standard status code.  (Output)


:Entry:  set_zone:  03/04/85 date_time_$set_zone


Function:  This entry sets or resets the user's default zone.


Syntax:
declare date_time_$set_zone entry (char(*), fixed bin(35));
call date_time_$set_zone (zone code);


Arguments:
zone
   the short name of the zone which is to be made current.  (Input)
   "system_zone" means use the system default zone.
code
   is a standard status code.  (Output)


:Entry:  to_clock:  03/04/85 date_time_$to_clock


Function:  Given any or all of the following - years, months, days,
hours, minutes, seconds, microseconds, day in week, day in year, or day
in clock - returns a standard clock value which represents the encoding
of these values.  All the values must be valid, i.e.  not greater than
23, etc.


Syntax:
declare date_time_$to_clock entry (ptr, fixed bin(71), fixed bin(35));
call date_time_$to_clock (addr (time_value), clock, code);


Arguments:
time_value
   is the structure containing time parts.  (Input) The structure is
   defined in time_value.incl.pl1.
clock
   is the encoded clock value.  (Output)
code
   is a standard status code.  (Output)


:Entry:  valid_format:  03/04/85 date_time_$valid_format


Function:  This entry checks the validity of a format string using
precisely the same tests as date_time_$format.


Syntax:
declare date_time_$valid_format entry (char(*), fixed bin, fixed bin(35));
call date_time_$valid_format (format, errloc, code);


Arguments:
format
   either a keyword, or an ioa-like control string describing the
   desired result in terms of literal characters and date/time
   selectors.  (Input) See the date_time_$format entry point for a
   description of valid format strings.
errloc
   is the character index in the format string where the error
   occurred.  (Output) This is meaningful only if it and code are both
   nonzero.
code
   is a standard status code.  (Output)
