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: ^, 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) ----------------------------------------------------------- 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