03/07/85  Formatting of Date/Time Data

This segment describes the functions available in date_time_$format
for building strings containing selected date/time information.


General:
The control string for the date_time_$format subroutine, clock
command, and other commands that expect a time_format argument 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 two types of selectors:
^<keyword>, which allows a keyword to be embedded within a format, and
the general form ^XX.  XX is a two-letter code that specifies what
information is wanted.  You can place an optional PL/I picture
specification 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
   (This line is broken only for publishing purposes,
    there is nothing between "^fi" and "^(6".)
calendar_clock
   ^9999yc-^my-^dm__^Hd:^MH:^99.(6)9UM_^za_^da.
clock
   ^9999yc-^my-^dm  ^Hd:^MH:^99.(6)9UM ^za ^da.
date
   is the process default value for date.
date_time
   is 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.


time
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.  The output from this keyword is
   specified in the process default time zone; therefore if you want a
   valid request-id, specify -zone GMT in commands or give GMT as the
   zone argument when calling date_time_$format with the request_id
   keyword (see request_ids.gi and Section 3 of the Programmer's
   Reference Manual).
system_date_time
   is the system default value for date and time.


system_date
   is the system default value for date.
system_time
   is the system default value for time.
time
   is the process default value for time.

   Your site can change the "system" strings.  For an application that
   depends upon the historic formats the three builtin "multics"
   strings are available.


Notes on control strings:
Processing of a control string proceeds by scanning the control string
until a circumflex is found or the end of the string is reached.  Any
text (including any blanks) passed over is copied to the output
string.  The selector is then interpreted and executed.  This causes a
datum from the input clock value to be edited into the output string.
Processing continues in this way until the control string is
exhausted.

You can express dates and times placed in the output string in units
of years, months, weeks, days, hours, minutes, seconds, and
microseconds, and the total calendar value as a single unit; for
example, you could express the calendar value representing 79-09-08
9:42A GMT as 1979 years, as 722702 days, or as 722702.112499 days.


You can also express dates and times as the number of units remaining
after a larger unit has been removed from the calendar value; for
example, 09/08/79 09:42 includes units for the 9th month of the year,
the 8th day of the month, the 9th hour of the day, and the 42nd minute
of the hour.

There are several items of date/time data that are nonnumeric, such as
day of week, day of month, and time zone used for conversion.


The selectors of numeric data are, in general, made up of two letters
taken from this sequence: c y m w d H M S U.  This letters stand for
calendar, year, month, week, day, hour, minute, second, and
microsecond, respectively.  All 81 combinations are not, however,
valid.  The form can generally be read as "unit of unit", e.g.,
"seconds of week".  The first unit is always smaller than the second
one.  In trying to keep the specifiers reasonably mnemonic (in
English) there is a problem: both month and minute begin with an "m".
So all date values are used as lowercase letters while all time
values are in uppercase.


It is difficult to try to handle all the forms needed in a general
manner.  Hd is hour of the day and is thus 24-hour time; this is not
always what is wanted.  Hh is chosen as hour in half day to get the
12-hour form of time.  To go along with this there is "mi" for
Meridiem Indicator, which gives A or P to make up AM or PM.  This does
not give AM or PM because ANSI and ISO standards specify that time be
given as "3P", not "3PM".  If you want the M, put the literal in,
e.g., "^miM".

Another way of looking at a calendar value is in terms of fiscal week.
This is selected with the "^fw" code.  Its value is four digits of
year followed by two digits of week number, i.e., yyyyww.  The default
picture has been chosen to give a value of yww.  The associated fiscal
indicator is selected by "^fi".  A complete value is obtained by
specifying "^fi^fw".


