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