1 03/07/85 Formatting of Date/Time Data
2
3 This segment describes the functions available in date_time_$format
4 for building strings containing selected date/time information.
5
6
7 General:
8 The control string for the date_time_$format subroutine, clock
9 command, and other commands that expect a time_format argument is
10 either a keyword or a character string consisting of text and/or
11 selectors. The selectors are always identified by a leading
12 circumflex character ^. There are two types of selectors:
13 ^<keyword>, which allows a keyword to be embedded within a format, and
14 the general form ^XX. XX is a two-letter code that specifies what
15 information is wanted. You can place an optional PL/I picture
16 specification between the ^ and XX if the default form is not
17 adequate. If the control string does not contain any circumflex
18 characters, it must then be one of the known set of keywords. Each
19 keyword identifies a control string for a predetermined format named
20 by that keyword.
21
22
23 List of format keywords:
24 all
25 ^9999yc-^my-^dm__^Hd:^MH:^99.69UM^zd_^za_^da ^fi
26 ^69fw ^ma dy^dy dc^dc Uc^Uc
27 This line is broken only for publishing purposes
28 there is nothing between "^fi" and "^6".
29 calendar_clock
30 ^9999yc-^my-^dm__^Hd:^MH:^99.69UM_^za_^da.
31 clock
32 ^9999yc-^my-^dm ^Hd:^MH:^99.69UM ^za ^da.
33 date
34 is the process default value for date.
35 date_time
36 is the process default value for date and time.
37
38
39 iso_date
40 ^9999yc-^my-^dm.
41 iso_date_time
42 ^9999yc-^my-^dm ^Hd:^MH:^SM ^za.
43 iso_long_date
44 ^9999yc-^my-^dm ^da.
45 iso_long_date_time
46 ^9999yc-^my-^dm ^Hd:^MH:^99.69UM ^za.
47 iso_long_time
48 ^Hd:^MH:^99.69UM.
49 iso_time
50 ^Hd:^MH:^SM.
51 multics_date
52 ^my/^dm/^yc.
53
54
55 time
56 multics_date_time
57 ^my/^dm/^yc ^Hd^99v.9MH ^xxxxza^xxxda.
58 multics_time
59 ^Hd:^MH.
60 request_id
61 ^yc^my^dm^Hd^MH^99.69UM. The output from this keyword is
62 specified in the process default time zone; therefore if you want a
63 valid request-id specify -zone GMT in commands or give GMT as the
64 zone argument when calling date_time_$format with the request_id
65 keyword see request_ids.gi and Section 3 of the Programmer's
66 Reference Manual.
67 system_date_time
68 is the system default value for date and time.
69
70
71 system_date
72 is the system default value for date.
73 system_time
74 is the system default value for time.
75 time
76 is the process default value for time.
77
78 Your site can change the "system" strings. For an application that
79 depends upon the historic formats the three builtin "multics"
80 strings are available.
81
82
83 Notes on control strings:
84 Processing of a control string proceeds by scanning the control string
85 until a circumflex is found or the end of the string is reached. Any
86 text including any blanks passed over is copied to the output
87 string. The selector is then interpreted and executed. This causes a
88 datum from the input clock value to be edited into the output string.
89 Processing continues in this way until the control string is
90 exhausted.
91
92 You can express dates and times placed in the output string in units
93 of years months weeks days hours minutes seconds and
94 microseconds and the total calendar value as a single unit; for
95 example you could express the calendar value representing 79-09-08
96 9:42A GMT as 1979 years as 722702 days or as 722702.112499 days.
97
98
99 You can also express dates and times as the number of units remaining
100 after a larger unit has been removed from the calendar value; for
101 example 09/08/79 09:42 includes units for the 9th month of the year
102 the 8th day of the month the 9th hour of the day and the 42nd minute
103 of the hour.
104
105 There are several items of date/time data that are nonnumeric such as
106 day of week day of month and time zone used for conversion.
107
108
109 The selectors of numeric data are in general made up of two letters
110 taken from this sequence: c y m w d H M S U. This letters stand for
111 calendar year month week day hour minute second and
112 microsecond respectively. All 81 combinations are not however
113 valid. The form can generally be read as "unit of unit" e.g.
114 "seconds of week". The first unit is always smaller than the second
115 one. In trying to keep the specifiers reasonably mnemonic in
116 English there is a problem: both month and minute begin with an "m".
117 So all date values are used as lowercase letters while all time
118 values are in uppercase.
119
120
121 It is difficult to try to handle all the forms needed in a general
122 manner. Hd is hour of the day and is thus 24-hour time; this is not
123 always what is wanted. Hh is chosen as hour in half day to get the
124 12-hour form of time. To go along with this there is "mi" for
125 Meridiem Indicator which gives A or P to make up AM or PM. This does
126 not give AM or PM because ANSI and ISO standards specify that time be
127 given as "3P" not "3PM". If you want the M put the literal in
128 e.g. "^miM".
129
130 Another way of looking at a calendar value is in terms of fiscal week.
131 This is selected with the "^fw" code. Its value is four digits of
132 year followed by two digits of week number i.e. yyyyww. The default
133 picture has been chosen to give a value of yww. The associated fiscal
134 indicator is selected by "^fi". A complete value is obtained by
135 specifying "^fi^fw".
136
137
138 The table below shows the complete set of selectors. The row
139 specifies what unit is wanted the column specifies within what other
140 unit e.g. ^Sy is seconds of year.
141
142 DATE/TIME SELECTORS
143
144 | of | of | of | of | of | of | of | of |
145 |calen-| year |month | week | day | hour |minute|second|
146 -------| dar | | | | | | | |
147 micro- +------+------+------+------+------+------+------+------+
148 second | ^Uc | ^Uy | ^Um | ^Uw | ^Ud | ^UH | ^UM | ^US |
149 +------+------+------+------+------+------+------+------+
150 second | ^Sc | ^Sy | ^Sm | ^Sw | ^Sd | ^SH | ^SM |
151 +------+------+------+------+------+------+------+
152
153
154 +------+------+------+------+------+------+------+
155 minute | ^Mc | ^My | ^Mm | ^Mw | ^Md | ^MH |
156 +------+------+------+------+------+------+
157 hour | ^Hc | ^Hy | ^Hm | ^Hw | ^Hd |
158 +------+------+------+------+------+
159 day | ^dc | ^dy | ^dm | ^dw | month day zone
160 +------+------+------+------+ +------+------+------+
161 month | | ^my | name | ^mn | ^dn | ^zn |
162 +------+------+ +------+------+------+
163
164
165 +------+------+ +------+------+------+
166 year | ^yc | abbrev | ^ma | ^da | ^za |
167 +------+ +------+------+------+
168 | ^Hh | <-hour of half day differential | ^zd |
169 +------+ 12-hour form +------+
170 | ^mi | <-meridiem indicator "A" or "P"
171 +------+
172 | ^fw | <-fiscal week form: yyyyww
173 +------+
174 | ^fi | <-fiscal indicator "FW" in English
175 +------+
176
177
178 List of picture extensions: In addition to the normal picture
179 characters a selector has 3 additional ones. Normally pictures
180 are of fixed length. With the aid of these controls SPACEs or
181 ZEROs can be trimmed from a result.
182 X
183 This represents an output position just like an "x" but the
184 character output into this position will be dropped if it is part of
185 a string of rightmost SPACEs.
186 O
187 This represents an output position just like a "9" but the digit in
188 the position will be unconditionally omitted.
189 Z
190 This represents an output position just like a "9" but a ZERO in
191 the position will be dropped at either end if it is not
192 significant.
193
194
195 List of format selectors: This shows each selector its default
196 picture and its meaning.
197 ^Uc
198 18Z9 microseconds in calendar
199 ^Uy
200 14Z9 microseconds of year
201 ^Um
202 13Z9 microseconds of month
203 ^Uw
204 12Z9 microseconds of week
205 ^Ud
206 11Z9 microseconds of day
207 ^UH
208 10Z9 microseconds of Hour
209
210
211 ^UM
212 8Z9 microseconds of Minute
213 ^US
214 5Z9 microseconds of Second
215 ^Sc
216 12Z9 seconds in calendar
217 ^Sy
218 12Z9 seconds of year
219 ^Sm
220 8Z9 seconds of month
221 ^Sw
222 6Z9 seconds of week
223
224
225 ^Sd
226 5Z9 seconds of day
227 ^SH
228 4Z9 seconds of Hour
229 ^SM
230 99 seconds of Minute
231 ^Mc
232 10Z9 minutes in calendar
233 ^My
234 6Z9 minutes of year
235 ^Mm
236 5Z9 minutes of month
237
238
239 ^Mw
240 5Z9 minutes of week
241 ^Md
242 4Z9 minutes of day
243 ^MH
244 99 minutes of Hour
245 ^Hc
246 8Z9 hours in calendar
247 ^Hy
248 4Z9 hours of year
249 ^Hm
250 3Z9 hours of month
251
252
253 ^Hw
254 3Z9 hours of week
255 ^Hd
256 99 hours of day
257 ^Hh
258 99 hours of half/day 12 hr time
259 ^mi
260 a Meridiem Indicator "A" or "P"
261 ^dc
262 7Z9 days in calendar
263 ^dy
264 999 days of year 1-366
265
266
267 ^dm
268 99 days of month 1-31
269 ^dw
270 9 days of week 1-7
271 ^dn
272 32X day name Friday
273 ^da
274 8X day abbreviation Fri
275 ^my
276 99 months of year
277 ^mn
278 32X month name "December"
279
280
281 ^ma
282 8X month abbreviation "Dec""
283 ^yc
284 OO99 years in calendar
285 ^zn
286 64X zone name "Azores Time"
287 ^za
288 8X zone abbreviation "at "
289 ^zd
290 s9999 zone differential "-0700"
291 ^fw
292 OOO999 Fiscal Week
293 ^fi
294 xx Fiscal Indicator "FW" in english
295
296
297 Examples:
298 The following table shows how date and times strings are displayed by
299 a variety of control strings.
300
301 CONTROL STRING
302 "DISPLAYED VALUE"
303 ^mn ^Z9dm ^9999yc
304 "September 8 1979"
305 ^mn ^z9dm ^9999yc
306 "September 8 1979"
307 ^dm ^ma ^9999yc ^zn
308 "08 Sep 1979 Mountain Standard Time"
309 ^my/^dm/^yc ^Hd^99v.9MH ^za ^da
310 "09/08/79 0242.4 mst Sat"
311
312
313 ^Hd:^MH:^SM^zd
314 "02:42:25-0700"
315 ^9999yc-^my-^dm__^Hd:^MH:^99.69UM_^za_^da
316 "1979-09-08__02:42:25.048634_mst_Sat"
317 <-^<multics_time>xyz^<multics_date>->
318 "<-02:42xyz09/08/79->"