Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Operating System Utilities /
Chapter 4 - Date, Time, and Measurement Utilities


Summary of the Date, Time, and Measurement Utilities

Pascal Summary

Constants

CONST
   {date equates for ToggleDate control bits}
   validDateFields      = -1;       {date fields are valid}
   genCdevRangeBit      = 27;       {restrict date/time to range used by }
                                    { General Controls control panel}
   togDelta12HourBit    = 28;       {if toggling hour up/down, restrict to }
                                    { 12-hour range}
   togCharZCycleBit     = 29;       {modifier for togChar12HourBit to }
                                    { accept hours 0..11 only}
   togChar12HourBit     = 30;       {if toggling hour by char, accept }
                                    { hours 1..12 only}
   smallDateBit         = 31;       {restrict valid date/time to range }
                                    { of Time global}

   {long date-time record field masks}
   eraMask              = $0001;    {era}
   yearMask             = $0002;    {year}
   monthMask            = $0004;    {month}
   dayMask              = $0008;    {day}
   hourMask             = $0010;    {hour}
   minuteMask           = $0020;    {minute}
   secondMask           = $0040;    {second}
   dayOfWeekMask        = $0080;    {day of the week}
   dayOfYearMask        = $0100;    {day of the year}
   weekOfYearMask       = $0200;    {week of the year}
   pmMask               = $0400;    {evening (P.M.)}

   {default value for togFlags field in the toggle parameter block }
   { and default value for the flags parameter passed to the Verify function}
   dateStdMask          = $007F;    {default value for checking era }
                                    { through second fields}

Data Types

