int = LunarOccultationOnDate(nDate, nMoonDataSourceIndex, nPlanetOrStar)
A lunar occultation occurs when the Moon passes in front of another body. This macro function returns the local time of the global maximum of the lunar occultation of nPlanetOrStar on nDate, provided the observing-condition checks pass at the location of Moon data source nMoonDataSourceIndex.
•A successful result is the local time in millionths of a day, obtained by multiplying the fractional day by 1000000 and truncating. It ranges from 0 to 999999; 0 is a valid midnight result. The return value contains no occultation-type code.
•The result is -1 if no qualifying global maximum falls on nDate, or if the observing-condition checks fail. Test for >= 0 to detect a returned event.
The global maximum describes the occultation as an event for the Earth as a whole. It is not the time of a local contact or local maximum. Passing the observing-condition filter does not establish that the Moon actually covers the body from the selected location.
At the event instant, both bodies must be more than 4° from the Sun, the Sun's true altitude must be below 0°, and both bodies must pass a topocentric apparent-altitude test: strictly greater than 8 arcminutes (about 0.1333°) for the Moon, and strictly greater than 0° for the other body. Topocentric means as seen from the selected observer's location; apparent altitude includes atmospheric refraction. These geometric checks do not guarantee detection through actual weather, haze or obstructions.
Supported occulted bodies are Mercury through Pluto and the catalogued stars (indices 2–29 in astronomical bodies). The Sun and Moon are excluded. Use a calculated Moon data source, selected by nMoonDataSourceIndex. Dates and returned times use that source's local-time settings.
This example lists global maxima of lunar occultations of planets whose observing-condition checks pass for Moon data source 1, on the date of the incoming macro token.
sResult = ''
for nPlanet = n_MERCURY to n_PLUTO step 1
nTime = LunarOccultationOnDate(n_TokenDate,1,nPlanet)
if nTime >= 0
sBuffer = 'Global maximum of the lunar occultation of ' + PlanetName(nPlanet)
sBuffer = sBuffer + ' at ' + FormatTime('hh:nn',nTime,true)
if sResult <> ''
sResult = sResult + chr(13)
endif
sResult = sResult + sBuffer
endif
endfor
One millionth of a day represents 0.0864 seconds in the time encoding; this specifies the units, not a guarantee of subsecond calculation accuracy.
See also: lunar occultation classifications (not encoded in this return value), SolarEclipseOnDate.
Topic 180065, last updated on 12-Oct-2026
