home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / dsdate.zip / DSDATE.DOC < prev    next >
Text File  |  1995-09-01  |  10KB  |  243 lines
  1.  
  2.  
  3.   *************************  INTRODUCTION  *********************************
  4.  
  5.     dsDate was written by a Rexx/2 programmer for use in any Rexx-based
  6.     OS/2 application.  Initially, it was written for use as a subproc in
  7.     VisPro Rexx applications as a means of creating and validating date
  8.     strings entered by VisPro application users.
  9.  
  10.     Note:  VisPro Rexx is a licensed trademark of Hockware, Inc.,
  11.            P.O. Box 336, Cary, NC.
  12.  
  13.     This function set is PUBLIC DOMAIN.  Neither payment nor licensing is
  14.     required.  All users may feel free to change or enhance this
  15.     function set as desired.  If enhancements are made, I would appreciate
  16.     being contacted.  I'm always looking for good utility functions.
  17.  
  18.     Please forward any comments to me as follows:
  19.  
  20.             Dan Statkus, Laurel, Maryland
  21.             CIS 74721,1603  / Internet 74721.1603@compuserve.com
  22.  
  23.  
  24.   **************************  DESCRIPTION  **********************************
  25.  
  26.   dsDate provides enhancements to all switches of the DATE() function
  27.   provided by REXX/2, and also provides additional date switches.
  28.  
  29.   The dsDate function emulates ALL of the switches of the native REXX/2
  30.   DATE() function.  dsDate() solves the following anamolies of the REXX/2
  31.   native function:
  32.  
  33.         1)  DATE() only returns data concerning the current system date.
  34.             dsDate() allows you to specify ANY date and obtain the same
  35.             information using the same optional parameters used by DATE().
  36.             If you do not provide a date, then (by default) dsDate() will
  37.             act on the current system date.  See examples.
  38.  
  39.         2)  DATE() will generate a runtime error if you attempt to use either
  40.             the 'C' or 'J' switches in native OS/2.  Personal Rexx must be
  41.             available in order for these switches to function.  dsDate()
  42.             solves this problem.  You may use either switch at will.
  43.  
  44.   Other switches provided by dsDate() and not native to REXX/2 are:
  45.  
  46.         1)  dsDate()'s 'T' switch will return a full text string representation
  47.             of the supplied date; eg. "January 15, 1979".
  48.  
  49.         2)  DATE() has no native support to validate a date.  dsDate()
  50.             provides the 'V' option to validate a date.  This is very useful
  51.             with data entry applications to ensure data integrity of dates
  52.             entered by application users.
  53.  
  54.         3)  DATE() has no abilities to increment or compare dates.  dsDate()
  55.             provides the 'I' (increment) option to add/subtract to/from a
  56.             desired date.  eg. Obtain the date of the day 15 days ago or
  57.             project a date 15 days in the future.
  58.  
  59.         4)  dsDate() provides the 'P'(Passed) switch to calculate the number of days
  60.             between any two provided dates.  eg. Return the # of days passed
  61.             between DateParam1 and Dateparam2.
  62.  
  63.         5)  dsDate() provides the 'Q' (Quarter) switch to calculate the quarter
  64.             of the calendar year for the given date.  Returns integer (1-4).
  65.  
  66.         6)  dsDate() can return a Gregorian date in US format from a Julian
  67.             date using the 'G' (Gregorian) switch.  This is the counterpart
  68.             to the 'J' switch of both DATE() and dsDate().
  69.  
  70.         7)  dsDate() can return an integer representing the week day of any
  71.             given date using its 'Y' (daY) switch.  Unlike the 'W' switch
  72.             which returns a text label, the 'Y' switch will produce a
  73.             numeric suitable for calculations.
  74.  
  75.  
  76.   **********************  DEVELOPMENT NOTES  **************************
  77.  
  78.         Great care was taken to ensure that all procedures are closed
  79.         so as to hide all internal tokens from applications using this
  80.         function set.  Parameter passing is used whenever possible.  All
  81.         sub-functions used by dsDate were named with a "!" as the last
  82.         digit of the function name to ensure that they won't trample
  83.         other, similarly named, procedures.
  84.  
  85.         There is only one globally scoped token used in the entire series
  86.         of procedure calls: the "dsd!." stem.  I doubt that other programmers
  87.         will use a stem of this name.  If so, then either this source
  88.         must be changed, or the calling program must be changed to
  89.         eliminate this trampling.
  90.  
  91.         If there is a naming conflict, a simple search and replace for the
  92.         dsd!. stem will rectify it.
  93.  
  94.  
  95.   ****************************  SYNTAX  *******************************
  96.  
  97.   The syntax of the dsDate function is:  dsDate(switch,parm1,parm2)
  98.  
  99.   When specifying dates in the parms, the date can be supplied as
  100.   mm/dd/yy, or mm/dd/yyyy. This allows for dates not in the 1900's.
  101.   Any date of the form mm/dd/yy is assumed in the 1900's
  102.  
  103.   For switches requesting a date to be returned in the form mm/dd/yy,
  104.   dd/mm/yy, or yy/mm/dd, the yy portion will be 2 digits if the year is
  105.   in the 1900's or 4 digits if not in the 1900's.
  106.  
  107.  
  108.   Switches:
  109.  
  110.     NULL i.e. dsDate() or dsDate(,parm1) converts the date
  111.        supplied in parm1 to a text string representation of the
  112.        given date in the same format as DATE().
  113.  
  114.        parm1 = a Date in the format mm/dd/yy or mm/dd/yyyy
  115.                if null, parm1 will be current date.
  116.        parm2 = not used
  117.  
  118.        e.g.  dsDate(,'10/06/85')   returns ===> 06 Oct 1985
  119.              dsDate(,'10/06/2000') returns ===> 06 Oct 2000
  120.  
  121.     B (Basedate) Emulates the B switch of DATE().
  122.  
  123.        e.g.  dsDate(B,'08/31/95')  returns ===> 728535
  124.  
  125.     C  (Century) Emulates C switch of DATE() without need for Personal Rexx.
  126.  
  127.        e.g.  dsDate(c,'01/10/85')   returns ===> 31056
  128.              dsDate(c,'01/10/1800') returns ===> 10
  129.  
  130.     D  (Days) Emulates D switch of DATE().
  131.  
  132.        e.g.  dsDate(d,'01/10/85')   returns ===> 10
  133.              dsDate(d,'07/10/1800') returns ===> 191
  134.  
  135.     E  (European) Emulates E switch of DATE().
  136.  
  137.        e.g.  dsDate(e,'01/23/85')   returns ===> 23/01/85
  138.              dsDate(e,'01/23/1800') returns ===> 23/01/1800
  139.  
  140.     G  (Gregorian) Converts Julian to GREGORIAN date, and returns the
  141.         GREGORIAN date in US format (mm/dd/yy).
  142.  
  143.        parm1 = null (Julian for current date) or yyddd
  144.                yy assumed in 1900's
  145.        parm2 = not used
  146.        e.g.  dsDate(G,85205)   returns ===>  07/24/85
  147.  
  148.     I  (Increment) Returns the date +/- x days from given date.
  149.         Base date supplied in parm1, number of days (+/-) supplied in parm2.
  150.  
  151.        parm1 = null (current date) or mm/dd/yy or mm/dd/yyyy
  152.        parm2 = null, 0, negative integer or positive integer
  153.  
  154.        e.g.  dsDate(I,,1)            returns ===>  next day's date
  155.              dsDate(I,'07/23/85',10) returns ===>  08/02/85
  156.              dsDate(I,'07/23/85',-5) returns ===>  07/18/85
  157.  
  158.     J  (Julian) Emulates the J switch of DATE() without needing Personal
  159.         Rexx.
  160.  
  161.        e.g.  dsDate(j,'07/23/85')   returns ===> 85204
  162.              dsDate(j,'07/23/1885') returns ===> 85204
  163.  
  164.     L  (Local) Emulates the L switch of DATE().
  165.  
  166.         e.g. dsDate(l,'08/08/95')   returns ===> 08 Aug 1995
  167.  
  168.     M  (Month) Emulates M switch of DATE().
  169.  
  170.        e.g.  dsDate(m,'01/23/85')   returns ===> January
  171.              dsDate(m,'07/23/1885') returns ===> July
  172.  
  173.     N  (Normal) Emulates the N switch of DATE().
  174.  
  175.         e.g. dsDate(n,'08/08/95')   returns ===> 08 Aug 1995
  176.  
  177.     O  (Ordered) Emulates the O switch of DATE().
  178.  
  179.        e.g.  dsDate(o,'07/23/85')   returns ===> 85/07/23
  180.              dsDate(o,'07/23/1885') returns ===> 1885/07/23
  181.  
  182.     P  (Passed) Returns the number of days passed between one date and
  183.         the other. The number of days from one day to the next is
  184.         considered one (1).
  185.  
  186.         parm1 = null(current date) or mm/dd/yy or mm/dd/yyyy
  187.         parm2 = null(current date) or mm/dd/yy or mm/dd/yyyy
  188.  
  189.         e.g. dsDate(P,,'01/01/2000')             returns ===> 5288 (possibly)
  190.              dsDate(P,'01/01/1900','01/01/2000') returns ===> 36524
  191.              dsDate(P,'01/01/2000','01/01/1900') returns ===> 36524
  192.  
  193.     Q  (Quarter) Returns the quarter number (1-4) of the calendar year for
  194.         the date supplied as parameter 1.
  195.  
  196.         parm1 = null(current date) or mm/dd/yy or mm/dd/yyyy
  197.         parm2 not used
  198.  
  199.        e.g. dsDate(Q)       returns ===> 1 (assume 01/01/94-03/31/94)
  200.             dsDate(Q, '07/23/95') returns ===> 3
  201.  
  202.     S  (Sorted) Emulates the S switch of DATE().
  203.  
  204.        e.g.  dsDate(s,'07/23/85')   returns ===> 19850723
  205.              dsDate(s,'07/23/1885') returns ===> 18850723
  206.  
  207.     T  (Text) Returns a given mm/dd/yy date as Text string.
  208.  
  209.         e.g. dsDate(t,'07/23/85')   returns ===> July 23, 1985
  210.              dsDate(t,'07/23/1885)  returns ===> July 23, 1885
  211.  
  212.     U  (USA) Emulates the U switch of DATE().
  213.  
  214.        e.g.  dsDate(u,'07/23/85')   returns ===> 07/23/85
  215.              dsDate(u,'07/23/1985') returns ===> 07/23/85
  216.              dsDate(u,'07/23/1885') returns ===> 07/23/1885
  217.  
  218.     V  (Valid) Validates the given date.  Returns '1' if date supplied
  219.         in parm1 is valid, 0 if parm1 date is invalid.
  220.  
  221.        parm1 = null (current date) or mm/dd/yy or mm/dd/yyyy
  222.        parm2 = not used
  223.  
  224.        e.g.  dsDate(V,'a1/01/2000') returns ===> 0
  225.              dsDate(V,'01/33/1985') returns ===> 0 (33 not valid)
  226.              dsDate(V,'07/04/1776') returns ===> 1
  227.              dsDate(V,'02/29/85')   returns ===> 0 (not leap year)
  228.              dsDate(V,'02/29/84')   returns ===> 1
  229.  
  230.     W  (WEEKDAY) Emulates the W switch of DATE().
  231.  
  232.        e.g.  dsDate(w,'01/01/2000') returns ===> Saturday
  233.              dsDate(w,'07/04/1776') returns ===> Thursday
  234.  
  235.     Y  (daY) Returns the integer number (1-7) of the day of the week for
  236.         for date specified in parm1.  Sunday = 1 ..... Saturday = 7
  237.  
  238.        parm1 = null (current date) or mm/dd/yy or mm/dd/yyyy
  239.        parm2 = not used
  240.  
  241.        e.g.  dsDate(Y,'01/01/2000') returns ===> 7  (Saturday)
  242.              dsDate(Y,'07/04/1776') returns ===> 5  (Thursday)
  243.