int = GetNextDateForHolidayId(nHolId,nYear)

 

This macro function will look for the next occurrence of the holiday of ID nHolId during the year nYear.

 

This function is based on the current position of the holidays table's cursor and, if a next holiday is found, then the table's cursor is moved to that next holiday.

 

➢To get the first occurrence of nHolId during nYear, call the function Reset_GetNextDateForHolidayId, to move the table's cursor back to the beginning of the table, before calling the function GetNextDateForHolidayId.

➢Independent search positions: the 2 groups of macro functions, FindNextHolidayOnDate / Reset_FindNextHolidayOnDate and GetNextDateForHolidayId / Reset_GetNextDateForHolidayId, use separate cursors to access the same holidays data. Each reset function resets only the cursor used by its corresponding search function. Consequently, macros can contains loops, mixing these groups of functions without losing the outer loop’s search position.

 

Important: the holidays set to which the holiday rule nHolId belongs needs be part of the script's aeiou-holidays or the current template's holidays override or in the list of included holidays. Otherwise holidays of that holidays set will not be brought into the temporary holidays table created at the beginning of diary generation (it will be as if there were no occurrences of nHolId at all).

 

Example 1: All the Occurrences of a Holiday in the Same Year

 

The macro code below gets the first occurrence of a holiday of nHolId during nYear, and then lists all the other ones (if there are any).

Reset_GetNextDateForHolidayId()
sResult = ''
nCurDate = GetNextDateForHolidayId(nHolId, nYear)
 
while nCurDate > 0
   if sResult <> ''
      sResult = sResult + ', '
   endif
   sResult = sResult + FormatDate('mmm d', nCurDate)
   nCurDate = GetNextDateForHolidayId(nHolId, nYear)
endwhile
 
if sResult == ''
   sResult = 'No occurrence in ' + IntToStr(nYear)
else
   sResult = 'Holiday occurs on ' + sResult
endif

The function GetNextDateForHolidayId will find holidays that fall twice in the same year, once in early January and once in late December, as happens for Muslim holidays. But the function will also find all the occurrences of multiday holidays, as well as days in lieu.

 

Example 2: The Occurrences of a Holiday over Many Years

 

The function GetNextDateForHolidayId can also be used to find the date of a given holiday for multiple years, to generate charts of holidays such as the one below, where the order of the holidays of years 2 and 3, must follow the order of the holidays in the first year.

 

 

The macro code below implements the procedure described in the image above, first FindNextHolidayOnDate to go through the list of 2018 holidays.

 

Then, for each 2018 holiday, it uses GetNextDateForHolidayId to get the dates of the holiday for 2019 and 2020 (to keep the code simple, we assume that each holiday occurs once only per year).

MAX_NUM_ITERATIONS 2000
MAX_STRING_LENGTH 8092
INCLUDE_HOLIDAYS_LIST a
 
input
    nHolSetID
var
    nStartYear nNumYears sDateFormat
    nRunDate nCurHolidayID sCurHolName nYear nCurDate
begin
    bResult = true
    sResult = ''
    nStartYear = 2018
    nNumYears = 3
    sDateFormat = 'Dddd Mmm d'
    // run over the entire first year of the chart
    for nRunDate = EncodeDate(nStartYear,1,1) to EncodeDate(nStartYear,12,31) step 1
       // for each date, look for one or more holidays
        Reset_FindNextHolidayOnDate()
        while FindNextHolidayOnDate(nRunDate,nHolSetID)
            // display the name of date of the first year
            nCurHolidayID = GetHolIdFromTable()
            sCurHolName = GetHolNameFromTable()
            sResult = sResult + sCurHolName // add the holiday name
            sResult = sResult + chr(9) // a tabulation
            sResult = sResult + FormatDate(sDateFormat, nRunDate) // the date
            // then get and display the dates for the remaining years
            for nYear = (nStartYear+1) to (nStartYear+nNumYears-1) step 1
                Reset_GetNextDateForHolidayId()
                nCurDate = GetNextDateForHolidayId(nCurHolidayID,nYear)
                sResult = sResult + chr(9) // a tabulation
                if nCurDate > 0
                    sResult = sResult + FormatDate(sDateFormat, nCurDate)
                endif
            endfor
            sResult = sResult + chr(13) // new line
        endwhile
    endfor
end

See also: Reset_GetNextDateForHolidayId, included holidays, and FindNextHolidayOnDate.

 

---

Topic 105134, last updated on 11-Oct-2026