       Advanced Search           Log In | Not a Member? Contact ADC    Inside Macintosh: Operating System Utilities /
Chapter 4 - Date, Time, and Measurement Utilities / Date, Time, and Measurement Utilities Reference
Data Structures

### The Long Date-Time Record

In addition to the date-time record, system software provides the long date-time record, which extends the date-time record format by adding several more fields. This format lets you use dates and times with a much longer span (30,000 B.C. to 30,000 A.D.). In addition, the long date-time record allows conversions to different calendar systems, such as a lunar calendar.

The `LongDateRec` data type defines the format of the long date-time record.

```TYPE LongDateRec =
RECORD
CASE Integer OF
0:
(era:          Integer;    {era}
year:         Integer;    {year, from 30,081 B.C. }
{ to 29,940 A.D.}
month:        Integer;    {month}
day:          Integer;    {day of the month}
hour:         Integer;    {hour, from 0 to 23}
minute:       Integer;    {minute, from 0 to 59}
second:       Integer;    {second, from 0 to 59}
dayOfWeek:    Integer;    {day of the week}
dayOfYear:    Integer;    {day of the year}
weekOfYear:   Integer;    {week of the year}
pm:           Integer;    {morning/evening}
res1:         Integer;    {reserved}
res2:         Integer;    {reserved}
res3:         Integer);   {reserved}
1:
{index by LongDateField}
(list:         ARRAY[0..13] OF Integer);
2:
(eraAlt:       Integer;       {era}
oldDate:       DateTimeRec);  {date-time record}
END;
```
##### Field Description
`era`
The era, where 0 represents A.D., and -1 represents B.C.
`year`
The year, ranging from 30,081 B.C. to 29,940 A.D. Values outside this range produce unpredictable results in all fields of the record. Note that to indicate the year 1984, this field would store the integer 1984, not just 84. This field accepts input of 0 or negative values, but these values return the positive result of the value plus one for the year. For example, a `year` value of 0 returns 1, and a `year` value of -1993 returns 1994. Other fields are unaffected.
`month`
The month of the year, where 1 represents January, and 12 represents December. When you use the `LongSecondsToDate` and `LongDateToSeconds` procedures, `month` values greater than 12 cause a wraparound to a future year and month. A value of 0 in this field returns the 12th month of the previous year. For example, a `month` value of 0 and a `year` value of 1993 return 12 and 1992, respectively. A negative value in this field has the effect of subtracting that number from the first month of the given year. For example, a `month` value of -2 and a `year` value of 1993 return 10 and 1992, respectively.
`day`
The day of the month, ranging from 1 to 31. When using the `LongSecondsToDate` and `LongDateToSeconds` procedures, `day` values greater than the number of days in a given month cause a wraparound to a future month and day. This feature is useful for working with leap years. For example, the 366th day of January in 1992 (1992 was a leap year) evaluates as December 31, 1992, and the 367th day of that year evaluates as January 1, 1993. A value of 0 in this field produces unpredictable results in the `month` and `day` fields. A negative value in this field has the effect of subtracting that number from the first day of the given month. For example, a `day` value of -10 and a `month` value of 10 return 9 and 20, respectively.
`hour`
The hour of the day, ranging from 0 to 23, where 0 represents midnight and 23 represents 11:00 P.M. When you use the `LongSecondsToDate` and `LongDateToSeconds` procedures, `hour` values greater than 23 cause a wraparound to a future day and hour. A negative value in this field produces unpredictable results. Note that this field is always maintained in 24-hour time. The `pm` field, if used, is redundant.
`minute`
The minute of the hour, ranging from 0 to 59. When you use the `LongSecondsToDate` and `LongDateToSeconds` procedures, `minute` values greater than 59 cause a wraparound to a future hour and minute. A negative value in this field has the effect of subtracting that number from the first minute of the given hour. For example, an `hour` value of 10 and a `minute` value of -10 return 9 and 50, respectively. However, if the negative value causes the `hour` value to become less than 0, for example `hour` = 0 and `minute` = -61, unpredictable results occur.
`second`
The second of the minute, ranging from 0 to 59. When you use the `LongSecondsToDate` and `LongDateToSeconds` procedures, `second` values greater than 59 cause a wraparound to a future minute and second. A negative value in this field has the effect of subtracting that number from the first second of the given minute. For example, an `minute` value of 10 and a `second` value of -10 return 9 and 50, respectively. However, if the negative value causes the `hour` value to become less than 0, for example `hour` = 0, `minute` = 0, and `second` = -61, unpredictable results occur.
`dayOfWeek`
The day number of the week, where 1 indicates Sunday and 7 indicates Saturday. This field accepts 0, negative values, or values greater than 7. When you use the `LongSecondsToDate` and `LongDateToSeconds` procedures, you get correct values because this field is automatically calculated from the values in the `year`, `month`, and `day` fields. For calendars that have more than 7 day names and 12 month names (for example, the Jewish calendar sometimes has 13 months), you use the `'itl1'` resource, defined by the `Itl1ExtRec` data type. To get more information on the format of the `'itl1'` resource, see the appendix "International Resources" in Inside Macintosh: Text.
`dayOfYear`
The day number of the year, ranging from 1 to 366. Values greater than the number of days in a given year cause a wraparound to a future year and day. This feature is useful for working with leap years. For example, in a Gregorian calendar the 366th day of January in 1992 (1992 was a leap year) evaluates as December 31, 1992, and the 367th day of that year evaluates as January 1, 1993.
`weekOfYear`
The week number of the year, ranging from 1 to 52. Note that out-of-range values (such as 0, negative numbers, or numbers greater than 52) can be set for this field. However, you can use the `LongSecondsToDate` procedure to convert these out-of-range values to appropriate values.
`pm`
The morning or evening half of the 24-hour day cycle, where 0 represents the morning (for example, A.M.), and 1 represents the evening (for example, P.M.). Note that out-of-range values can be set for this field. However, you can use the `LongSecondsToDate` procedure to convert these out-of-range values to appropriate values.
`res1`
Reserved. Set this field to 0.
`res2`
Reserved. Set this field to 0.
`res3`
Reserved. Set this field to 0.
`list`
An array of `LongDateField` values. The `field` parameter of the `ToggleDate` function uses the enumerated data type `LongDateField` to indicate the `LongDateRec` fields that the `ValidDate` function should check. The following values are available:
`TYPE LongDateField = (eraField, yearField, monthField, dayField, hourField, minuteField, secondField, dayOfWeekField, dayOfYearField, weekOfYearField, pmField, res1Field, res2Field, res3Field);`
`eraAlt`
The era, where 0 represents A.D., and -1 represents B.C. Use this field and the `oldDate` field to convert from a date-time record.
`oldDate`
The date-time record to convert. Use this field and the `eraAlt` field to convert from a date-time record.         Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2004 Apple Computer, Inc. All rights reserved. | Terms of use | Privacy Notice