1 :Info: date_time_:  1991-01-03 date_time_
  2 
  3 The date_time_ system is a utility which encodes, decodes, adjusts, or
  4 formats a Multics standard calendar clock value.  The clock reading is
  5 assumed to be in microseconds relative to 1901-01-01 0:00 gmt.  The
  6 ASCII times involved may be one of several languages and in a choice of
  7 time zones around the world.
  8 
  9 
 10 Entry points in date_time_:
 11    (List is generated by the help command)
 12 
 13 
 14 :Entry:  date_time_:  1985-03-04 date_time_
 15 
 16 
 17 Function:  The date_time_ subroutine converts a system clock value to
 18 ASCII representation.  It will be in terms of the process default
 19 language and zone.
 20 
 21 
 22 Syntax:
 23 declare date_time_ entry (fixed bin(71), char(*));
 24 call date_time_ (clock, str);
 25 
 26 
 27 Arguments:
 28 clock
 29    is the clock value to be formatted.  (Input)
 30 str
 31    is the resultant character string.  (Output)
 32 
 33 
 34 Notes:  The format string which produces the resultant string is:
 35        "^my/^dm/^yc  ^Hd^99v.9MH ^xxxxza^xxxxda"
 36 which produces strings like this:
 37        mm/dd/yy  HHMM.M zzzddd
 38        07/14/83  1435.4 mst Thu
 39 See time_strings.gi for a description of acceptable strings.
 40 
 41 The ASCII representation of time, which date_time_ attempts to return
 42 in string, is 24 characters long.  If string is declared by the caller
 43 with a length of N and N is less than 24, then only the first N
 44 characters are returned.  If N is greater than 24, then the result is
 45 returned padded on the right with spaces.
 46 
 47 If clock is not a valid date, "01/01/01 0000.0 gmt Tue" is returned.
 48 
 49 
 50 :Entry:  format:  1985-03-04 date_time_$format
 51 
 52 
 53 Function:  This entry does a generalized formatting of a Multics
 54 standard calendar clock value.  A format string is supplied which
 55 describes the layout and content of the desired result.  The zone
 56 and/or language in which the result is to be displayed may be
 57 specified.
 58 
 59 
 60 Syntax:
 61 declare date_time_$format entry (char(*), fixed bin(71), char(*),
 62      char(*)) returns (char(250) var);
 63 result = date_time_$format (time_format, clock, zone, lang);
 64 
 65 
 66 Arguments:
 67 time_format
 68    either a keyword, or an ioa-like control string describing the
 69    desired result in terms of literal characters and date/time
 70    selectors.  (Input) See time_format.gi.info for details.
 71 clock
 72    a clock value to be displayed.  (Output)
 73 zone
 74    the short name of the zone in which output time value is expressed.
 75    (Input) "system_zone" means use the system default zone.  "" means
 76    use the per-process default zone.  (Input)
 77 lang
 78    the language in which month names, day names and time zones are
 79    expressed.  (Input) "system_lang" means use the system default time
 80    language.  "" means use per-process default time language.
 81 
 82 
 83 result
 84    is the string which is the result of the conversion.  (Output)
 85 
 86 
 87 Notes on time format:
 88 The control string to date_time_$format is either a keyword or a
 89 character string consisting of text and/or selectors.  The selectors
 90 are identified by a leading circumflex character (^).  There are 2
 91 types of selectors:
 92 
 93   ^<keyword>  allows a keyword to be imbedded within a format.
 94   ^XX         a 2 letter code identifying the wanted information.
 95 
 96 An optional PL/I picture specification may be placed between the ^ and
 97 XX if the default form is not adequate.
 98 
 99 
