home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / fdater.zip / FDATER.DOC < prev    next >
Text File  |  1995-04-29  |  8KB  |  170 lines
  1. ======================================================================
  2.                        FDATER.REX
  3. A Rexx implementation of the Truedate date arithmetic routine
  4. Revision date of this file: 1995 Apr 29
  5. ======================================================================
  6. AUTHOR:     Stephen Ferg
  7.             608 N. Harrison Street
  8.             Arlington, VA 22203-1416
  9.             USA
  10.  
  11.             telephone (voice, not FAX): (703) 525-2241
  12.             CompuServe ID             : 73377,1157
  13.             Internet                  : ferg_s@bls.gov
  14.             Internet                  : 73377.1157@compuserve.com
  15.  
  16. =====================================================================
  17.  
  18. FDATER.REX is a REXX module for doing date arithmetic.
  19. FDATER is intended for business applications, not historical ones.
  20.  
  21. The source code of FDATER.REX has been placed in the public domain by
  22. its author, Stephen Ferg.  You may copy, use, and modify it as you wish.
  23.  
  24. To avoid confusion, although the actual source code of FDATER.REX has
  25. been placed in the public domain, its author, Stephen Ferg, wishes to
  26. retain copyright of the names "FDATER" and "FDATER.REX".  You may copy,
  27. use, and modify the code as you wish, but if you change it, please do
  28. not distribute the modified version under the names "FDATER" or
  29. "FDATER.REX", and please document any modifications that you have made
  30. to the original code.
  31.  
  32. FDATER.REX is a REXX implementation of the TRUEDATE algorithm that is
  33. presented in the article in the file TRUEDATE.TXT.  The main
  34. modification to the Truedate routines for the REXX implementation was to
  35. add code to convert REXX "base" dates to and from Truedate "absolute"
  36. dates.  This was necessary because Truedate and REXX have different
  37. conceptions of what a "base" date is.  On 1/1/1, Truedate will tell you
  38. that today is day 1, but REXX's DATE function with the "B" parm will
  39. tell you that 0 days have elapsed.  So Truedate and REXX's DATE function
  40. are one day out of sync.  FDATER.REX contains code to compensate for
  41. this difference.  It accepts REXX base dates through its interface, but
  42. converts them to/from Truedate "absolute dates" for internal use.
  43.  
  44.  
  45. FDATER'S BUSINESS VIEW OF THE CALENDAR
  46. --------------------------------------
  47.    FDATER is intended for business applications, not historical
  48.    ones.  FDATER does not take into account historical changes in the
  49.    calendar such as the ten days that were dropped from the British
  50.    calendar when Britain moved from the Julian to the Gregorian
  51.    calendar in the 18th century, or the 11 days that were dropped
  52.    from the Russian calendar when Russia made the same move in the
  53.    early 20th century.  As far as FDATER is concerned, the calendar
  54.    has followed the same pattern, unchanged, since January 1, 0001.
  55.  
  56. ======================================================================
  57. FDATER.REX can be called, as an external routine, from any REXX program,
  58. or copied into a REXX program and used as an internal routine.
  59.  
  60. FDATER takes two parameters, and returns one value.
  61.  
  62. The first parameter is always the name of one of the FDATER functions,
  63. such as "IsLeapYear" or "MonthName".  Parm #1 is NOT case-sensitive.
  64.  
  65. The second parameter is a string whose contents vary depending on the
  66. function specified in parm #1.  The appropriate values for parm #2 are
  67. documented below.
  68.  
  69. The value that FDATER returns will be as documented below, unless
  70. FDATER.REX detects invalid parameters, in which case it will return a
  71. multi-word message whose first word is "ERROR:"
  72.  
  73. The .ZIP file that contains FDATER.REX should also contain DRIVER.REX,
  74. which is a short demo program that shows how to call FDATER.REX.
  75.  
  76. ===================================================================
  77. MAIN EXAMPLE:
  78. ===================================================================
  79.   DueDate = date("B") + 60 /* payment date is 60 days from today */
  80.   result = FdateR("Base2Cal", DueDate)
  81.   parse var result CalYear CalMonth CalDay .
  82.  
  83.   MonthName = FdateR("Monthname", Calmonth)
  84.   DowNum    = FdateR("DowNum"   , DueDate )
  85.   DowName   = FdateR("DowName"  , Downum  )
  86.  
  87.   say "Payment due by" Downame"," Monthname CalDay"," CalYear
  88. ===================================================================
  89.  
  90.  
  91. ===================================================================
  92. DOCUMENTATION FOR EACH OF FDATER'S FUNCTIONS
  93. ===================================================================
  94.  
  95. ---------------------------------------------------------------
  96. Function: Convert a base date into a calendar date
  97. Parm #1 : "Base2Cal"
  98. Parm #2 : the number of the base date
  99. Returns : a single string containing
  100.           a calendar date in the form "CalYear CalMonth CalDay"
  101.           with the three date-parts separated by a space.
  102. EXAMPLE : See MAIN EXAMPLE (above)
  103.  
  104. ---------------------------------------------------------------
  105. Function: Convert a calendar date into a base date
  106. Parm #1 : "Cal2Base"
  107. Parm #2 : a single string containing
  108.           a calendar date in the form "CalYear CalMonth CalDay"
  109.           with the three date-parts separated by space(s).
  110. Returns : the number of the base date
  111. EXAMPLE :
  112.   /* break today's date apart into 3 separate parts */
  113.   StandardDate = date("S")
  114.   CalYear    = substr(StandardDate,1,4)
  115.   CalMonth   = substr(StandardDate,5,2)
  116.   CalDay     = substr(StandardDate,7,2)
  117.  
  118.   BaseDate = FdateR("Cal2Base", CalYear CalMonth CalDay)
  119.  
  120.   say "FdateR figures today's base date is:" BaseDate
  121.   say "REXX's DATE function   base date is:" date("B")
  122.  
  123. FOR ANOTHER EXAMPLE, SEE THE DRIVER.REX DEMO PROGRAM.
  124.  
  125. ---------------------------------------------------------------
  126. Function: tell whether a year is or is not a leap year
  127. Parm #1 : "IsLeapYear"
  128. Parm #2 : a number indicating a year, from 1 to 9999
  129. Returns : 1 if the year IS     a leapyear
  130.           0 if the year IS NOT a leapyear
  131. EXAMPLE :
  132.   CalYear = "1995"
  133.   IsLeapYear = FdateR("IsLeapYear", CalYear)
  134.   if IsLeapYear then say CalYear "is a leap year"
  135.   else               say CalYear "is NOT a leap year"
  136.  
  137. ---------------------------------------------------------------
  138. Function: Calculate the day of the week from the absolute date
  139. Parm #1 : "DowNum"
  140. Parm #2 : a number indicating an absolute date
  141. Returns : the number of the day of the week of that date
  142.           1 = Sunday ... 7 = Saturday
  143. EXAMPLE : See MAIN EXAMPLE (above)
  144.  
  145. ---------------------------------------------------------------
  146. Function: Calculate English-language name of the month
  147. Parm #1 : "MonthName"
  148. Parm #2 : the number of the month (1-12, where 1 = January)
  149. Returns : the number of the day of the week of that date
  150. EXAMPLE : See MAIN EXAMPLE (above)
  151.  
  152. ---------------------------------------------------------------
  153. Function: Calculate English-language name of the day of the week
  154. Parm #1 : "DowName"
  155. Parm #2 : the number of the day  (1-7, where 1 = Sunday)
  156. Returns : the number of the day of the week of that date
  157. EXAMPLE : See MAIN EXAMPLE (above)
  158.  
  159. ===================================================================
  160. A TIP:
  161. ===================================================================
  162. When converting a date from calendar format to base format, FDATER will
  163. quite happily accept some invalid calendar dates (such as Sep 31) and
  164. convert them to a valid base date.  If FDATER is then used to convert
  165. that base date back to a calendar date, it will of course convert it to
  166. a valid calendar date (in this case, Oct 1).  So one use for FDATER is
  167. to check the validity of a calendar date by converting it to a base date
  168. and then converting the base date back to a calendar date.  If you got
  169. the same thing you started with, then the date is valid.
  170.