RecurrencePattern Object

The RecurrencePattern object describes the recurrence pattern for an AppointmentItem object.

At a Glance

Properties

Methods

(None.)

Remarks

A RecurrencePattern object contains properties that fully specify the recurrence characteristics of an AppointmentItem object. It is created and linked to the appointment when you first call the AppointmentItem object's GetRecurrencePattern method. This sets the appointment's IsRecurring property to True and instantiates a new RecurrencePattern object populated with the default values indicated in the property descriptions.

The RecurrencePattern object applies only to its parent appointment and cannot be used for any other AppointmentItem object. The recurrence pattern can be accessed from any appointment in the recurring series, that is, from an individual recurrence as well as from the appointment that originated the series. The originating appointment can be obtained with the RecurrencePattern object's Parent property.

To edit the entire recurring series of appointments, you modify the appropriate properties on either the originating AppointmentItem object or its child RecurrencePattern object. To edit an individual recurrence only, you instantiate it and modify its AppointmentItem properties. You can instantiate an individual recurrence by using a MessageFilter object to restrict the Messages collection containing the appointments. All changes take effect when you call the appointment's Send or Update method.

If any change is made to the recurrence pattern after one or more individual recurrences have been instantiated, some or all of them may be automatically deleted. Microsoft® Outlook™ deletes all individual recurrences, while Microsoft® Schedule+ deletes only those that are earlier than the new PatternStartDate or later than the new PatternEndDate. CDO determines what your active calendar store is and deletes recurrences in the appropriate manner.

If you instantiate one or more individual recurrences and subsequently delete them all, Microsoft Outlook deletes the RecurrencePattern object. If CDO determines that your active calendar store is Outlook, it also deletes the RecurrencePattern object in this case.

The AppointmentItem object's ClearRecurrencePattern method resets IsRecurring to False and calls Release on the RecurrencePattern object. This is normally the final Release because the RecurrencePattern object should have no other references. The RecurrencePattern object is removed from memory in response to its final Release.

The RecurrenceType property determines the recurrence unit, the basic time unit for recurrence of the appointment. This can be a day, a week, a month, or a year. The appointment can recur on every instance of this recurrence unit, on isolated instances selected by the Instance property, or on periodic instances defined by the Interval property.

The DayOfMonth, DayOfWeekMask, and MonthOfYear properties specify the days and months when the appointment is to recur. The StartTime and EndTime properties determine the times of day for each occurrence. The PatternStartDate, PatternEndDate, Occurrences, and NoEndDate properties define the overall time period during which the appointment is to recur.

Several of the recurrence pattern properties have interdependent values. When you set one of these properties, related properties are forced into conformance in order to ensure consistency. For example, changing PatternEndDate causes Occurrences to be recalculated, and changing Occurrences causes PatternEndDate to be recalculated. The most recent change determines the settings of the interdependent properties. Each property description includes the effects of changing its value.

The pattern you specify in the DayOfMonth, DayOfWeekMask, Instance, Interval, and MonthOfYear properties is not required to include a recurrence on the day of the original appointment, nor on the days indicated in PatternStartDate or PatternEndDate. These days are counted in Occurrences only if they match the pattern, and a recurrence is generated on the starting or ending day only if that day matches the pattern.

This code fragment defines recurrence patterns for three AppointmentItem objects obtained from the Messages collection of a calendar folder. The first specifies recurrence on the third Friday of every month. The second and third specify recurrence on American Thanksgiving and Canadian Thanksgiving respectively.

Dim objApp3rdFri, objAppAmThx, objAppCanThx As AppointmentItem 
Dim objRec3rdFri, objRecAmThx, objRecCanThx As RecurrencePattern 
' ... assume all three AppointmentItem objects are valid ... 
' ... calling the GetRecurrencePattern method makes them recurring ... 
Set objRec3rdFri = objApp3rdFri.GetRecurrencePattern 
Set objRecAmThx = objAppAmThx.GetRecurrencePattern 
Set objRecCanThx = objAppCanThx.GetRecurrencePattern 
' every third Friday 
objRec3rdFri.RecurrenceType = CdoRecurTypeMonthlyNth 
objRec3rdFri.DayOfWeekMask = CdoFriday 
objRec3rdFri.Instance = 3 ' third instance of selected day 
objApp3rdFri.Update ' needed for settings to take effect in calendar 
' American Thanksgiving (fourth Thursday of November) 
objRecAmThx.RecurrenceType = CdoRecurTypeYearlyNth 
objRecAmThx.DayOfWeekMask = CdoThursday 
objRecAmThx.MonthOfYear = 11 ' November 
objRecAmThx.Instance = 4 
objAppAmThx.Update ' needed for settings to take effect in calendar 
' Canadian Thanksgiving (second Monday of October) 
objRecCanThx.RecurrenceType = CdoRecurTypeYearlyNth 
objRecCanThx.DayOfWeekMask = CdoMonday 
objRecCanThx.MonthOfYear = 10 ' October 
objRecCanThx.Instance = 2 
objAppCanThx.Update ' needed for settings to take effect in calendar