100 If the control string does not contain any circumflex characters, it
101 must then be one of the known set of keywords.  Each keyword
102 identifies a control string for a predetermined format named by that
103 keyword.
104 
105 For information about ^XX selectors, type:
106    help time_format.gi -scn selectors
107 
108 
109 List of format keywords:
110 all
111    ^9999yc-^my-^dm__^Hd:^MH:^99.(6)9UM^zd_^za_^da ^fi
112    ^(6)9fw ^ma dy^dy dc^dc Uc^Uc
113 calendar_clock
114    ^9999yc-^my-^dm__^Hd:^MH:^99.(6)9UM_^za_^da
115 clock
116    ^9999yc-^my-^dm ^Hd:^MH:^99.(6)9UM ^za ^da
117 date
118    the process default value for date
119 date_time
120    the process default value for date and time
121 iso_date
122    ^9999yc-^my-^dm
123 
124 
125 iso_date_time
126    ^9999yc-^my-^dm ^Hd:^MH:^SM ^za
127 iso_long_date
128    ^9999yc-^my-^dm ^da
129 iso_long_date_time
130    ^9999yc-^my-^dm ^Hd:^MH:^99.(6)9UM ^za
131 iso_long_time
132    ^Hd:^MH:^99.(6)9UM
133 iso_time
134    ^Hd:^MH:^SM
135 multics_date
136    ^my/^dm/^yc
137 multics_date_time
138    ^my/^dm/^yc ^Hd^99v.9MH ^xxxxza^xxxda
139 
140 
141 multics_time
142    ^Hd:^MH
143 request_id
144    ^yc^my^dm^Hd^MH^99.(6)9UM
145 system_date_time
146    the system default value for date and time
147 system_date
148    the system default value for date
149 system_time
150    the system default value for time
151 time
152    the process default value for time
153 
154 
155    A site may change the "system" keywords.  To list the "system"
156    keywords for your site, type:
157 
158       print_time_defaults -system
159 
160    For an application which depends upon the historic date/time
161    formats, the 3 builtin "multics" keywords are available.
162 
163 
164 :Entry:  format_max_length:  1985-03-04 date_time_$format_max_length
165 
166 
167 Function:  This entry returns the length of the longest result which a
168 format can generate.  The zone and/or language in which to work may be
169 specified.
170 
171 
172 Syntax:
173 declare date time_$format_max_length entry (char(*), char(*), char(*))
174      returns (fixed bin);
175 max_len = date_time_$format_max_length (format, zone, lang);
176 
177 
178 Arguments:
179 format
180    a control string intended to be given to date_time_$format.  (Input)
181    b..argx zone the short name of the zone in which conversion will be
182    done.  (Input) "system_zone" means use the system default zone.  ""
183    means use the per-process default zone.  (input)
184 lang
185    the language in which month names and time zones are expressed.
186    "system_lang" means use the system default time language.  "" means
187    use per-process default time language.
188 max_len
189    is the length of the longest string which can result from processing
190    the given format.  (Output)
191 
192 
193 :Entry:  from_clock:  1985-03-04 date_time_$from_clock
194 
195 
196 Function:  Given a Multics standard calendar clock value and an output
197 time zone name, return the month, day of the month, the year, the hour
198 of the day, the minute of the hour, the second of the minute, the
199 number of microseconds, the day in week, the day in year, and the day
200 in clock.  The caller may specify one of the time zones in the
201 time_info_ in which the decoded clock value is to be expressed, or may
202 request that the value be expressed in one of the default time zones.
203 
204 
205 Syntax:
206 declare date_time_$from_clock entry (fixed bin(71), char(*), ptr, fixed
207      bin(35));
208 call date_time_$from_clock (clock, zone, addr(time_value), code);
209 
210 
211 Arguments:
212 clock
213    is the binary clock value to be decoded.  (Input)
214 zone
215    the short name of the zone in which output time value is expressed.
216    (Input) "system_zone" means use the system default zone.  "" means
217    use the per-process default zone.
218 time_value
219    is the structure containing time parts.  (Output)
220 code
221    is a standard status code.  (Output)
222 
223 
224 :Entry:  from_clock_interval:  1985-03-04 date_time_$from_clock_interval
225 
226 
227 Function:  Given two clock values, return the number of years, months,
228 weeks, days, hours, minutes, seconds, and microseconds between them.
229 The set of units to use is specified, as well as whether any are to
230 include the fractional remainder.
231 
232 
233 Syntax:
234 declare date_time_$from_clock_interval entry (fixed bin(71), fixed
235      bin(71), ptr, fixed bin(35));
236 call date_time_$from_clock_interval (clock1, clock2, addr
237      (time_offsets), code);
238 
239 
240 Arguments:
241 clock1
242    is the base time value.  (Input) The output is expressed relative to
243    this binary clock value.
244 clock2
245    is the offset time value.  (Input) clock1 is in essence subtracted
246    from this value.  If this value is later than clock1, all results
247    will be positive.  If this value is earlier, all results will be
248    negative.
249 time_offsets
250    is the structure containing resulting time values.  (Output) The
251    structure is defined in time_offset.incl.pl1
252 code
253    is a standard status code.  (Output)
254 
255 
256 :Entry:  fstime:  1985-03-04 date_time_$fstime
257 
258 
259 Function:  This entry performs the same function as date_time_ given a
260 36-bit storage system date value.
261 
262 
263 Syntax:
264 declare date_time_$fstime entry (bit(36) aligned, char(*));
265 call date_time_$fstime (ssclock, str);
266 
267 
268 Arguments:
269 ssclock
270    is an internal storage system clock value.  (Input)
271 str
272    is the resultant character string.  (Output)
273 
274 
275 :Entry:  offset_to_clock:  1985-03-04 date_time_$offset_to_clock
276 
277 
278 Function:  This entry point creates a new Multics clock value by
279 adjusting an input clock value to a specified day-of-week and then
280 adding relative date/time offsets.  The relative date/time values
281 include a year offset, month offset, week offset, day offset, hour
282 offset, minute offset, second offset, and microsecond offset.  Any of
283 these values may be zero (no offset from input clock value) or negative
284 (backwards offset from input clock value).  In addition, an input time
285 zone is specified.
286 
287 
288 Syntax:
289 declare date_time_$offset_to_clock entry (ptr, fixed bin(71), char(*),
290      fixed bin(71), fixed bin(35));
291 call date_time_$offset_to_clock (addr(time_offset), clock_in, zone,
292      clock, code);
293 
294 
295 Arguments:
296 time_offset
297    is the structure containing time offsets to be applied.  (Input)
298    Structure is defined in time_offset.incl.pl1.
299 clock_in
300    is the clock value to which offsets are applied.  (Input)
301 zone
302    is the zone in which clock_in is to be interpreted.  (Input)
303 clock
304    is the resulting clock value.  (Output)
305 code
306    is a standard status code.  (Output)
307 
308 
309 :Entry:  set_lang:  1985-03-04 date_time_$set_lang
310 
311 
312 Function:  This entry sets or resets the user's default time language.
313 
314 
315 Syntax:
316 declare date_time_$set_lang entry (char(*), fixed bin(35));
317 call date_time_$set_lang (lang, code);
318 
319 
320 Arguments:
321 lang
322    the language which is to be made current.  (Input) "system_lang"
323    means use the system default time language.
324 code
325    is a standard status code.  (Output)
326 
327 
328 :Entry:  set_zone:  1985-03-04 date_time_$set_zone
329 
330 
331 Function:  This entry sets or resets the user's default zone.
332 
333 
334 Syntax:
335 declare date_time_$set_zone entry (char(*), fixed bin(35));
336 call date_time_$set_zone (zone code);
337 
338 
339 Arguments:
340 zone
341    the short name of the zone which is to be made current.  (Input)
342    "system_zone" means use the system default zone.
343 code
344    is a standard status code.  (Output)
345 
346 
347 :Entry:  to_clock:  1985-03-04 date_time_$to_clock
348 
349 
350 Function:  Given any or all of the following - years, months, days,
351 hours, minutes, seconds, microseconds, day in week, day in year, or day
352 in clock - returns a standard clock value which represents the encoding
353 of these values.  All the values must be valid, i.e.  not greater than
354 23, etc.
355 
356 
357 Syntax:
358 declare date_time_$to_clock entry (ptr, fixed bin(71), fixed bin(35));
359 call date_time_$to_clock (addr (time_value), clock, code);
360 
361 
362 Arguments:
363 time_value
364    is the structure containing time parts.  (Input) The structure is
365    defined in time_value.incl.pl1.
366 clock
367    is the encoded clock value.  (Output)
368 code
369    is a standard status code.  (Output)
370 
371 
372 :Entry:  valid_format:  1985-03-04 date_time_$valid_format
373 
374 
375 Function:  This entry checks the validity of a format string using
376 precisely the same tests as date_time_$format.
377 
378 
379 Syntax:
380 declare date_time_$valid_format entry (char(*), fixed bin,
381    fixed bin(35));
382 call date_time_$valid_format (format, errloc, code);
383 
384 
385 Arguments:
386 format
387    either a keyword, or an ioa-like control string describing the
388    desired result in terms of literal characters and date/time
389    selectors.  (Input) See the date_time_$format entry point for a
390    description of valid format strings.
391 errloc
392    is the character index in the format string where the error
393    occurred.  (Output) This is meaningful only if it and code are both
394    nonzero.
395 code
396    is a standard status code.  (Output)
397 
398 
399 :hcom:
400 
401 
402 
403 /****^  HISTORY COMMENTS:
404   1) change(2020-06-15,GDixon), approve(2021-02-22,MCR10088),
405      audit(2021-05-27,Swenson), install(2021-05-27,MR12.6g-0056):
406       A) Fix problem in header of date_time_ subroutine entrypoint.
407       B) Clarify contents of date_time_$format "Notes on time format"
408          section.
409                                                    END HISTORY COMMENTS */
410 
411 
412