TYPE 
   DateTimeRec =              {date-time record}
   RECORD
      year:       Integer;    {year}
      month:      Integer;    {month}
      day:        Integer;    {day of the month}
      hour:       Integer;    {hour}
      minute:     Integer;    {minute}
      second:     Integer;    {second}
      dayOfWeek:  Integer;    {day of the week}
   END;

   LongDateField =   {long date field enumeration}
                     (eraField, yearField, monthField, dayField,
                     hourField, minuteField, secondField,dayOfWeekField,
                     dayOfYearField,weekOfYearField, pmField, res1Field,
                     res2Field, res3Field);
   LongDateTime = comp;       {date and time in 64-bit SANE comp format}

   LongDateCvt =              {long date-time conversion record}
   RECORD
      CASE Integer OF
         0:
            (c:      comp);   {copy field into a variable of type }
                              { LongDateTime}
         1:
            (lHigh:  LongInt; {high-order 32 bits}
             lLow:   LongInt);{low-order 32 bits}
   END;

   LongDateRec =              {long date-time record}
   RECORD
      CASE Integer OF
         0:
            (era:          Integer;       {era}
             year:         Integer;       {year}
             month:        Integer;       {month}
             day:          Integer;       {day of the month}
             hour:         Integer;       {hour}
             minute:       Integer;       {minute}
             second:       Integer;       {second}
             dayOfWeek:    Integer;       {day of the week}
             dayOfYear:    Integer;       {day of the year}
             weekOfYear:   Integer;       {week of the year}
             pm:           Integer;       {half of day--0 for morning, }
                                          { 1 for 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;

   TogglePB =                    {toggle parameter block}
   RECORD
      togFlags:      LongInt;    {flags}
      amChars:       ResType;    {from 'itl0' resource, but made uppercase}
      pmChars:       ResType;    {from 'itl0' resource, but made uppercase}
                                 {reserved}
      reserved:      ARRAY[0..3] OF LongInt;

   END;

   ToggleResults = Integer;         {ToggleDate function return type}

   DateDelta = SignedByte;          {ToggleDate function delta field type}

   MachineLocation =                   {geographic location record}
   RECORD
      latitude:            Fract;      {latitude}
      longitude:           Fract;      {longitude}
      CASE Integer OF
         0:
            (dlsDelta:     SignedByte);{daylight savings time}
         1:
            (gmtDelta:     LongInt);   {Greenwich mean time}
   END;
   UnsignedWide =          {Microseconds procedure return type}
   PACKED RECORD
   hi:   longInt;       {high-order 32 bits}
   lo:   longInt;       {low-order 32 bits}
   END;

Routines

Getting the Current Date and Time

FUNCTION ReadDateTime		(VAR time: LongInt) : OSErr;
PROCEDURE GetDateTime 		(VAR secs: LongInt);
PROCEDURE GetTime 		(VAR d: DateTimeRec);

Setting the Current Date and Time

FUNCTION SetDateTime		(time: LongInt) : OSErr;
PROCEDURE SetTime		(d: DateTimeRec);

Converting Between Date-Time Formats

{each procedure has two spellings, see Table 4-4 for the alternate spelling}
PROCEDURE SecondsToDate 	(secs: LongInt; VAR d: DateTimeRec);
PROCEDURE DateToSeconds 	(d: DateTimeRec; VAR secs: LongInt);

Converting Between Long Date-Time Formats

{each procedure has two spellings, see Table 4-4 for the alternate spelling}
PROCEDURE LongSecondsToDate	(VAR lSecs: LongDateTime;
				VAR lDate: LongDateRec);
PROCEDURE LongDateToSeconds	(lDate: LongDateRec; VAR lSecs: LongDateTime);

Modifying and Verifying Long Date-Time Records

FUNCTION ToggleDate		(VAR lSecs: LongDateTime; field: LongDateField;
				delta: DateDelta; ch: Integer;
				params: TogglePB): ToggleResults;
FUNCTION ValidDate		(vDate: LongDateRec; flags: LongInt;
				VAR newSecs: LongDateTime): Integer;

Reading and Writing Location Data

PROCEDURE ReadLocation		(VAR loc: MachineLocation);
PROCEDURE WriteLocation		(VAR loc: MachineLocation);

Determining the Measurement System

{this function has two spellings, see Table 4-4 for the alternate spelling}
FUNCTION IsMetric:Boolean;

Measuring Time

PROCEDURE Microseconds		(VAR microTickCount UnsignedWide);

C Summary

Constants

enum
{
   /*date equates for ToggleDate control bits*/
   validDateFields      = -1,       /*date fields are valid*/
   genCdevRangeBit      = 27,       /*restrict date/time to range used by */
                                    /* General Controls control panel*/
   togDelta12HourBit    = 28,       /*if toggling hour up/down, restrict */
                                    /* to 12-hour range*/
   togCharZCycleBit     = 29,       /*modifier for TogChar12HourBit to */
                                    /* accept hours 0..11 only*/
   togChar12HourBit     = 30,       /*if toggling hour by char, accept */
                                    /* hours 1..12 only*/
   smallDateBit         = 31,       /*restrict valid date/time to range */
                                    /* of Time global*/

   /*long date-time record field masks*/
   eraMask              = 0x0001,   /*era*/
   yearMask             = 0x0002,   /*year*/
   monthMask            = 0x0004,   /*day*/
   dayMask              = 0x0008,   /*month*/
   hourMask             = 0x0010,   /*hour*/
   minuteMask           = 0x0020,   /*minute*/
   secondMask           = 0x0040,   /*second*/
   dayOfWeekMask        = 0x0080,   /*day of the week*/
   dayOfYearMask        = 0x0100,   /*day of the year*/
   weekOfYearMask       = 0x0200,   /*week of the year*/
   pmMask               = 0x0400    /*evening (P.M.)*/
};

enum
{
   /*default value for togFlags field in the toggle parameter block and */
   /* default value for the flags parameter passed to the Verify function*/
   dateStdMask          = 0x007F,   /*default value for checking era */
                                    /* through second fields*/
};

Data Types

struct DateTimeRec         /*date-time record*/
{
   short       year;       /*year*/
   short       month;      /*month*/
   short       day;        /*day of the month*/
   short       hour;       /*hour*/
   short       minute;     /*minute*/
   short       second;     /*second*/
   short       dayOfWeek;  /*day of the week*/
};
typedef struct DateTimeRec DateTimeRec;

enum                       /*long date field enumeration*/
{
   eraField, yearField, monthField, dayField, hourField, minuteField,
   secondField,dayOfWeekField, dayOfYearField, weekOfYearField, pmField,
   res1Field, res2Field, res3Field
};
typedef unsigned char LongDateField;

typedef comp LongDateTime;    /*date and time in 64-bit SANE comp format*/

union LongDateCvt             /*long date-time conversion record*/
{
   comp     c;                /*copy field into a LongDateTime variable*/
   struct
   {
      long  lHigh;            /*high-order 32 bits*/
      long  lLow;             /*low-order 32 bits*/
   } hl;
};
typedef union LongDateCvt LongDateCvt;

union LongDateRec             /*long date-time record*/
{
   struct
   {
      short era;              /*era*/
      short year;             /*year*/
      short month;            /*month*/
      short day;              /*day of the month*/
      short hour;             /*hour*/
      short minute;           /*minute*/
      short second;           /*second*/
      short dayOfWeek;        /*day of the week*/
      short dayOfYear;        /*day of the year*/
      short weekOfYear;       /*week of the year*/
      short pm;               /*half of day--0 for morning, 1 for evening*/
      short res1;             /*reserved*/
      short res2;             /*reserved*/
      short res3;             /*reserved*/
   } ld;
   short list[14];            /*index by LongDateField*/
   struct
   {
      short       eraAlt;     /*era*/
      DateTimeRec oldDate;    /*date-time record*/
   } od;
};
typedef union LongDateRec LongDateRec;

struct TogglePB               /*toggle parameter block*/
{
   long     togFlags;         /*flags*/
   ResType  amChars;          /*from 'itl0' resource, but made uppercase*/
   ResType  pmChars;          /*from 'itl0' resource, but made uppercase*/
   long     reserved[4];      /*reserved*/
};
typedef struct TogglePB TogglePB;
typedef short ToggleResults;  /*ToggleDate function return type*/
typedef char DateDelta;       /*ToggleDate function delta field type*/
struct MachineLocation        /*geographic location record*/
{
   Fract    latitude;         /*latitude*/
   Fract    longitude;        /*longitude*/
   union
   {
      char  dlsDelta;         /*daylight saving time*/
      long  gmtDelta;         /*Greenwich mean time*/
   } gmtFlags;
};
typedef struct MachineLocation MachineLocation;
struct UnsignedWide           /*Microseconds procedure return type*/
{
   unsigned long     hi;      /*high-order 32 bits*/
   unsigned long     lo;      /*high-order 32 bits*/
};
typedef struct UnsignedWide UnsignedWide;

Routines

Getting the Current Date and Time

pascal OSErr ReadDateTime	(unsigned long *time);
pascal void GetDateTime 	(unsigned long *secs);
pascal void GetTime 		(DateTimeRec *d);

Setting the Current Date and Time

pascal OSErr SetDateTime	(unsigned long time);
pascal void SetTime		(const DateTimeRec *d);

Converting Between Date-Time Formats

{each procedure has two spellings, see Table 4-4 for the alternate spelling}
pascal void SecondsToDate	(unsigned long secs, DateTimeRec *d);
pascal void DateToSeconds 	(const DateTimeRec *d, unsigned long *secs);

Converting Between Long Date-Time Formats

{each procedure has two spellings, see Table 4-4 for the alternate spelling}
pascal void LongSecondsToDate
   				(LongDateTime *lSecs, LongDateRec *lDate);
pascal void LongDateToSeconds
				(const LongDateRec *lDate, LongDateTime *lSecs);

Modifying and Verifying Long Date-Time Records

pascal ToggleResults ToggleDate
				(LongDateTime *lSecs, LongDateField field,
				DateDelta delta, short ch,
				const TogglePB *params);
pascal short ValidDate		(const LongDateRec vDate, long flags,
 				LongDateTime *newSecs);

Reading and Writing Location Data

pascal void ReadLocation	(MachineLocation *loc);
pascal void WriteLocation	(MachineLocation *loc);

Determining the Measurement System

{this functiosn has two spellings, see Table 4-4 for the alternate spelling}
pascal Boolean IsMetric		(void);

Measuring Time

pascal void Microseconds	(UnsignedWide *microTickCount);

Assembly-Language Summary

Data Structures

Date-Time Record
0dtYearwordyear
2dtMonthwordmonth
4dtDaywordday of the month
6dtHourwordhour
8dtMinutewordminute
10dtSecondwordsecond
12dtDayOfWeekwordday of the week

Long Date Field Enumeration
0eraFieldbyteera
1yearFieldbyteyear
2monthFieldbytemonth
3dayFieldbyteday of the month
4hourFieldbytehour
5minuteFieldbyteminute
6secondFieldbytesecond
7dayOfWeekFieldbyteday of the week
8dayOfYearFieldbyteday of the year
9weekOfYearFieldbyteweek of the year
10pmFieldbytepm
11res1Fieldbytereserved
12res2Fieldbytereserved
13res3Fieldbytereserved

Long Date-Time Value
0highLonglonghigh-order 32 bits
4lowLonglonglow-order 32 bits

Long Date-Time Record
0erawordera
2yearwordyear
4monthwordmonth
6daywordday of the month
8hourwordhour
10minutewordminute
12secondwordsecond
14dayOfWeekwordday of the week
16dayOfYearwordday of the year
18weekOfYearwordweek of the year
20pmwordhalf of day, morning or evening
22ldReserved6 bytesreserved

0latitudelonglatitude
4longitudelonglongitude
8dlsDeltabytedaylight savings time
9gmtDelta3 bytesGreenwich mean time
Geographic Location Record

Toggle Parameter Block
0togFlagslongflags
2amCharswordResType from 'itl0' made uppercase
4pmCharswordResType from 'itl0' made uppercase
6reservedwordreserved

Unsigned Wide Record
0hilonghigh-order 32 bits
4lolonglow-order 32 bits

Global Variables
TimeThe number of seconds since midnight, January 1, 1904

Result Codes
toggleErr59Reserved
toggleErr48Reserved
toggleErr37Reserved
toggleOutOfRange7Out of range (synonym for toggleErr3)
toggleBadNum6Tried to use character as number
toggleUnknown5Unknown error
toggleBadChar4Invalid character
toggleBadDelta3Invalid delta value
toggleBadField2Invalid field number
toggleOK1No error
toggleUndefined0Undefined error
noErr0No error
clkRdErr-85Unable to read clock
clkWrErr-86Time written did not verify


Previous Book Contents Book Index Next

© Apple Computer, Inc.
6 JUL 1996