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->"


                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved