home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxdate20.zip / rexxdate.txt < prev    next >
Text File  |  1995-08-04  |  8KB  |  200 lines
  1.  
  2.                     RexxDate Function Package for OS/2
  3.  
  4.                                version 2.0
  5.  
  6.                     (c) Copyright Barry Pederson 1995
  7.                           All rights Reserved.
  8.  
  9.  
  10. What is RexxDate?
  11.  
  12.     RexxDate is a REXX function package for manipulating calendar dates.
  13.  
  14. What's New in version 2.0?
  15.  
  16.     Version 2.0 uses a different set of algorithms that extend the
  17.     range of allowable dates from the old version 1.1 range of
  18.     1/1/1970...12/31/2037 to the new version 2.0 range of 
  19.     1/1/ 100...12/31/19999.
  20.     (the new algorithms are actually valid back to 4713 B.C.)
  21.  
  22.     The basedate of RexxDate now matches the basedate of Rexx's 
  23.     builtin Date() function, for dates after 9/14/1752.  So 
  24.     RxDate() = Date('B').  This means that the exact values 
  25.     returned by version 2.0 of RexxDate will be different from 
  26.     the values of version 1.1.  (version 2.0 results should 
  27.     equal version 1.1 results + 719162)
  28.  
  29.     Interpretation of dates is changed slightly. In version 1.1,
  30.     when an input year was represented by a number in the range
  31.     70..99 it was interpreted as a year in the twentieth century
  32.     (1970..1999).  Numbers in the range 0..37 were interpreted
  33.     as being in the twenty-first century (2000..2037).  Numbers
  34.     in the range 38..69 would have represented invalid years.
  35.     Version 2.0 is much simpler, years in the range 0..99 are 
  36.     assumed to refer to the current century (whatever it happens 
  37.     to be at the moment the function is executed). Years >= 100 
  38.     are interpreted literally.
  39.  
  40. Requirements
  41.  
  42.     RexxDate requires OS/2 2.0 or later.
  43.  
  44. Installation & Removal
  45.  
  46.     The RexxDate function is contained in the REXXDATE.DLL file, which
  47.     needs to be placed in a directory that appears in your LIBPATH.
  48.     Before the date manipulation function can be used, it must be
  49.     registered in REXX with code such as:
  50.  
  51.         /* check whether the RxDate Function is loaded, if not, load it */
  52.         IF RxFuncQuery('RxDate')
  53.             THEN CALL RxFuncAdd 'RxDate', 'RexxDate', 'RxDate'
  54.  
  55.     The DLL can be unloaded by exiting all CMD.EXE shells
  56.  
  57.  
  58. The Function
  59.  
  60.     --------------------------------------------------
  61.     rc = RxDate(<date-string>, <format-specifier>)
  62.     --------------------------------------------------
  63.  
  64.         The first parameter is either an integer containing the number of
  65.         days since 1/1/0001. or a date string in one of these forms:
  66.  
  67.             m-d    (current year is assumed)
  68.             m-d-y
  69.             y-m-d  (only if y > 12)
  70.  
  71.                 ----------------------------------------------------
  72.                 Characters other than '-' can be used as separators
  73.                 Dates must be in the range 1/1/100 - 12/31/19999
  74.                 ----------------------------------------------------
  75.  
  76.         If the first parameter is omitted, then the current date will be
  77.         assumed.
  78.  
  79.         If the second parameter is omitted, than an integer is returned
  80.         containing the number of days between the specified day and
  81.         1/1/0001.  If the date is out of the allowed range, -1 is returned.
  82.  
  83.         Arithmetic functions can be used to manipulate the returned
  84.         values, for example:
  85.  
  86.             today = rxDate()
  87.             tomorrow = today + 1
  88.             yesterday = today - 1
  89.  
  90.             days_until_new_years_eve = rxDate('12/31') - today
  91.  
  92.         If the function is called with a second parameter, then the 
  93.         function returns the date formatted according to the second 
  94.         parameter.  If the date is out of the allowed range, the string
  95.         "Error converting date" is returned.
  96.  
  97.         The second parameter should contain format-specifiers as used by
  98.         the C strftime() function.  The specifiers relating to dates are:
  99.  
  100.             %a - abbreviated weekday name (Sun)
  101.             %A - full weekday name (Sunday)
  102.             %b - abbreviated month name (Dec)
  103.             %B - full month name (December)
  104.             %d - day of the month (01-31)
  105.             %j - day of the year (001-366)
  106.             %m - month (01-12)
  107.             %U - week of the year, where Sunday is the first day (00-53)
  108.             %w - weekday (0-6) where Sunday is 0
  109.             %W - weekday (0-6) where Monday is 0
  110.             %x - the date formatted according to the current locale
  111.             %y - last two digits of the year (00-99)
  112.             %Y - the year 
  113.             %% - the percent character
  114.  
  115.         Here is an example:
  116.  
  117.             say 'Today is' rxDate(, '%A %B %d, %Y')
  118.  
  119.             sunday = rxDate() - rxDate(, '%w')
  120.  
  121.             say 'The week started on:' rxDate(sunday, '%x')
  122.             say 'And ends on:' rxDate(sunday+6, '%x')
  123.  
  124.         should print something like:
  125.  
  126.             Today is Friday October 07, 1994
  127.             The week started on: 10/02/94
  128.             And ends on: 10/08/94
  129.  
  130.  
  131. ------------------------------------------------------------------------
  132.  
  133.     That's it, just one function.  But it allows you to do quite a bit,
  134.     especially the second form of function with the format-specifiers.
  135.  
  136.     For comments or suggestions, mail to:
  137.  
  138.         bapeders@badlands.nodak.edu
  139.  
  140.     and I'd love to hear if anyone comes up with a good use for
  141.     this DLL.
  142.  
  143. ------------------------------------------------------------------------
  144.  
  145. Appendix & Credits from the Date Algorithm source code
  146.  
  147.         Translated from Pascal to C by Jim Van Zandt, July 1992.
  148.  
  149.         Error-free translation based on error-free PL/I source
  150.  
  151.         Based on Pascal code copyright 1985 by Michael A. Covington,
  152.         published in P.C. Tech Journal, December 1985, based on formulae
  153.         appearing in Astronomical Formulae for Calculators by Jean Meeus
  154.  
  155.         Reconversion to normal Julian epoch, integer arithmetic and
  156.         4000-year correction by John W. Kennedy
  157.  
  158.         [The 4000-year adjustment is controversial.  It is not mentioned in
  159.         the paper "Calendrical Calculations" by Nachum Dershowitz and
  160.         Edward M.  Reingold in Software Practice and Experience, v 20 n 9
  161.         pp 899-928 (Sep 1990).  I have left it in mainly because it will
  162.         make no difference for a very long time.  - jvz]
  163.  
  164.         Historical exceptions _not_ allowed for in this package:
  165.  
  166.         Until Julius Caesar established the Julian calendar in 45 B.C.,
  167.         calendars were irregular.  This package assumes the Julian calendar
  168.         back to 4713 B.C.
  169.  
  170.         The Julian calendar was altered in 8 B.C.  From 45 B.C. to 8 B.C.,
  171.         the months were
  172.                 Jan=31, Feb=29(30), Mar=31, Apr=30, May=31, Jun=30,
  173.                 Jul=31, Aug=30,     Sep=31, Oct=30, Nov=31, Dec=30
  174.         This package assumes the month lengths as we know them.
  175.  
  176.         Leap years from 45 B.C.  to 8 A.D.  were miscalculated: (45, 42,
  177.         39, 36, 33, 30, 27, 24, 21, 18, 15, 12, 9, then none at all until 8
  178.         A.D.) This package assumes leap years every four years, as they
  179.         were meant to have been.
  180.  
  181.         January 1 was not always the first day of the year.  The United
  182.         Kingdom, in particular, started the year on March 25 until 1752.
  183.         (However, the year ended on December 31, leaving the days between
  184.         in limbo.) This package assumes January 1 is the first day of the
  185.         year.
  186.  
  187.         Leap-year day was originally done by having February 24 (25 from 45
  188.         to 8 B.C.) twice.  This package assumes Leap-year day is February
  189.         29.
  190.  
  191.         "Transition" argument is the first Julian date to be considered as
  192.         belonging to the Gregorian calendar.  Usual values are:
  193.  
  194.         2299161 = October 5/15, 1582,       as in Rome, or
  195.         2361222 = September 3/14, 1752,     as in the United Kingdom
  196.                                             and the Colonies
  197.                                             (used by RexxDate 2.0)
  198.  
  199. --------------------------------------------------------------------------
  200.