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