The Retrieve Relative Month command will calculate and return three
date values based on the date given in the DATE parameter, offset by
the number of months in the RELMTH parameter.  It will return a date
in the target month equivalent to the original date, its beginning of
the month date, and its end of the month date.  If the target month
has fewer days than the source month, then the TODATE will be
adjusted to the end of month date.  If so, the number of days it was
adjusted will be returned in the ADJUST parameter.

An input is valid only if it would produce a date within the range of
1929 to 2070, inclusive.

RTVRELMTH handles the conversion to the next month, next year, leap
year, etc.  The command can only be used in a CL program.

Here is a sample CL program using the command:

     pgm
       dcl &fromdate *char 10
       dcl &bomdate *char 10
       dcl &eomdate *char 10
       dcl &todate *char 10
       dcl &adjust *dec (5 0)
       dcl &adjustc *char 5
       chgvar &fromdate '2016-10-31'
       rtvrelmth date(&fromdate) relmth(-4) +
         todate(&todate) bomdate(&bomdate) eomdate(&eomdate) +
         adjust(&adjust) +
         fromfmt(*iso) +
         tofmt(*iso)
       chgvar &adjustc &adjust
       sndpgmmsg ('From date:               ' || &fromdate)
       sndpgmmsg ('To date:                 ' || &todate)
       sndpgmmsg ('Beginning of month date: ' || &bomdate)
       sndpgmmsg ('End of month date:       ' || &eomdate)
       sndpgmmsg ('Adjustment:              ' || &adjustc)
     endpgm

When run this program will produce the following output:

     From date:               2016-10-31
     To date:                 2016-06-30
     Beginning of month date: 2016-06-01
     End of month date:       2016-06-30
     Adjustment:              -0001

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

   DATE          This is the date from which the other dates are
                 calculated.

   RELMTH        This is the number of months by which to adjust the
                 current date.  It may be negative for a month in the
                 past, zero for the current month, or positive for a
                 month in the future.

   TODATE        This is the returned calculated date.  For example,
                 if the DATE is *ISO '2000-12-15' and RELMTH is -3
                 then this would return '2000-09-15'.

                 This may be adjusted if the calculated date was past
                 the end of the month.  For example, if the DATE is
                 '2000-12-31' and RELMTH is 2 then this would return
                 '2001-02-28' and ADJUST would be -3.

   BOMDATE       This is the returned beginning of month date.  For
                 example, if the DATE is *ISO '2000-12-15' and RELMTH
                 is -3 then this would return '2000-09-01'.

   EOMDATE       This is the returned end of month date.  For
                 example, if the DATE is *ISO '2000-12-15' and RELMTH
                 is -3 then this would return '2000-09-30'.

   ADJUST        This is the TODATE adjustment.  This will be always
                 be 0 or negative.  If negative, then the TODATE had
                 to be adjusted by this many days to fit into the
                 correct month.  For example, if the DATE is
                 '2000-12-31' and RELMTH is 2 then this would return
                 '2001-02-28' and ADJUST would be -3.

   FROMFMT       The format of the DATE value.  The default is *JOB.
                 The other values that may be specified are the same
                 as on the system CVTDAT command including *SYSVAL,
                 *MDY, *DMY, *YMD, *JUL, *LONGJUL, *MDYY, *DMYY,
                 *YYMD, *CYMD, *ISO, *USA, *EUR, and *JIS.

   TOFMT         The format of the TODATE value to be returned.  The
                 default is *JOB.  The other values that may be
                 specified are the same as on the system CVTDAT
                 command including *SYSVAL, *MDY, *DMY, *YMD, *JUL,
                 *LONGJUL, *MDYY, *DMYY, *YYMD, *CYMD, *ISO, *USA,
                 *EUR, and *JIS.

   TOSEP         Whether separator characters should be used in the
                 TODATE return date.  The default is *JOB meaning the
                 value seen on DSPJOB.  The other values that may be
                 specified are the same as on the system CVTDAT
                 command including *SYSVAL, *NONE, *BLANK, or the
                 values '/' ',' '.' and '-'.  If the TOFMT is *ISO,
                 *USA, *EUR, or *JIS, the TOSEP value is ignored as
                 the TOVAR value will always contain the standard
                 separators.


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

  **   See previous comments about valid date ranges.

  **   Only valid dates may be entered.

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

The following TAA Tools must be on your system:

         CVTDAT2       Convert date 2
         SNDESCMSG     Send escape message
         RTVEOMDAT     Retrieve end of month date

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

None, the tool is ready to use:

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

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

   RTVRELMTH     *CMD                      TAARMTH        QATTCMD
   TAADATAC      *PGM          CLLE        TAARMTHC       QATTCL