The table below shows the complete set of selectors.  The row
specifies what unit is wanted, the column specifies within what other
unit, e.g., ^Sy is seconds of year.

                           DATE/TIME SELECTORS

         | of   | of   | of   | of   | of   | of   | of   | of   |
         |calen-| year |month | week | day  | hour |minute|second|
  -------|  dar |      |      |      |      |      |      |      |
  micro- +------+------+------+------+------+------+------+------+
  second | ^Uc  | ^Uy  | ^Um  | ^Uw  | ^Ud  | ^UH  | ^UM  | ^US  |
         +------+------+------+------+------+------+------+------+
  second | ^Sc  | ^Sy  | ^Sm  | ^Sw  | ^Sd  | ^SH  | ^SM  |
         +------+------+------+------+------+------+------+


         +------+------+------+------+------+------+------+
  minute | ^Mc  | ^My  | ^Mm  | ^Mw  | ^Md  | ^MH  |
         +------+------+------+------+------+------+
    hour | ^Hc  | ^Hy  | ^Hm  | ^Hw  | ^Hd  |
         +------+------+------+------+------+
     day | ^dc  | ^dy  | ^dm  | ^dw  |        month    day    zone
         +------+------+------+------+      +------+------+------+
   month |      | ^my  |             name   | ^mn  | ^dn  | ^zn  |
         +------+------+                    +------+------+------+


         +------+------+                    +------+------+------+
    year | ^yc  |                    abbrev | ^ma  | ^da  | ^za  |
         +------+                           +------+------+------+
         | ^Hh  | <-hour of half day      differential    | ^zd  |
         +------+    (12-hour form)                       +------+
         | ^mi  | <-meridiem indicator ("A" or "P")
         +------+
         | ^fw  | <-fiscal week (form: yyyyww)
         +------+
         | ^fi  | <-fiscal indicator ("FW" in English)
         +------+


List of picture extensions: In addition to the normal picture
   characters, a selector has 3 additional ones.  Normally, pictures
   are of fixed length.  With the aid of these controls, SPACEs or
   ZEROs can be trimmed from a result.
X
   This represents an output position just like an "x", but the
   character output into this position will be dropped if it is part of
   a string of rightmost SPACEs.
O
   This represents an output position just like a "9", but the digit in
   the position will be unconditionally omitted.
Z
   This represents an output position just like a "9", but a ZERO in
   the position will be dropped (at either end) if it is not
   significant.


List of format selectors: This shows each selector, its default
   picture, and its meaning.
^Uc
   (18)Z9    microseconds in calendar
^Uy
   (14)Z9    microseconds of year
^Um
   (13)Z9    microseconds of month
^Uw
   (12)Z9    microseconds of week
^Ud
   (11)Z9    microseconds of day
^UH
   (10)Z9    microseconds of Hour


^UM
   (8)Z9     microseconds of Minute
^US
   (5)Z9     microseconds of Second
^Sc
   (12)Z9    seconds in calendar
^Sy
   (12)Z9    seconds of year
^Sm
   (8)Z9     seconds of month
^Sw
   (6)Z9     seconds of week


^Sd
   (5)Z9     seconds of day
^SH
   (4)Z9     seconds of Hour
^SM
   99        seconds of Minute
^Mc
   (10)Z9    minutes in calendar
^My
   (6)Z9     minutes of year
^Mm
   (5)Z9     minutes of month


^Mw
   (5)Z9     minutes of week
^Md
   (4)Z9     minutes of day
^MH
   99        minutes of Hour
^Hc
   (8)Z9     hours in calendar
^Hy
   (4)Z9     hours of year
^Hm
   (3)Z9     hours of month


^Hw
   (3)Z9     hours of week
^Hd
   99        hours of day
^Hh
   99        hours of half/day (12 hr time)
^mi
   a         Meridiem Indicator ("A" or "P")
^dc
   (7)Z9     days in calendar
^dy
   999       days of year (1-366)


^dm
   99        days of month (1-31)
^dw
   9         days of week (1-7)
^dn
   (32)X     day name (Friday)
^da
   (8)X      day abbreviation (Fri)
^my
   99        months of year
^mn
   (32)X     month name ("December")


^ma
   (8)X      month abbreviation ("Dec"")
^yc
   OO99      years in calendar
^zn
   (64)X     zone name ("Azores Time")
^za
   (8)X      zone abbreviation ("at ")
^zd
   s9999     zone differential ("-0700")
^fw
   OOO999    Fiscal Week
^fi
   xx        Fiscal Indicator ("FW" in english)


Examples:
The following table shows how date and times strings are displayed by
a variety of control strings.

     CONTROL STRING
        "DISPLAYED VALUE"
     ^mn ^Z9dm, ^9999yc
        "September 8, 1979"
     ^mn ^z9dm, ^9999yc
        "September  8, 1979"
     ^dm ^ma ^9999yc ^zn
        "08 Sep 1979 Mountain Standard Time"
     ^my/^dm/^yc  ^Hd^99v.9MH ^za ^da
        "09/08/79  0242.4 mst Sat"


     ^Hd:^MH:^SM^zd
        "02:42:25-0700"
     ^9999yc-^my-^dm__^Hd:^MH:^99.(6)9UM_^za_^da
        "1979-09-08__02:42:25.048634_mst_Sat"
     <-^<multics_time>xyz^<multics_date>->
        "<-02:42xyz09/08/79->"
