home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / simtel / sigm / vols000 / vol023 / date.doc < prev    next >
Text File  |  1984-04-29  |  7KB  |  139 lines
  1. THE DATE LIBRARY
  2.  
  3. This package of routines :
  4. -- Allows a date to be entered in the relatively comfortable form of
  5.    number/separator/number/separator/number -- eg: 10-22-80 or 1/1/77.
  6.    The full year can also be entered [eg: 12-11-1980], although the
  7.    leading numbers are stripped, which means that 12-11-1680 equals
  8.    12-11-1980.
  9. -- Can insist that the entered year be within a specified range,
  10.    refusing to continue processing until the restrictions are
  11.    complied with.
  12. -- Converts the entered date into a two-byte integer value [in the range
  13.    1..maxint] which reflects the total number of days between the entered
  14.    date and Jan 1 of the program's base year. This means that calculations
  15.    made using this value do not have to take into consideration the
  16.    number of days in any given month -- or year for that matter.
  17. -- Breaks the date back into separate values for the month, date, year
  18.    and day of week [Sun..Sat].
  19. -- Prepares the broken date into strings with the various names spelled
  20.    out [eg: Thursday, January 1, 1981] or as a fixed eight place value
  21.    [11-11-80]. In the former the day-of-week name can be omitted and/or
  22.    names abbreviated and in the latter spaces can be substituted for
  23.    leading zeroes for the month and date [ie: 01-01-81 or  1- 1-80].
  24.  
  25. I have set the beast up in two forms: [1] separate .LIB modules for
  26. each routine, allowing them to be included in any Pascal program with
  27. the editor and [2] a complete external subprogram for separate compilation
  28. with ver 3.2 or later.
  29.  
  30. The separate routines are:
  31.  
  32. PROMPT                PROMPT.LIB
  33. This is actually a general-purpose routine, but it is specifically called
  34. by GETDATE. PROMPT is passed a string, pads it to a specified length,
  35. and writes it to the console. It allows pretty data entry.
  36.  
  37. MAKEDATE with GETDATE        MAKEDATE.LIB
  38. RMAKEDATE with RGETDATE        RMAKEDA.LIB
  39. Prompts the console to enter a date and returns the calculated integer
  40. value. RMAKEDATE is passed the minimum and maximum year values and
  41. checks to ensure that the entered value falls within the range.
  42.     GETDATE and RGETDATE perform the actual data entry. When compiled
  43. separately they are not accessible to the main program but if included
  44. within the program text these names obviously cannot be used for other
  45. routines.
  46.  
  47. BRKDATE                BRKDATE.LIB
  48. Breaks the integer date value into the month, day, year and weekday.
  49. Note that the latter is in the range 0..6 rather than 1..7. Breakdate
  50. fully corrects for leap years.
  51.  
  52. DASTRLONG            DASTRLON.LIB
  53. DASTRSHORT            DASTRSH.LIB
  54. DASTRFIXED            DASTRFIX.LIB
  55. The names are admittedly crunched a bit, but that's to fit within the
  56. six-character name limit for separate compilation.
  57.     Each function is passed a date value and returns a string in
  58. the appropriate format. They all use BRKDATE. DASTRLONG spells out all
  59. words while DASTRSHORT abbreviates the month and day name [but not with
  60. periods -- I think they're ugly]. In addition a boolean value WITHDAY
  61. is passed to indicate whether the day name is to be included [true] or
  62. omitted [false].
  63.     DASTRFIXED returns the date in an eight-place fixed length
  64. format. The separator character is specified as a constant and can
  65. be changed if desired. The function includes a boolean parameter WITHSPACE
  66. which determines whether leading zeroes are converted into spaces or
  67. left as numeric characters.
  68.  
  69. STRBYTE
  70. This routine is contained within DASTRFIX.LIB. It is passed a byte value
  71. and WITHSPACE and returns a two-place string equivalent. It is broken out
  72. in case it proves useful elsewhere in the program.
  73.  
  74. ----------
  75.  
  76. DATE.PAS has all of the date library routines plus PROMPT set up as an
  77. external module for separate compilation. Note, however, that it is
  78. necessary to change "progname" in the first line of the program to
  79. the name of the main program before it will properly compile. It also
  80. appears that the program names cannot exceed six characters [rather than
  81. just having only the first six be significant].
  82.  
  83. DATE.LIB can then be inserted in the main program to provide the relevant
  84. external declarations. DATE.LIB includes declarations for LENGTH and
  85. SETLENGTH.
  86.  
  87. Generally, the date routines require the following global type declarations:
  88.     TYPE    string255 = string 255;
  89.         byte = 0..255;
  90. There are two important constants used in MAKEDATE, RMAKEDATE and BRKDATE.
  91. YRBASE is the base year, which equals 10 in the package as written.
  92. YRSPAN is the total number of years which constitute the acceptable
  93. maximum range of entries. This number is dicated by maxint and thus cannot
  94. exceed 89.
  95.  
  96. This means that as written the routines can handle dates in the range
  97. 1910..1999. Since 1900 was not a leap year and there is no provision
  98. for dealing with that occurrence, 1901 [yrbase = 1] is the lowest possible
  99. base year. Since 2000 will be a leap year [wouldn't life be easier if
  100. the sun rose and set only 360 times a year and pi equalled three?] the
  101. routines could be extended beyond 1999, but the yr mod 100 statement
  102. within GETDATE and RGETDATE -- which permits dates to be entered
  103. 1-11-1980, if you're so moved -- would have to be modified to permit
  104. 00 to be higher than 99. I just didn't see any reason to clutter the
  105. program up with this business for a few more years.
  106.  
  107. As long as two integer date values share a common base year they are
  108. directly comparable. This is an argument for sticking with just one
  109. base year for all purposes. Thus the difference between any two date
  110. values is the number of days between them. More importantly, your
  111. programs should have a much easier time of scanning through data to
  112. determine whether the records fall within a designate range -- and
  113. are thus eligible for further processing -- when that range is specified
  114. as a number of days -- 10, 30, 90, etc.
  115.  
  116. It should also be noted that the string returned by DASTRFIXED with
  117. spaces passed as false can be used to create a CP/M file name if you have
  118. a series of data files which you want to keep broken down by date.
  119. Thus one set of files could be 01-11-80.ORD, 01-12-80.ORD, etc. if you
  120. wanted to keep, say, orders as a set of separate files.
  121.  
  122. Please note that DATEFUNC.LIB includes declarations for LENGTH and
  123. SETLENGTH, since they are used within DATE.PAS, so these should not
  124. be declared elsewhere in the main module.
  125.  
  126. The following global types are generally required:
  127.     TYPE    string255 = string 255;
  128.         byte = 0..255;
  129.  
  130. The datestring routines are all functions returning strings, which means
  131. that Pascal/Z ver 3.2 or later is required for proper compilation.
  132.  
  133. ----------
  134.  
  135. Scott Custin
  136. 2410 20th St NW #10
  137. Washington DC 20009
  138.  
  139.