ACS DateTime

I. Essentials

This document describes the design of the ACS DateTime service package.

II. Introduction

The ACS DateTime service is a collection of HTML widget generation procedures and date/time processing functions. The latter are built largely on top of the Tcl clock routines, although there are a small number of procedures that connect to the database for services like Julian date conversions.

Most the procedures defined within the ACS DateTime service take date/time information as input and return date/time strings to the caller. Rather than standardize on a low-level representation of time (like seconds since 00:00:00 UTC, January 1 1970) all of these procedures accept general date specifications. Internally dates are parsed by the standard Tcl procedure clock scan for processing and then converted back to a formatted string for output. This makes it easy to pass dates between the Tcl layer and the database.

III. Historical Considerations

This package was written largely to consolidate and improve the date, time, and calendar functionality existing in ACS 3.

IV. Competitive Analysis

None.

VI. Data Model Discussion

The ACS DateTime package does not have a data model.

VII. Legal Transactions

None.

VIII. API

Date and Time functions

See examples.

1. dt_systime generates current system time (local or GMT)
2. dt_sysdate generates current system date
3. dt_format formats a time using the formatting codes supported by the standard Unix time functions
4. dt_month_names generates a list of standard month names
5. dt_month_abbrev generates a list of standard month abbreviations
6. dt_julian_to_ansi converts Julian time to ANSI time (yyyy-mm-dd)
7. dt_ansi_to_pretty converts ANSI time to "pretty ANSI time" (yyyy-mm-dd to Month day, year)
8. dt_ansi_to_list generates a Tcl list of date-time elements (year, month, day, hour, minute, second)
9. dt_valid_time_p checks the validity of a time specification
10. dt_interval_check checks the validity of a time interval by comparing start and end times and determining if they represent a positive, empty, or negative time range

XII. Future Improvements/Areas of Likely Change

Many of the calendar widgets generate extensive HTML from within Tcl procedures. This will eventually be converted to a template-based system so that the display properties are more easily customized.

XIII. Authors

Implemented by Ron Henderson (ron\@arsdigita.com), based on the previous work of gregh\@arsdigita.com and smeeks\@arsdigita.com.