[Dart-dev] [3985] DART/trunk/time_manager/time_manager_mod.html: Initial documentation for the time manager functions.
nancy at ucar.edu
nancy at ucar.edu
Wed Aug 5 18:25:12 MDT 2009
An HTML attachment was scrubbed...
URL: http://mailman.ucar.edu/pipermail/dart-dev/attachments/20090805/c4fd2463/attachment-0001.html
-------------- next part --------------
Added: DART/trunk/time_manager/time_manager_mod.html
===================================================================
--- DART/trunk/time_manager/time_manager_mod.html (rev 0)
+++ DART/trunk/time_manager/time_manager_mod.html 2009-08-06 00:25:12 UTC (rev 3985)
@@ -0,0 +1,1031 @@
+<HTML>
+<HEAD>
+<TITLE>module time_manager_mod</TITLE>
+<link rel="stylesheet" type="text/css" href="../doc/html/doc.css"></link>
+</HEAD>
+<BODY>
+<!--
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!! !!
+!! GNU General Public License !!
+!! !!
+!! This file is part of the Data Assimilation Research Testbed (DART). !!
+!! !!
+!! DART is free software; you can redistribute it and/or modify !!
+!! it and are expected to follow the terms of the GNU General Public !!
+!! License as published by the Free Software Foundation. !!
+!! !!
+!! DART is distributed in the hope that it will be useful, !!
+!! but WITHOUT ANY WARRANTY; without even the implied warranty of !!
+!! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the !!
+!! GNU General Public License for more details. !!
+!! !!
+!! You should have received a copy of the GNU General Public License !!
+!! along with DART; if not, write to: !!
+!! Free Software Foundation, Inc. !!
+!! 59 Temple Place, Suite 330 !!
+!! Boston, MA 02111-1307 USA !!
+!! or see: !!
+!! http://www.gnu.org/licenses/gpl.txt !!
+!! !!
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+-->
+
+<DIV ALIGN=CENTER>
+<A HREF="#Interface">INTERFACE</A> /
+<A HREF="#PublicEntities">PUBLIC COMPONENTS</A> /
+<A HREF="#Namelist">NAMELIST</A> /
+<A HREF="#FilesUsed">FILES</A> /
+<A HREF="#References">REFERENCES</A> /
+<A HREF="#Errors">ERRORS</A> /
+<A HREF="#KnownBugs">BUGS</A> /
+<A HREF="#FuturePlans">PLANS</A> /
+<A HREF="#PrivateComponents">PRIVATE COMPONENTS</A>
+</DIV>
+
+<!--==================================================================-->
+
+<H1>MODULE time_manager_mod</H1>
+<A NAME="HEADER"></A>
+
+<!--==================================================================-->
+
+<A NAME="OVERVIEW"></A>
+<HR>
+<H2>OVERVIEW</H2>
+
+<P>
+Provides a set of routines to manipulate both time and calendars
+of various types.
+</P> <P>
+Time intervals are stored and defined in terms of integer number
+of days and integer seconds. The minimum time resolution is 1 second.
+Mathematical operations (e.g. addition, subtraction, multiplication) are
+defined on these intervals. Seconds which roll over 86400 (the number
+of seconds in a day) are converted into days.
+</P> <P>
+Calendars interpret time intervals in terms of years, months, days.
+Various calendars commonly in use in the scientific community are
+supported.
+</P>
+
+<!--==================================================================-->
+
+<A NAME="OTHER MODULES USED"></A>
+<BR><HR><BR>
+<H2>OTHER MODULES USED</H2>
+<PRE>
+types_mod
+utilities_mod
+</PRE>
+
+<!--==================================================================-->
+<!--Note to authors. The first row of the table is different. -->
+
+<A NAME="Interface"></A>
+<BR><HR><BR>
+<H2>PUBLIC INTERFACE</H2>
+
+<TABLE>
+<TR><TD><em class=call>use time_manager_mod, only : </em></TD>
+ <TD><A HREF="#time_type">time_type</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#op_type">operator(+)</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#op_type">operator(-)</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#op_type">operator(*)</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#op_type">operator(/)</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#op_type">operator(>)</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#op_type">operator(>=)</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#op_type">operator(==)</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#op_type">operator(/=)</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#op_type">operator(<)</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#op_type">operator(<=)</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#op_type">operator(//)</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#set_time">set_time</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#set_time_missing">set_time_missing</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#increment_time">increment_time</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#decrement_time">decrement_time</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#get_time">get_time</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#interval_alarm">interval_alarm</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#repeat_alarm">repeat_alarm</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#cal_type">THIRTY_DAY_MONTHS</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#cal_type">JULIAN</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#cal_type">GREGORIAN</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#cal_type">NOLEAP</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#cal_type">NO_CALENDAR</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#cal_type">GREGORIAN_MARS</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#set_calendar_type">set_calendar_type</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#get_calendar_type">get_calendar_type</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#get_calendar_string">get_calendar_string</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#set_date">set_date</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#get_date">get_date</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#increment_date">increment_date</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#decrement_date">decrement_date</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#days_in_month">days_in_month</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#leap_year">leap_year</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#length_of_year">length_of_year</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#days_in_year">days_in_year</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#month_name">month_name</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#julian_day">julian_day</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#time_manager_init">time_manager_init</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#print_time">print_time</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#print_date">print_date</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#write_time">write_time</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#read_time">read_time</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#interactive_time">interactive_time</A></TD></TR>
+</TABLE>
+
+<H3 class=indent1>NOTES</H3>
+
+<P>
+No namelist at this time.
+<!-- Optional namelist interface -->
+<!-- <A HREF="#Namelist"><em class=code>&time_manager_mod_nml</em> </A> -->
+<!-- may be read from file <em class=file>input.nml</em>. -->
+</P>
+
+<!--==================================================================-->
+<!-- Declare all public entities ... -->
+<!-- duplicate public routines template as many times as necessary -->
+<!-- make sure you replace all yyyroutine?? strings -->
+<!--==================================================================-->
+
+<A NAME="PublicEntities"></A>
+<BR><HR><BR>
+<H2>PUBLIC COMPONENTS</H2>
+<BR>
+
+
+<!-- # functions: -->
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="set_time"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = set_time(seconds <em class=optionalcode>[, days]</em>) </em>
+<pre>
+type(time_type) :: <em class=code>set_time</em>
+integer, intent(in) :: <em class=code>seconds</em>
+integer, intent(in), optional :: <em class=optionalcode>days</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Fills a time type. If seconds are > 86400, they are converted
+into the appropriate number of days. Note that seconds are specified first.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>seconds</em></TD>
+ <TD>Number of seconds. If larger than 86400, they are converted
+ into the appropriate number of days.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>days</em></TD>
+ <TD>Number of days. Default is 0.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="set_time_missing"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = set_time_missing() </em>
+<pre>
+type(time_type) :: <em class=code>set_time_missing</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Set a time type to a missing value. The
+resulting time value will cause an error
+if used for an arithmetic operation or if get_time() is called.
+</P>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="increment_time"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = increment_time(time, seconds [, days]) </em>
+<pre>
+type(time_type) :: <em class=code>increment_time</em>
+type(time_type), intent(in) :: <em class=code>time</em>
+integer, intent(in) :: <em class=code>seconds</em>
+integer, intent(in), optional :: <em class=optionalcode>days</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Adds the specified number of seconds and optionally, days, to the
+given time and returns the new time. Increments cannot be negative
+(see decrement_time below).
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>time value to be incremented.</TD></TR>
+<TR><TD valign=top><em class=code>seconds</em></TD>
+ <TD>number of seconds to add to given time.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>days</em></TD>
+ <TD>optionally a number of days to add to the given time.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="decrement_time"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = decrement_time(time, seconds [, days]) </em>
+<pre>
+type(time_type) :: <em class=code>decrement_time</em>
+type(time_type), intent(in) :: <em class=code>time</em>
+integer, intent(in) :: <em class=code>seconds</em>
+integer, intent(in), optional :: <em class=optionalcode>days</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Subtract the specified number of seconds and optionally, days, to the
+given time and returns the new time. Decrements cannot be negative
+(see increment_time above).
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>time value to be decremented.</TD></TR>
+<TR><TD valign=top><em class=code>seconds</em></TD>
+ <TD>number of seconds to subtract from the given time.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>days</em></TD>
+ <TD>optionally a number of days to subtract from the given time.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="interval_alarm"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = interval_alarm(time, time_interval, alarm, alarm_interval) </em>
+<pre>
+logical :: <em class=code>interval_alarm</em>
+type(time_type), intent(in) :: <em class=code>time</em>
+type(time_type), intent(in) :: <em class=code>time_interval</em>
+type(time_type), intent(inout) :: <em class=code>alarm</em>
+type(time_type), intent(in) :: <em class=code>alarm_interval</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+ Supports a commonly used type of test on times for models. Given the
+ current time, and a time for an alarm, determines if this is the closest
+ time to the alarm time given a time step of time_interval. If this
+ is the closest time (alarm - time <= time_interval/2), the function
+ returns true and the alarm is incremented by the alarm_interval. Watch
+ for problems if the new alarm time is less than time + time_interval.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Current time.</TD></TR>
+<TR><TD valign=top><em class=code>time_interval</em></TD>
+ <TD>Bin size for determining if alarm time is close enough to now.</TD></TR>
+<TR><TD valign=top><em class=code>alarm</em></TD>
+ <TD>When alarm next goes off next. Updated by this routine.</TD></TR>
+<TR><TD valign=top><em class=code>alarm_interval</em></TD>
+ <TD>How often alarm goes off.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="repeat_alarm"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = repeat_alarm(time, alarm_frequency, alarm_length) </em>
+<pre>
+type(time_type) :: <em class=code>repeat_alarm</em>
+type(time_type), intent(in) :: <em class=code>time</em>
+type(time_type), intent(in) :: <em class=code>alarm_frequency</em>
+type(time_type), intent(in) :: <em class=code>alarm_length</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Repeat_alarm supports an alarm that goes off with alarm_frequency and
+lasts for alarm_length. If the nearest occurence of an alarm time
+is less than half an alarm_length from the input time, repeat_alarm
+is true. For instance, if the alarm_frequency is 1 day, and the
+alarm_length is 2 hours, then repeat_alarm is true from time 2300 on
+day n to time 0100 on day n + 1 for all n.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Current time.</TD></TR>
+<TR><TD valign=top><em class=code>alarm_frequency</em></TD>
+ <TD>How often the alarm goes off.</TD></TR>
+<TR><TD valign=top><em class=code>alarm_length</em></TD>
+ <TD>How long the alarm is true.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="get_calendar_type"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = get_calendar_type() </em>
+<pre>
+integer :: <em class=code>get_calendar_type</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Returns default calendar type for mapping from time to date.
+Calendar types are public integer parameters that define
+various calendars. See elsewhere in this file for the list.
+</P>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="set_date"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = set_date(year, month, day [, hours, minutes, seconds])</em>
+<pre>
+type(time_type) :: <em class=code>set_date</em>
+integer, intent(in) :: <em class=code>year</em>
+integer, intent(in) :: <em class=code>month</em>
+integer, intent(in) :: <em class=code>day</em>
+integer, intent(in), optional :: <em class=optionalcode>hours</em>
+integer, intent(in), optional :: <em class=optionalcode>minutes</em>
+integer, intent(in), optional :: <em class=optionalcode>seconds</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Given a date interpreted using the current calendar type,
+compute the corresponding time.
+P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>year</em></TD>
+ <TD>Integer year.</TD></TR>
+<TR><TD valign=top><em class=code>month</em></TD>
+ <TD>Integer month number.</TD></TR>
+<TR><TD valign=top><em class=code>day</em></TD>
+ <TD>Integer day number.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>hours</em></TD>
+ <TD>Integer hour. Default is 0.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>minutes</em></TD>
+ <TD>Integer minutes. Default is 0.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>seconds</em></TD>
+ <TD>Integer seconds. Default is 0.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="increment_date"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = increment_date(time [, years, months, days, hours, minutes, seconds])</em>
+<pre>
+type(time_type) :: <em class=code>increment_date</em>
+type(time_type), intent(in) :: <em class=code>time</em>
+integer, intent(in), optional :: <em class=optionalcode>years</em>
+integer, intent(in), optional :: <em class=optionalcode>months</em>
+integer, intent(in), optional :: <em class=optionalcode>days</em>
+integer, intent(in), optional :: <em class=optionalcode>hours</em>
+integer, intent(in), optional :: <em class=optionalcode>minutes</em>
+integer, intent(in), optional :: <em class=optionalcode>seconds</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Given a time and some date increment, compute a new time.
+The interpretation of the date depends on the currently selected
+calendar type.
+P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Current time.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>year</em></TD>
+ <TD>Integer years to add. Default is 0.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>month</em></TD>
+ <TD>Integer months to add. Default is 0.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>day</em></TD>
+ <TD>Integer days to add. Default is 0.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>hours</em></TD>
+ <TD>Integer hours to add. Default is 0.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>minutes</em></TD>
+ <TD>Integer minutes to add. Default is 0.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>seconds</em></TD>
+ <TD>Integer seconds to add. Default is 0.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="decrement_date"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = decrement_date(time [, years, months, days, hours, minutes, seconds])</em>
+<pre>
+type(time_type) :: <em class=code>decrement_date</em>
+type(time_type), intent(in) :: <em class=code>time</em>
+integer, intent(in), optional :: <em class=optionalcode>years</em>
+integer, intent(in), optional :: <em class=optionalcode>months</em>
+integer, intent(in), optional :: <em class=optionalcode>days</em>
+integer, intent(in), optional :: <em class=optionalcode>hours</em>
+integer, intent(in), optional :: <em class=optionalcode>minutes</em>
+integer, intent(in), optional :: <em class=optionalcode>seconds</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Given a time and some date decrement, compute a new time.
+The interpretation of the date depends on the currently selected
+calendar type.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Current time.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>year</em></TD>
+ <TD>Integer years to subtract. Default is 0.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>month</em></TD>
+ <TD>Integer months to subtract. Default is 0.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>day</em></TD>
+ <TD>Integer days to subtract. Default is 0.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>hours</em></TD>
+ <TD>Integer hours to subtract. Default is 0.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>minutes</em></TD>
+ <TD>Integer minutes to subtract. Default is 0.</TD></TR>
+<TR><TD valign=top><em class=optionalcode>seconds</em></TD>
+ <TD>Integer seconds to subtract. Default is 0.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="days_in_month"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = days_in_month(time) </em>
+<pre>
+integer :: <em class=code>days_in_month</em>
+type(time_type), intent(in) :: <em class=code>time</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Given a time, determine the month based on the currently
+selected calendar type and return the
+numbers of days in that month.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Current time.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="leap_year"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = leap_year(time) </em>
+<pre>
+logical :: <em class=code>leap_year</em>
+type(time_type),intent(in) :: <em class=code>time</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Given a time, determine if the current year is a leap
+year in the currently selected calendar type.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Current time.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="length_of_year"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = length_of_year() </em>
+<pre>
+integer :: <em class=code>length_of_year</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+For the currently selected calendar type, return the
+number of days in a year if that value is fixed (e.g. there are
+not leap years). For other calendar types, see
+<a href="#days_in_year">days_in_year()</a> which takes a time
+argument to determine the current year.
+</P>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="days_in_year"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = days_in_year(time) </em>
+<pre>
+integer :: <em class=code>days_in_year</em>
+type(time_type), intent(in) :: <em class=code>time</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Given a time, determine the year based on the currently
+selected calendar type and return the
+numbers of days in that year.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Current time.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="month_name"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = month_name(n) </em>
+<pre>
+character(len=9) :: <em class=code>month_name</em>
+integer, intent(in) :: <em class=code>n</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Return a character string containing the month name corresponding
+to the given month number.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>n</em></TD>
+ <TD>Month number. Must be between 1 and 12, inclusive.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="julian_day"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = julian_day(year, month, day) </em>
+<pre>
+integer :: <em class=code>julian_day</em>
+integer, intent(in) :: <em class=code>year</em>
+integer, intent(in) :: <em class=code>month</em>
+integer, intent(in) :: <em class=code>day</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Given a date in year/month/day format,
+compute the day number from the beginning of the year.
+The currently selected calendar type must be GREGORIAN.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>year</em></TD>
+ <TD>Year number in the Gregorian calendar.</TD></TR>
+<TR><TD valign=top><em class=code>month</em></TD>
+ <TD>Month number in the Gregorian calendar.</TD></TR>
+<TR><TD valign=top><em class=code>day</em></TD>
+ <TD>Day of month in the Gregorian calendar.</TD></TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A FUNCTION ========================-->
+<A NAME="read_time"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> var = read_time(file_unit [, form, ios_out]) </em>
+<pre>
+type(time_type) :: <em class=code>read_time</em>
+integer, intent(in) :: <em class=code>file_unit</em>
+character(len=*), intent(in), optional :: <em class=optionalcode>form</em>
+integer, intent(out), optional :: <em class=optionalcode>ios_out</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Read a time from the given file unit number. The unit must already
+be open. The default format is ascii/formatted. If an error is
+encountered and ios_out is specified, the error status will be returned
+to the caller; otherwise the error is fatal.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>file_unit</em></TD>
+ <TD>Integer file unit number of an already open file.</TD></TR>
+<TR><TD valign=top><em class=code>form</em></TD>
+ <TD>Format to read the time. Options are 'formatted'
+ or 'unformatted'. Default is 'formatted'.</TD></TR>
+<TR><TD valign=top><em class=code>ios_out</em></TD>
+ <TD>On error, if specified, the error status code is returned here.
+ If not specified, an error calls the standard error_handler and
+ exits.</TD></TR>
+</TABLE>
+<BR>
+
+
+<!-- # subroutines: -->
+
+<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+<A NAME="get_time"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> call get_time(time, seconds [, days])</em>
+<pre>
+type(time_type), intent(in) :: <em class=code>time</em>
+integer, intent(out) :: <em class=code>seconds</em>
+integer, intent(out), optional :: <em class=optionalcode>days</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Returns days and seconds ( < 86400 ) corresponding to a time.
+If the optional 'days' argument is not given, the days are converted
+to seconds and the total time is returned as seconds.
+Note that seconds preceeds days in the argument list.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Time to convert into seconds and days.</TD><TR>
+<TR><TD valign=top><em class=code>seconds</em></TD>
+ <TD>If days is specified, number of seconds in the current day.
+ Otherwise, total number of seconds in time.</TD><TR>
+<TR><TD valign=top><em class=code>days</em></TD>
+ <TD>If specified, number of days in time.</TD><TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+<A NAME="set_calendar_type"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> call set_calendar_type(mytype)</em>
+or
+<em class=call> call set_calendar_type(calstring)</em>
+<pre>
+integer, intent(in) :: <em class=code>mytype</em>
+ or
+character(len=*), intent(in) :: <em class=code>calstring</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Selects the current calendar type, for converting between time
+and year/month/day. The argument can either be one of the predefined
+calendar integer parameter types (see elsewhere in this file for
+the list of types), or a string which matches the name of the
+integer parameters. The string interface is especially suitable for
+namelist use.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>mytype</em></TD>
+ <TD>Integer parameter to select the calendar type.</TD><TR>
+</TABLE>
+or
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>calstring</em></TD>
+ <TD>Character string to select the calendar type.
+ Valid strings match the names of the integer parameters.</TD><TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+<A NAME="get_calendar_string"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> call get_calendar_string(mystring)</em>
+<pre>
+character(len=*), intent(out) :: <em class=code>mystring</em>
+</pre></div>
+<!-- for consistency, the arg name should be calstring, i think. -->
+<H3 class=indent1>Description</H3>
+<P>
+Return the character string corresponding to the
+currently selected calendar type.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>mystring</em></TD>
+ <TD>Character string corresponding to the current calendar type. </TD><TR>
+</TABLE>
+<BR>
+
+subroutine get_date(time, year, month, day, hour, minute, second)
+<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+<A NAME="get_date"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> call get_date(time, year, month, day, hour, minute, second)</em>
+<pre>
+type(time_type), intent(in) :: <em class=code>time</em>
+integer, intent(out) :: <em class=code>year</em>
+integer, intent(out) :: <em class=code>month</em>
+integer, intent(out) :: <em class=code>day</em>
+integer, intent(out) :: <em class=code>hour</em>
+integer, intent(out) :: <em class=code>minute</em>
+integer, intent(out) :: <em class=code>second</em>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Given a time, compute the corresponding date given the
+currently selected calendar type.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Input time. </TD><TR>
+<TR><TD valign=top><em class=code>year</em></TD>
+ <TD>Corresponding calendar year.</TD><TR>
+<TR><TD valign=top><em class=code>month</em></TD>
+ <TD>Corresponding calendar month.</TD><TR>
+<TR><TD valign=top><em class=code>day</em></TD>
+ <TD>Corresponding calendar day.</TD><TR>
+<TR><TD valign=top><em class=code>hour</em></TD>
+ <TD>Corresponding hour.</TD><TR>
+<TR><TD valign=top><em class=code>minute</em></TD>
+ <TD>Corresponding minute.</TD><TR>
+<TR><TD valign=top><em class=code>second</em></TD>
+ <TD>Corresponding second.</TD><TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+<A NAME="time_manager_init"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> call time_manager_init()</em>
+<pre>
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Initializes any internal data needed by the time manager code.
+Does not need to be called before using any of the time
+manager routines; it will be called internally before executing
+any of the other routines.
+</P>
+<BR>
+
+<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+<A NAME="print_time"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> call print_time(time [, str, iunit])</em>
+<pre>
+type(time_type), intent(in) :: <em class=code>time</em>
+character(len=*), intent(in), optional :: <em class=optionalcode>str</em>
+integer, intent(in), optional :: <em class=optionalcode>iunit</em>
+
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Print the time as days and seconds. If the optional str argument
+is specified, print that string as a label. If iunit is specified,
+write output to that unit; otherwise write to standard output/terminal.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Time to be printed as days/seconds. </TD><TR>
+<TR><TD valign=top><em class=optionalcode>str</em></TD>
+ <TD>String label to print before days/seconds. Default: 'TIME: '.</TD><TR>
+<TR><TD valign=top><em class=optionalcode>iunit</em></TD>
+ <TD>Unit number to write output on. Default is standard output/terminal
+ (unit 6).</TD><TR>
+</TABLE>
+<BR>
+
+subroutine print_date (time,str,iunit)
+<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+<A NAME="print_date"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> call print_date(time [, str, iunit])</em>
+<pre>
+type(time_type), intent(in) :: <em class=code>time</em>
+character(len=*), intent(in), optional :: <em class=optionalcode>str</em>
+integer, intent(in), optional :: <em class=optionalcode>iunit</em>
+
+</pre></div>
+<H3 class=indent1>Description</H3>
+<P>
+Print the time as year/month/day/hour/minute/second, as computed
+from the currently selected calendar type.
+If the optional str argument
+is specified, print that string as a label. If iunit is specified,
+write output to that unit; otherwise write to standard output/terminal.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Time to be printed as a calendar date/time. </TD><TR>
+<TR><TD valign=top><em class=optionalcode>str</em></TD>
+ <TD>String label to print before date. Default: 'DATE: '.</TD><TR>
+<TR><TD valign=top><em class=optionalcode>iunit</em></TD>
+ <TD>Unit number to write output on. Default is standard output/terminal
+ (unit 6).</TD><TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+<A NAME="write_time"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> call write_time(file_unit, time [, form, ios])</em>
+<pre>
+integer, intent(in) :: <em class=code>file_unit</em>
+type(time_type), intent(in) :: <em class=code>time</em>
+character(len=*), intent(in), optional :: <em class=optionalcode>form</em>
+integer, intent(out), optional :: <em class=optionalcode>ios</em>
+</pre></div>
+<!-- ios should be ios_out to match read_time (or visa versa) -->
+<H3 class=indent1>Description</H3>
+<P>
+Write a time to an already open file unit. The optional 'form'
+argument controls whether it is formatted or unformatted.
+On error, the optional 'ios' argument returns the error code; otherwise
+a fatal error is triggered.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>file_unit</em></TD>
+ <TD>Integer unit number for an already open file. </TD><TR>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Time to write to the file. </TD><TR>
+<TR><TD valign=top><em class=optionalcode>form</em></TD>
+ <TD>String format specifier; either 'unformatted' or 'formatted'.
+ Defaults to 'formatted'.</TD><TR>
+<TR><TD valign=top><em class=optionalcode>ios</em></TD>
+ <TD>If specified, on error the i/o status error code is returned here.
+ Otherwise, the standard error handler is called and the
+ program exits. </TD><TR>
+</TABLE>
+<BR>
+
+<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+<A NAME="interactive_time"></A>
+<P></P><HR><P></P>
+<div class=routine>
+<em class=call> call interactive_time(time)</em>
+<pre>
+type(time_type), intent(inout) :: <em class=code>time</em>
+</pre></div>
+<!-- should that not just be intent(out)? it is not read. -->
+<H3 class=indent1>Description</H3>
+<P>
+Prompt the user for a time as a calendar date, based on the
+currently selected calendar type. Writes prompt to standard output
+and reads from standard input.
+</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>time</em></TD>
+ <TD>Time type to be returned.</TD><TR>
+</TABLE>
+<BR>
+
+
+
+<!-- # derived types -->
+
+<!--=================== DESCRIPTION OF A LOCAL TYPE ==================-->
+
+<A NAME="time_type"></A>
+<BR><HR><BR>
+<div class=type><pre>
+<em class=call>type time_type</em>
+ private
+ integer :: seconds
+ integer :: days
+end type time_type
+</pre></div>
+
+<H3 class=indent1>Description</H3>
+<P>
+This type is used to define a time interval.
+</P>
+
+
+<!-- # parameters -->
+
+<!--=================== DESCRIPTION OF A PARAMETER ==================-->
+
+<A NAME="cal_type"></A>
+<BR><HR><BR>
+<div class=type><pre>
+ integer :: <em class=code>NO_CALENDAR</em>
+ integer :: <em class=code>GREGORIAN</em>
+ integer :: <em class=code>GREGORIAN_MARS</em>
+ integer :: <em class=code>JULIAN</em>
+ integer :: <em class=code>THIRTY_DAY_MONTHS</em>
+ integer :: <em class=code>NOLEAP</em>
+</pre></div>
+
+<H3 class=indent1>Description</H3>
+<P>
+The public integer parameters which define different calendar types.
+The same names defined as strings can be used to set the calendar type.
+</P>
+
+<!-- # operators -->
+
+<!--=================== DESCRIPTION OF AN OPERATOR ==================-->
+
+<A NAME="op_type"></A>
+<BR><HR><BR>
+<div class=type><pre>
+ <em class=code>operator(+)</em>
+ <em class=code>operator(-)</em>
+ <em class=code>operator(*)</em>
+ <em class=code>operator(/)</em>
+ <em class=code>operator(>)</em>
+ <em class=code>operator(>=)</em>
+ <em class=code>operator(==)</em>
+ <em class=code>operator(/=)</em>
+ <em class=code>operator(<)</em>
+ <em class=code>operator(<=)</em>
+ <em class=code>operator(//)</em>
+</pre></div>
+
+<H3 class=indent1>Description</H3>
+<P>
+Arithmetic operations are defined for time types, so expressions like
+<pre>
+<em class=code>t3 = t1 + t2</em>
+</pre>
+can be constructed. To use these operators, they must be listed
+on the module use statement in the form specified above.
+</P>
+<P>
+Multiplication is one time and one scalar.
+</P>
+<P>
+Division with a single slash is integer, and returns the largest
+integer for which time1 >= time2 * n. Division with a double slash
+returns a double precision quotient of the two times.
+</P>
+
+
+
+<!--============== DESCRIPTION OF A NAMELIST ========================-->
+ <A NAME="Namelist"></A>
+<BR><HR><BR>
+<H2>NAMELIST</H2>
+ <P> No namelist is currently defined for the time manager code.
+ <BR>
+
+
+<!--==================================================================-->
+<!-- Describe the Files Used by this module. -->
+<!--==================================================================-->
+
+<A NAME="FilesUsed"></A>
+<BR><HR><BR>
+<H2>FILES</H2>
+<UL>
+ None currently.
+</UL>
+
+<!--==================================================================-->
+<!-- Cite references, if need be. -->
+<!--==================================================================-->
+
+<A NAME="References"></A>
+<BR><HR><BR>
+<H2>REFERENCES</H2>
+
+<!--==================================================================-->
+<!-- Describe all the error conditions and codes. -->
+<!-- Putting a <BR> after the synopsis creates a nice effect. -->
+<!--==================================================================-->
+
+<A NAME="Errors"></A>
+<HR>
+<H2>ERROR CODES and CONDITIONS</H2>
+<div class="errors">
+<TABLE border=1 cellspacing=1 cellpadding=10 width=100%>
+<TR><TH>Routine</TH><TH>Message</TH><TH>Comment</TH></TR>
+
+<TR><!-- routine --><TD VALIGN=top></TD>
+ <!-- message --><TD VALIGN=top></TD>
+ <!-- comment --><TD VALIGN=top></TD>
+</TR>
+
+</TABLE>
+</div>
+
+<!--==================================================================-->
+<!-- Describe the bugs. -->
+<!--==================================================================-->
+
+<A NAME="KnownBugs"></A>
+<BR><HR><BR>
+<H2>KNOWN BUGS</H2>
+<P>
+none
+</P>
+
+<!--==================================================================-->
+<!-- Descibe Future Plans. -->
+<!--==================================================================-->
+
+<A NAME="FuturePlans"></A>
+<BR><HR><BR>
+<H2>FUTURE PLANS</H2>
+<P>
+none
+</P>
+
+<!--==================================================================-->
+<!-- Have not fleshed out this part yet ... ha ha ha -->
+<!--==================================================================-->
+
+<A NAME="PrivateComponents"></A>
+<BR><HR><BR>
+<H2>PRIVATE COMPONENTS</H2>
+<P>
+none
+</P>
+
+<!--==================================================================-->
+
+<HR>
+<TABLE summary="">
+<TR><TD>Contact: </TD><TD> Jeff Anderson, Tim Hoar </TD></TR>
@@ Diff output truncated at 40000 characters. @@
More information about the Dart-dev
mailing list