1 02/19/85  convert_date_to_binary_
  2 
  3 The convert_date_to_binary_ subroutine converts a character
  4 representation of a date and time into a 72-bit clock reading.  It
  5 accepts a wide variety of date and time forms, including the output of
  6 the date_time_ subroutine.
  7 
  8 
  9 Entry points in convert_date_to_binary_:
 10    (List is generated by the help command)
 11 
 12 
 13 :Entry: convert_date_to_binary_: 02/19/85  convert_date_to_binary_
 14 
 15 
 16 Function:
 17 converts a character representation of a date and time into a 72-bit
 18 clock reading.
 19 
 20 
 21 Syntax:
 22 declare convert_date_to_binary_ entry (char(*), fixed bin(71), fixed
 23      bin(35));
 24 call convert_date_to_binary_ (time_string, clock, code);
 25 
 26 
 27 Arguments:
 28 time_string
 29    the string to be converted.  (Input) See Time String below for a
 30    description of valid string values.
 31 
 32 clock
 33    the resulting clock value.  (Output) Unchanged if an error occurs.
 34 code
 35    is a standard status code.  (Output) It can have one of the
 36    following values:
 37    error_table_$bad_conversion
 38       a conversion condition occurred while trying to convert a value.
 39    error_table_$dt_ambiguous_time
 40       there is no language common to all words in the time string.
 41 
 42 
 43    error_table_$dt_bad_fw
 44       fiscal_week < 1 or fiscal_week > year_max (which is 52 or 53).
 45    error_table_$dt_hour_gt_twelve
 46       the hour given exceeds 12.
 47    error_table_$dt_multiple_date_spec
 48       more than one instance of a date has been given.
 49    error_table_$dt_multiple_diw_spec
 50       day of the week specified more than once.
 51    error_table_$dt_multiple_meaning
 52       the time string does not have the same meaning in all potential
 53       languages, these being the intersection of all the languages
 54       possible for all words present.
 55    error_table_$dt_multiple_time_spec
 56       more than one instance of a time has been given.
 57    error_table_$dt_multiple_zone_spec
 58       the zone may only be specified once.
 59 
 60 
 61    error_table_$dt_time_conversion_error
 62       For any of the following reasons:
 63       a.  General syntax error
 64       b.  Month without a day number.
 65       c.  Midnight or noon preceded by an hour other than 12.
 66       d.  Improper use of comma or period.
 67       e.  Improper use of offset.
 68    error_table_$dt_size_error
 69       the size condition occurred while converting the time string.
 70    error_table_$too_many_tokens
 71       the time string contains more tokens than the routine is prepared
 72       to handle.
 73    error_table_$dt_unknown_word
 74       a word in a time string is not found in the time_info_ token
 75       list.
 76 
 77 
 78 Time string:
 79 The time string can have up to six parts -- adverbial offset, date,
 80 time, day of week, signed offset, and time zone.  Adverbial offsets, if
 81 present, must appear leftmost in the string.  Beyond that, all of the
 82 parts are optional and may be in any order.  The parts may be made up
 83 of alphabetic fields, numeric fields, and special characters.
 84 
 85 An alphabetic field is made up of letters and must contain a whole word
 86 or an abbreviation (usually made up of the first three letters of the
 87 word).  No distinction is made between uppercase and lowercase
 88 characters.  Although this description gives examples in English, each
 89 of the words is available in several languages.  Any of these languages
 90 may be used in time strings, but all words within a given string must
 91 be in the same language.
 92 
 93 
 94 To see the languages defined on your site, type
 95           display_time_info -lang
 96 A numeric field consists of an optionally signed integer (or fraction)
 97 of one or more decimal digits.  The special characters that may be used
 98 in either alphabetic or numeric fields are:  the slash (/), the period
 99 (.), the colon (:), the plus (+), the minus (-), and the comma (,).
100 Blanks are not required between alphabetic and numeric fields in the
101 time strings; however, they are required between two numeric fields
102 unless the second field begins with a plus (+) or minus (-) sign.  For
103 example:
104         2days4hours10minutes
105         1245.17+7hours
106         10/17/79Wednesday
107 
108 
109 Underscores may be used in place of blanks in the time string.  For
110 example:
111           09/25/79__1442.6_+5_hours
112 
113 Usually when a user enters a time string, the time zone is omitted.
114 Although the zone is seldom seen, it is very important.  The time zone
115 determines the interpretation of items given in the time string.  Also,
116 the zone is involved in supplying defaults for missing items.  All
117 defaults are taken from the current absolute time, adjusted by a
118 working time zone.  If a zone is given in the string, that becomes the
119 working zone.  Otherwise, the process default time zone is used.
120 
121 
122 This means that whether you convert a string with an explicit zone,
123 such as "XXXX_ast" or set the process default to "ast" and then convert
124 the string "XXXX", you get the same absolute time.  (Note that setting
125 the process default will also influence output conversion, while giving
126 an explicit zone does not.)  To display your default zone, type:
127 
128           print_time_defaults zone
129 
130 
131 Multics accepts dates from the year 0001 through 9999.  The Julian
132 calendar is used for dates from 0001-01-01 through 1582-10-04.  The
133 Gregorian calendar is used for dates from 1582-10-15 through
134 9999-12-31.  (The dates from October 5, 1582 through October 14, 1582
135 do not exist.  They were dropped when the Gregorian calendar was
136 adopted.  The leap day is always February 29.  The lower limit on dates
137 of January 1, 0001 AD was picked since it begins the era.  The upper
138 limit on dates of December 31, 9999 was chosen to limit year numbers to
139 four digits.  The time zones as now defined are used regardless of the
140 year.  The Multics date/time system does not account for "leap seconds"
141 and, therefore, the difference between any two binary clock values that
142 are precisely an integral number of days (hours, minutes, seconds,
143 etc.)  apart is guaranteed to be evenly divisible by the number of
144 microseconds in a day (hour, minute, second, etc.).
145 
146 
147 Notes:
148 See the Subroutines manual for a description of the six parts contained
149 in time string.
150 
151 
152 :Entry:  relative:  02/19/85 convert_date_to_binary_$relative
153 
154 
155 Function:
156 This entry point is similar to the convert_date_to_binary_
157 entry point, except that the clock reading returned is computed
158 relative to an input clock time rather than the current clock time.
159 Thus the clock reading returned for the string "March 26" is the clock
160 reading for the first March 26 following the input clock time, rather
161 than the clock reading for the first March 26 following the current
162 clock time.  Given a 72-bit clock time to use, this entry point
163 converts a character representation of a date and time to the
164 equivalent 72-bit clock reading.
165 
166 
167 Syntax:
168 declare convert_date_to_binary_$relative entry (char(*), fixed bin(71),
169      fixed bin(71), fixed bin(35));
170 call convert_date_to_binary_$relative (string, clock, clock_in, code)
171 
172 
173 Arguments:
174 string
175    is the character representation of the clock reading desired.
176    (Input)
177 clock
178    is the computed clock value relative to the clock_in argument.
179    (Output)
180 clock_in
181    is the clock time used to compute the clock value.  (Input)
182 code
183    is a standard status code.  (Output)