TAA Tools
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 Up to Top