1 03/08/85  encode_clock_value_
  2 
  3 
  4 NOTE:
  5      encode_clock_value_ is replaced by date_time_$to_clock;
  6      encode_clock_value_ is supported for compatibility only.
  7 
  8 
  9 Entry points in encode_clock_value_:
 10    (List is generated by the help command)
 11 
 12 
 13 :Entry:  encode_clock_value_:  03/08/85  encode_clock_value_
 14 
 15 
 16 Function:
 17 The encode_clock_value_ subroutine takes a given month, day of the
 18 month, year, hour of the day, minute, second, microsecond, and time
 19 zone and returns a system clock reading.  When given a day of the week,
 20 it performs an optional check on the clock reading to ensure that it
 21 falls on the given day.
 22 
 23 A system clock reading is encoded as the number of microseconds from
 24 January 1, 1901 0000.0, Greenwich Mean Time (GMT) to the given date,
 25 time, and time zone.
 26 
 27 
 28 Syntax:
 29 declare encode_clock_value_ entry (fixed bin, fixed bin, fixed bin,
 30      fixed bin, fixed bin, fixed bin, fixed bin(71), fixed bin,
 31      char(3), fixed bin(71), fixed bin(35));
 32 call encode_clock_value_ (month, dom, year, hour, minute, second,
 33      microsecond, dow, zone, clock, code);
 34 
 35 
 36 Arguments:
 37 month
 38    is the month (January = 1, ..., December = 12).  (Input)
 39 dom
 40    is the day of the month, i.e., 1 to 31.  (Input)
 41 year
 42    is the year, e.g., 1982.  (Input)
 43 
 44 
 45 hour
 46    is the hour of the day (midnight = 0, ..., 11 PM = 23).  (Input)
 47 minute
 48    is the minute of the hour, i.e., 0 to 59.  (Input)
 49 second
 50    is the second of the minute, i.e., 0 to 59.  (Input)
 51 microsecond
 52    is the number of microseconds that are added to the clock reading
 53    encoded from the given month, dom, year, hour, minute, and second.
 54    (Input)
 55 
 56 
 57 dow
 58    is the day of the week (0 = no day of week checking, 1 = Monday,
 59    ..., 7 = Sunday).  (Input)
 60 zone
 61    is a three-character abbreviation of the time zone in which the
 62    given day of the month and hour are expressed.  (Input or Output)
 63    Input
 64       is one of the zone abbreviations given in the table of time zones
 65       (see the convert_date_to_binary_ subroutine), or is a null
 66       character string.  A zone abbreviation may be given in uppercase
 67       or lowercase.  If a null string is given, the current time zone
 68       used by the process is assumed.
 69    Output
 70       is a three-character lowercase abbreviation of the current time
 71       zone used by the process if a null character string was given as
 72       input.
 73 
 74 
 75 clock
 76    is the encoded system clock reading.  (Output)
 77 code
 78    is a system status code.  (Output)
 79 
 80 
 81 :Entry:  offsets:  03/08/85 encode_clock_value_$offsets
 82 
 83 
 84 NOTE:
 85      encode_clock_value_$offsets is replaced by
 86      date_time_$offset_to_clock; encode_clock_value_$offsets is
 87      supported for compatibility only.
 88 
 89 
 90 Function:
 91 This entry point takes a system clock reading, a day of the week, and
 92 year, month, day, hour, minute, second, and microsecond, offset values.
 93 The offset values may be positive, negative, or zero.  It returns a
 94 clock reading that has been adjusted to fall on the given day of the
 95 week, and which is then offset by the given number of years, months,
 96 days, hours, minutes, seconds, and microseconds.
 97 
 98 
 99 Syntax:
100 declare encode_clock_value_$offsets entry (fixed bin(71), fixed bin,
101      fixed bin, fixed bin, fixed bin, fixed bin, fixed bin,
102      fixed bin(71), fixed bin, char(3), fixed bin(71), fixed bin(35));
103 call encode_clock_value_$offsets (clock_in, month_off, day_off,
104      year_off, hour_off, minute_off, second_off, microsec_off,
105      dow_offset, zone, clock_out, code);
106 
107 
108 Arguments:
109 clock_in
110    is a system clock reading.  (Input)
111 month_off
112    is an offset, in months.  (Input)
113 day_off
114    is an offset, in days.  (Input)
115 year_off
116    is an offset, in years.  (Input)
117 
118 
119 hour_off
120    is an offset, in hours.  (Input)
121 minute_off
122    is an offset, in minutes.  (Input)
123 second_off
124    is an offset, in seconds.  (Input)
125 microsec_off
126    is an offset, in microseconds.  (Input)
127 dow_off
128    is a day of the week offset (0 = no day of week offset,
129    1 = offset to next Monday, ..., 7 = offset to next Sunday).  (Input)
130 
131 
132 zone
133    is a three-character abbreviation of the time zone in which the
134    input clock reading is to be interpreted.  (Input or Output) The
135    choice of zone may alter which day of the week the input clock
136    reading falls on, and may therefore affect any day of the week
137    adjustment.
138    Input
139       is one of the zone abbreviations given in the table of time zones
140       (see the convert_date_to_binary_ subroutine), or is a null
141       character string.  A zone abbreviation may be given in uppercase
142       or lowercase.  If a null string is given, the current time zone
143       used by the process is assumed.
144    Output
145       is a three-character lowercase abbreviation of the current time
146       zone used by the process if a null character string was given as
147       input.
148 
149 
150 clock_out
151    is the adjusted clock reading.  (Output)
152 code
153    is a system status code.  (Output)
154 
155 
156 Notes:  The order in which offsets are applied to the input clock
157 reading can affect the adjusted clock reading.  The
158 encode_clock_value_$offsets entry point uses the order required by the
159 convert_date_to_binary_ subroutine in all cases.  The offsets are
160 applied in the following order:
161 
162 1.   Decode the input clock reading into absolute date and time values
163      specified in terms of the input time zone.  The time zone can
164      alter the day of the week the input clock reading falls on, and
165      can therefore change the effect of the day of the week offset.
166 
167 2.   Apply any day of the week offset by adding days to the absolute
168      date values from step 1 until the date falls on the given day of
169      the week.
170 
171 3.   Apply any year offset to the absolute date values from step 2.
172 
173 4.   Apply any month offset to the absolute date values from step 3.
174      If applying the month offset results in an invalid date
175      (e.g., 1/31/77 +3 months yields 4/31/77), then adjust the day of
176      the month to be the last day of the new month, taking leap years
177      into account.
178 
179 5.   Apply the day offset to the absolute date values from step 4.
180 
181 6.   Apply the hour, minute, second, and microsecond offsets to the
182      absolute time values from step 1.
183 
184 7.   Encode the absolute date values from step 5 and absolute time
185      values from step 6 to form the adjusted clock reading.