
                    RexxDate Function Package for OS/2

                               version 2.0

                    (c) Copyright Barry Pederson 1995
                          All rights Reserved.


What is RexxDate?

    RexxDate is a REXX function package for manipulating calendar dates.

What's New in version 2.0?

    Version 2.0 uses a different set of algorithms that extend the
    range of allowable dates from the old version 1.1 range of
    1/1/1970...12/31/2037 to the new version 2.0 range of 
    1/1/ 100...12/31/19999.
    (the new algorithms are actually valid back to 4713 B.C.)

    The basedate of RexxDate now matches the basedate of Rexx's 
    builtin Date() function, for dates after 9/14/1752.  So 
    RxDate() = Date('B').  This means that the exact values 
    returned by version 2.0 of RexxDate will be different from 
    the values of version 1.1.  (version 2.0 results should 
    equal version 1.1 results + 719162)

    Interpretation of dates is changed slightly. In version 1.1,
    when an input year was represented by a number in the range
    70..99 it was interpreted as a year in the twentieth century
    (1970..1999).  Numbers in the range 0..37 were interpreted
    as being in the twenty-first century (2000..2037).  Numbers
    in the range 38..69 would have represented invalid years.
    Version 2.0 is much simpler, years in the range 0..99 are 
    assumed to refer to the current century (whatever it happens 
    to be at the moment the function is executed). Years >= 100 
    are interpreted literally.

Requirements

    RexxDate requires OS/2 2.0 or later.

Installation & Removal

    The RexxDate function is contained in the REXXDATE.DLL file, which
    needs to be placed in a directory that appears in your LIBPATH.
    Before the date manipulation function can be used, it must be
    registered in REXX with code such as:

        /* check whether the RxDate Function is loaded, if not, load it */
        IF RxFuncQuery('RxDate')
            THEN CALL RxFuncAdd 'RxDate', 'RexxDate', 'RxDate'

    The DLL can be unloaded by exiting all CMD.EXE shells


The Function

    --------------------------------------------------
    rc = RxDate(<date-string>, <format-specifier>)
    --------------------------------------------------

        The first parameter is either an integer containing the number of
        days since 1/1/0001. or a date string in one of these forms:

            m-d    (current year is assumed)
            m-d-y
            y-m-d  (only if y > 12)

                ----------------------------------------------------
                Characters other than '-' can be used as separators
                Dates must be in the range 1/1/100 - 12/31/19999
                ----------------------------------------------------

        If the first parameter is omitted, then the current date will be
        assumed.

        If the second parameter is omitted, than an integer is returned
        containing the number of days between the specified day and
        1/1/0001.  If the date is out of the allowed range, -1 is returned.

        Arithmetic functions can be used to manipulate the returned
        values, for example:

            today = rxDate()
            tomorrow = today + 1
            yesterday = today - 1

            days_until_new_years_eve = rxDate('12/31') - today

        If the function is called with a second parameter, then the 
        function returns the date formatted according to the second 
        parameter.  If the date is out of the allowed range, the string
        "Error converting date" is returned.

        The second parameter should contain format-specifiers as used by
        the C strftime() function.  The specifiers relating to dates are:

            %a - abbreviated weekday name (Sun)
            %A - full weekday name (Sunday)
            %b - abbreviated month name (Dec)
            %B - full month name (December)
            %d - day of the month (01-31)
            %j - day of the year (001-366)
            %m - month (01-12)
            %U - week of the year, where Sunday is the first day (00-53)
            %w - weekday (0-6) where Sunday is 0
            %W - weekday (0-6) where Monday is 0
            %x - the date formatted according to the current locale
            %y - last two digits of the year (00-99)
            %Y - the year 
            %% - the percent character

        Here is an example:

            say 'Today is' rxDate(, '%A %B %d, %Y')

            sunday = rxDate() - rxDate(, '%w')

            say 'The week started on:' rxDate(sunday, '%x')
            say 'And ends on:' rxDate(sunday+6, '%x')

        should print something like:

            Today is Friday October 07, 1994
            The week started on: 10/02/94
            And ends on: 10/08/94


------------------------------------------------------------------------

    That's it, just one function.  But it allows you to do quite a bit,
    especially the second form of function with the format-specifiers.

    For comments or suggestions, mail to:

        bapeders@badlands.nodak.edu

    and I'd love to hear if anyone comes up with a good use for
    this DLL.

------------------------------------------------------------------------

Appendix & Credits from the Date Algorithm source code

        Translated from Pascal to C by Jim Van Zandt, July 1992.

        Error-free translation based on error-free PL/I source

        Based on Pascal code copyright 1985 by Michael A. Covington,
        published in P.C. Tech Journal, December 1985, based on formulae
        appearing in Astronomical Formulae for Calculators by Jean Meeus

        Reconversion to normal Julian epoch, integer arithmetic and
        4000-year correction by John W. Kennedy

        [The 4000-year adjustment is controversial.  It is not mentioned in
        the paper "Calendrical Calculations" by Nachum Dershowitz and
        Edward M.  Reingold in Software Practice and Experience, v 20 n 9
        pp 899-928 (Sep 1990).  I have left it in mainly because it will
        make no difference for a very long time.  - jvz]

        Historical exceptions _not_ allowed for in this package:

        Until Julius Caesar established the Julian calendar in 45 B.C.,
        calendars were irregular.  This package assumes the Julian calendar
        back to 4713 B.C.

        The Julian calendar was altered in 8 B.C.  From 45 B.C. to 8 B.C.,
        the months were
                Jan=31, Feb=29(30), Mar=31, Apr=30, May=31, Jun=30,
                Jul=31, Aug=30,     Sep=31, Oct=30, Nov=31, Dec=30
        This package assumes the month lengths as we know them.

        Leap years from 45 B.C.  to 8 A.D.  were miscalculated: (45, 42,
        39, 36, 33, 30, 27, 24, 21, 18, 15, 12, 9, then none at all until 8
        A.D.) This package assumes leap years every four years, as they
        were meant to have been.

        January 1 was not always the first day of the year.  The United
        Kingdom, in particular, started the year on March 25 until 1752.
        (However, the year ended on December 31, leaving the days between
        in limbo.) This package assumes January 1 is the first day of the
        year.

        Leap-year day was originally done by having February 24 (25 from 45
        to 8 B.C.) twice.  This package assumes Leap-year day is February
        29.

        "Transition" argument is the first Julian date to be considered as
        belonging to the Gregorian calendar.  Usual values are:

        2299161 = October 5/15, 1582,       as in Rome, or
        2361222 = September 3/14, 1752,     as in the United Kingdom
                                            and the Colonies
                                            (used by RexxDate 2.0)

--------------------------------------------------------------------------
