RTVDAT       RETRIEVE DATE IN VARIOUS FORMATS       TAADATD

 The  RTVDAT command  allows  you  to input  a  date  to a  command  and
 receive back  the same date in  various formats.  These  formats can be
 of value in comparisons, report writing, messages, etc.

 RTVDAT  is ideal  for CL programs  because the  command provides return
 variables.    If  you   are  only  interested  in  the   DAYOFWEEK  and
 WEEKOFYEAR, use RTVDAT4 for better performance.

 The RTVDAT2  TAA Tool provides a  similar function, but  is designed to
 be  accessed  directly  from  a  HLL  program.    RTVDAT2  has  a  call
 interface  and  returns  a  data  structure  which  can  be  externally
 described in the program.

 The RTVDAT  command provides several parameters.   For example,  if you
 input  the date 010609 (January  06, 2009) you can  specify one or more
 parameters as return  variables to receive  the following formats  (see
 the later discussion of ISO dates).

       Format                   Keyword       Length     Value
       ------                   -------       ------     -----

       Day of week              DAYNAME         9        Tuesday
       Month                    MTHNAME         9        January
       Complete date            COMPDATE       20        January 6, 2009
       Abbreviated date         ABRVDATE       12        Jan 6, 2006
       3 character day upper    DAY3U           3        TUE
       3 character day lower    DAY3L           3        Tue
       3 character month upper  MTH3U           3        JAN
       3 character month lower  MTH3L           3        Jan
       Day of the week          DAYOFWEEK       1        3
       Day of the year          DAYOFYEAR       3        006
       Week of the month        WEEKOFMTH       1        1
       Week of the year         WEEKOFYEAR      2        02
       YYMMDD format            YYMMDD          6        090106
       CYYMMDD format           CYYMMDD         7        1090106
       CCYYMMDD format          CCYYMMDD        8        20090106
       Full year                FULLYEAR        4        2009
       Century                  CENT            1        0
       Old version of COMPDATE  FULLDATE       17        January 6, 2009
       ISO Day                  ISODAY          1        2
       ISO Week                 ISOWEEK         2        02
       ISO Date 1               ISODATE1        8        2009-02
       ISO Date 2               ISODATE2        7        2009-W02
       ISO Date 3               ISODATE3       10        2009-W02-2
       ISO Date 4               ISODATE4        8        2009W022

 A typical command would be entered as:

       RTVDAT     DAY3U(&DAYNAME)

 This would  return the  day of  the week  as a 3  character upper  case
 value.

 The DATE  keyword is input  to the command  and defaults to  the system
 date.   If  a specific date  is entered, job  date format  must be used
 (e.g.  MMDDYY).   Because return variables exist, the command  can only
 be used in a CL program.

 All parameters  are defined as  character variables.  When  the command
 is  prompted for, the number in parenthesis  next to the keyword prompt
 describes the length of the variable  to be defined in the CL  program.

 The WEEKOFMTH parameter  considers any day ending  in 7 or less  as the
 first  week of the month,  14 or less  as the second week  of the month
 etc.  The value returned will be 1 to 5.

 The WEEKOFYEAR  parameter counts  1  for the  first  week of  the  year
 regardless of what day of the week the year starts on.

 A year of 40 - 99  is considered to be the 20th century.   A year of 00
 - 39  is considered to  be the 21st  century.  This  is consistent with
 the  system  definition.   If a  different century  is needed,  use the
 CENTURY parameter.

 The FULLDATE  return value  is the old  form of  COMPDATE.   It is  not
 large  enough  to  handle  the  largest  date.    It  is  retained  for
 compatibility purposes, but COMPDATE should be used.

 ISO Dates
 ---------

 The  International Standards Organization  (ISO) defines  a date format
 that includes a 'week  of year' and optionally  a day within the  week.
 Days in  the week  begin with  Monday =  1 (Sunday  = 7)  which differs
 from the DAYOFWEEK return variable where Sunday = 1 (Saturday = 7).

 The  'ISO week' definition  requires that the  week include at  least a
 Thursday at  the beginning  of the  year.   Consequently, if  the  year
 begins with  Friday,  Saturday, or  Sunday, those  days are  considered
 part of the  last week of the preceding year.   All years have at least
 52 weeks and some years have 53 weeks.

 Translation
 -----------

 No translation is required for English day and month names.

 Translation  of the day and month names  is provided by creating a data
 area with  the special  command CRTRTVDAT2  and editing  the data  area
 with  the EDTDTAARA2 TAA  Tool.   The same  data area  is used  for the
 RTVDAT2 TAA Tool.  See the discussion with RTVDAT2.

 Command parameters                                    *CMD
 ------------------

    DATE          The  date to be retrieved.   The special value *SYSDAT
                  may be used to retrieve the current date.

                  If a  specific date  is  entered, it  must be  in  job
                  format.

    CENTURY       The  century of  the  date.   **  is  the default  and
                  means  use  the  century  based  on  the  date.    For
                  example, if  the date  101506 is  entered (job  format
                  of *MDY), a century of 2006 is assumed.

                  Unless a  century is described,  RTVDAT uses  the same
                  assumptions  as the  system (19  is assumed  for years
                  40-99   and  00  is  assumed  for  years  00-39).    A
                  different century  may be  entered  between 16  (1600)
                  and 40 (4000).

                  Note  that if  a value  is  entered it  should be  the
                  first  two digits  of the year.   For  example, if the
                  year 2072  is  needed, enter  '20'  and not  the  21st
                  century.

 The  other  parameters  are  all return  variables  and  are  described
 previously.

 Restrictions
 ------------

   **   The RTVDAT command can only be used in a CL program.

   **   If a  DATE value other than  *SYSDAT is used, it  must be in job
        format.

   **   Only dates  between January  1, 1600  and Dec  31, 4000  may  be
        used.

 Prerequisites
 -------------

 The following TAA Tools must be on your system:

        CVTDAT2       Convert date 2
        RTVNEWYEAR    Retrieve new year
        SNDESCMSG     Send escape message

 Implementation
 --------------

 None, the tool is ready to use.

 Objects used by the tool
 ------------------------

    Object        Type       Attribute      Src member     Src file
    ------        -----      ---------      ----------     -----------

    RTVDAT        *CMD                      TAADATD        QATTCMD
    TAADATDC      *PGM          CLP         TAADATDC       QATTCL

Added to TAA Productivity Tools April 1, 1995


Home Page

Last modified on March 10, 2014 © 1995, 2014 - TAA Tools, Inc.