Legacy Document

Inside Macintosh: Operating System Utilities /

Chapter 4 - Date, Time, and Measurement Utilities / Date, Time, and Measurement Utilities Reference

Routines / Modifying and Verifying Long Date-Time Records

ToggleDate

You can use the ToggleDate function to modify a date and time, by modifying one specific component of a date and time (day, hour, minute, seconds, day of week, and so on). For example, you can use the ToggleDate function to increase a date and time by one minute, decrease a date and time by one minute, or explicitly add or subtract a number of seconds to or from a date and time.

FUNCTION ToggleDate (VAR lSecs: LongDateTime;
                     field: LongDateField; delta: DateDelta;
                     ch: Integer; params: TogglePB)
                     : ToggleResults;

lSecs

The date-time information to modify, expressed as the number of seconds elapsed since midnight, January 1, 1904.

field

The name of the field in the date-time record you want modify. Use one of the LongDateField enumeration constants for the value of this parameter.

delta

A signed byte specifying the action you want to perform on the value specified in the field parameter. Set delta to 1, to increase the value in the field by 1. Set delta to -1, to decrease the value of the field by 1. Set delta to 0. If you want to set the value of the field explicitly; pass the new value through the ch field, described next.

ch

If the value in the delta field is 0, the value of the field in the date-time record (specified by the field parameter) is set to the value in the ch parameter. If the value in the delta field is not equal to 0, the value in the ch parameter is ignored.

params

The settings of the toggle parameter block settings. Note that you are responsible for setting this field.

-->	togFlags	LongInt	The fields to be checked by the ValidDate function.
-->	amChars	ResType	A.M. characters from 'itl0' resource.
-->	pmChars	ResType	P.M. characters from 'itl0' resource.
-->	reserved	ARRAY [0...3] OF LongInt	Reserved; set each element to 0.

DESCRIPTION

The ToggleDate function first converts the number of seconds, specified in the lSecs parameter, to a date and time--making each component of the date and time (day, minute, seconds, day of week, and so on) available through a long date-time record. The ToggleDate function then modifies the value of the field, specified by the field parameter. If the value in the delta field is greater than 0, the value of the field (specified in the field parameter) increases by 1; if the value in the delta field is less than 0, the value of the field decreases by 1; and if the value of delta is 0, the value of the field is explicitly set to the value specified in the ch field.

After the ToggleDate function modifies the field, it calls the ValidDate function. The ValidDate function checks the long date-time record for correctness, using the values of the togFlags field in the toggle parameter block that the ToggleDate function passes to it. If any of the record fields are invalid, the ValidDate function returns a LongDateField value corresponding to the field in error. Otherwise, it returns the result code for validDateFields. Note that ValidDate reports only the least significant erroneous field.

After the ToggleDate function checks the validity of the modified field, it converts the modified date and time back into a number of seconds (the number of seconds elapsed since midnight, January 1, 1904) and returns these seconds in the lSecs parameter.

The following constants specify the LongDateRec fields for the ValidDate function to check:

CONST
   eraMask              = $0001;    {verify the era}
   yearMask             = $0002;    {verify the year}
   monthMask            = $0004;    {verify the month}
   dayMask              = $0008;    {verify the day}
   hourMask             = $0010;    {verify the hour}
   minuteMask           = $0020;    {verify the minute}
   secondMask           = $0040;    {verify the second}
   dateStdMask          = $007F;    {verify the era through second}
   dayOfWeekMask        = $0080;    {verify the day of the week}
   dayOfYearMask        = $0100;    {verify the day of the year}
   weekOfYearMask       = $0200;    {verify the week of the year}
   pmMask               = $0400;    {verify the evening (P.M.)}

SPECIAL CONSIDERATIONS

Although ToggleDate does not move or purge memory, you should not call it at interrupt time.

RESULT CODES

The ToggleDate function returns its own set of result codes. The ToggleResults data type defines the result code of the ToggleDate function:

TYPE ToggleResults = Integer; {ToggleDate function return type}

The following list gives the result codes defined for this function:

toggleUndefined	0	Undefined error
toggleOK	1	No error
toggleBadField	2	Invalid field number
toggleBadDelta	3	Invalid delta value
toggleBadChar	4	Invalid character
toggleUnknown	5	Unknown error
toggleBadNum	6	Tried to use character as number
toggleOutOfRange	7	Out of range (synonym for toggleErr3)
toggleErr3	7	Reserved
toggleErr4	8	Reserved
toggleErr5	9	Reserved

SEE ALSO

To learn more about the LongDateTime data type, see page 4-25. For more information on the LongDateRec structure, see page 4-26. The toggle parameter block record is described on page 4-30.

For more information about the GetIntlResource function, see the chapter "Script Manager" in Inside Macintosh: Text. For details on the UppercaseText procedure, see the chapter "Text Utilities" in Inside Macintosh: Text. The ValidDate function is described next.