The Tcl date/time API library module has the file name datime.tcl. This module manipulates and converts dates and times.

Here is a list of procedures in this library module:

• datime_month_name_2_num
• datime_month_num_2_name
• get_ftime
• get_time
• datime_hour12_2_hour24
• datime_get_ampm
• run_year
• days_in_month
• isleap
• juldate
• datdif

Module Dependencies

The following modules are required along with this module:

• parse.tcl

Module Definition Files

This module requires the definition file:

• stdhead.tcl

Module Procedures

datime_month_name_2_num

Declaration  : proc datime_month_name_2_num {mname}
Parameters   :
      Name   : mname
      Type   : string
Description  : month name

Returns      : month number upon success, zero otherwise

This procedure will convert a month name to a month number. Only the first three characters of the month name are compared so you may use the long or short month names. January is considered month one.

datime_month_num_2_name

Declaration  : proc datime_month_num_2_name {mnum mname}
Parameters   :
      Name   : mnum
      Type   : positive integer
      Range  : 1-12
Description  : month number (jan=1)

      Name   : mname
      Type   : string
Description  : output month name

Returns      : 1 upon success, 0 otherwise

This procedure will translate a month number to the short month name and place the result into the output month name.

get_ftime

Declaration  : proc get_ftime {}

Returns      : formatted date/time string

This procedure will format and return the current time string. Returned format is:

   yyyy/mm/dd hh:mm:ss

get_time

Declaration  : proc get_time {}

Returns      : formatted date/time string

This procedure will format and place a date/time string into the returned date/time string. The format of the string will be a series of digits in the form:

   yyyymmddhhmmss

The string uses no delimiters and can therefore be considered fixed length.

datime_hour12_2_hour24

Declaration  : proc datime_hour12_2_hour24 {intime outime sep_flag}
Parameters   :
      Name   : intime
      Type   : time string
Description  : input time

      Name   : outime
      Type   : time string
Description  : output time

      Name   : sep_flag
      Type   : boolean number(0-1)
Description  : separator flag

Returns      : 1 upon success, 0 otherwise

This procedure will convert a time string expressed in 12 hour format to a time string expressed in 24 format. The input time may be in any of the following formats:

• hh[:mm][:ss]p, hh[:mm][:ss] p, hh[:mm][:ss]pm, hh[:mm][:ss] pm
• hh[:mm][:ss]a, hh[:mm][:ss] a, hh[:mm][:ss]am, hh[:mm][:ss] am
• hh[:mm][:ss]m, hh[:mm][:ss] m, hh[:mm][:ss]n, hh[:mm][:ss] n

Where p and pm are the same, a and am are also the same. A trailing m indicates midnight and a trailing n indicates noon. When a trailing m or n is used, the time is assumed to be 12:00 regardless of any other hour/minute value. Spaces may or may not be present after the time and before the am or pm designator. The colon separator is required in the input time string. The separator flag is used to indicate whether the output time should have a colon separator. The minute and seconds fields are completely optional. The output time always contains two digits each for the hour, minute and optional seconds. The hour and minute are always present in the output time. Seconds are only present in the output time if present in the input time. Procedure returns the converted time loaded into the output time upon success.

datime_get_ampm

Declaration  : proc datime_get_ampm {wrd ap)
Parameters   :
      Name   : wrd
      Type   : string
Description  : time string

      Name   : ap
      Type   : string
Description  : output designator

Returns      : 1 upon success, 0 otherwise

This procedure will get the am, pm designator in the time string. If found, the designator will be removed from the time string and a single character will be loaded into the output designator. Acceptable designators in the time string are a, am, p, pm, n and m.

run_year

Declaration  : proc run_year {}

Returns      : run year upon success, zero otherwise

This procedure will get the year of program run via the get_time procedure.

days_in_month

Declaration  : proc days_in_month {year month}
Parameters   :
      Name   : year
      Type   : positive integer
Description  : full year (with century)

      Name   : month
      Type   : positive integer
Description  : month number (jan=1)

Returns      : number of days in month upon success, zero otherwise

This procedure will determine the number of days in a month taking into account leap years.

isleap

Declaration  : proc isleap {year}
Parameters   :
      Name   : year
      Type   : positive integer
Description  : full year (with century)

Returns      : 1 upon a leap year, 0 otherwise

This procedure will determine whether the full year is a leap year.

juldate

Declaration  : proc juldate {dte julout}
Parameters   :
      Name   : dte
      Type   : integer
Description  : input date (in the form yyyymmdd)

      Name   : julout
Description  : output Julian number

Returns      : 1 upon success, 0 otherwise

This procedure will convert the input date to a Julian value using DATIME_JUL_BASE (defined in this module) as the base year. Upon success the Julian number will be loaded into the output Julian number.

datdif

Declaration  : proc datdif {d1 d2 difout)
Parameters   :
      Name   : d1
      Type   : integer
Description  : input date 1 (in the form yyyymmdd)

      Name   : d2
      Type   : integer
Description  : input date 2 (in the form yyyymmdd)

      Name   : difout
      Type   : integer
Description  : output date difference

Returns      : 1 upon success, 0 otherwise

This procedure will calculate the number of days difference between two dates. The input date 1 is assumed to be the later of the two dates. Upon success the number of days difference will be loaded into the output date difference.