The Check Date 3 tool provides a command to check dates. The major
intent of the tool is to call the processing program from a HLL
program and pass it an Externally Described Data Structure of
information and receive a message back in the Data Structure.
Unlike most date checking functions, the error messages describe the
specific error (such as Day 31 is not valid for April) rather than a
general description that the date is invalid. The error messages are
designed to be displayed to end users.
All date formats supported by CVTDAT are provided by CHKDAT3. The
function is useful whenever dates must be validated.
A typical command would be:
CHKDAT3 DATE(yyyymmdd) DATFMT(*YYMMDD)
A parameter controls whether a date separator exists. The default is
*DFT which means that either no date separator exists or to use the
implied value for the formats of *ISO, *USA, *EUR, or *JIS.
You may specify a value such as:
CHKDAT3 DATE(yyyy/mm/dd) DATFMT(*YYMMDD) DATSEP('/')
You may also check to see if the date is within a range of dates from
the current date or that it is in the current year.
CHKDAT3 escape messages you can monitor for
-------------------------------------------
TAA9891 Bad date conditions (the text explains the error)
(Only sent if the CHKDAT3 command is used)
If the function is called from a HLL program, the bad date conditions
will appear in the Externally Described Data Structure.
CPF9898 escape messages will be sent if the interface is violated.
regardless of whether the command is used or the processing program
is called directly. These are typically 'programmer problems' as
opposed to an end user problem of keying a bad date. For example, 1)
if the date format *USA is specified, you cannot request a date
separator of '-' or 2) if the value for DTLR is not one of the
allowed values, an escape message is sent. These escape messages are
sent from the RPG processing program (not the CL program which is the
command processing program).
Escape messages from based on functions will be re-sent.
Date restrictions
-----------------
The system has restrictions that can be read on CVTDAT relative to
the range of dates that can be converted. For 8 character dates, the
range is August 24, 1928 to May 9, 2071.
CHKDAT3 supports dates within the years of 1600 to 4000. Leap years
are properly handled.
Command parameters *CMD
------------------
DATE The date to be checked. The date must be entered in
the same format as described by a combination of the
DATFMT and DATSEP parameters. For example, if
DATFMT(*YYMD) and DATSEP('/') are used, the date
must appear as 'yyyy/mm/dd'.
DATFMT The format of the date to be checked. A combination
of DATFMT and DATSEP determine a valid entry. For
example, if DATFMT(*YYMD) and DATSEP('/') are used,
the date must appear as 'yyyy/mm/dd'.
The default is *JOB meaning to use the date format
as described by DSPJOB.
The following entries are the same as on CVTDAT and
have the same meaning. The date separators are
optional and may be specified (except where
described).
*JOB Uses the job date format as displayed by DSPJOB
*SYSVAL Uses the QDATFMT system value
*MDY mmddyy or mm/dd/yy
*DMY ddmmyy or dd/mm/yy
*YMD yymmdd or yy/mm/dd
*YYMD yyyymmdd or yyyy/mm/dd
*MDYY mmddyyyy or mm/dd/yyyy
*DMYY ddmmyyyy or dd/mm/yyyyy
*CYMD cyymmdd or cyy/mm/dd
*JUL yynnn or yy/nnn
*LONGJUL yyyynnn or yyyy/nnn
*ISO yyyy-mm-dd The '-' is a required separator
*USA mm/dd/yyyy The '/' is a required separator
*EUR dd.mm.yyyy The '.' is a required separator
*JIS yyyy-mm-dd The '-' is a required separator
DATSEP The date separator to be used. The default is *DFT
which means *NONE for typical date formats such as
*MDY and *YYMMDD or to check for the required
separator with the formats *ISO, *USA, *EUR, and
*JIS. You may also enter the required separator for
*ISO, *USA, *EUR, and *JIS.
The values that may be entered are:
*DFT Means either *NONE or use the rqd separator
*SYSVAL Use the system value QDATSEP
*JOB Use the date separator as displayed by DSPJOB
*OPTJOB May use the date sep as displayed by DSPJOB
The date may exist with or without the sep
*BLANK Use a blank separator
'/' Use a slash separator
'-' Use a dash separator
'.' Use a period separator
',' Use a comma separator
DAYLORNG The low range in days from the current date. The
default is *MAX meaning, no check occurs. You may
enter a minus, zero, or plus value in the range of
-80000 to 80000.
If the date should not be in the past, enter 0. You
may also enter a plus value such as 7 meaning the
date must be at least 7 days greater than the
current date.
DAYHIRNG The high range in days from the current date. The
default is *MAX meaning, no check occurs. You may
enter a minus, zero, or plus value in the range of
-80000 to 80000.
If the date should not be in the future, enter 0.
You may also enter a minus value such as -7 meaning
the date must be at least 7 days less than the
current date.
CURYEAR A *YES/*NO value for whether to ensure the year
entered is the same as the current year. *NO is the
default meaning that any year may be entered.
A *YES requires that the year of the date entered
match the current year.
SETLR How to set LR to end the RPG program. The major
processing of the function is done by an RPG
program. The default is *ON to end the RPG program
when the function is complete. This de-activates
the program. This is not a good performance choice
if you are going to iteratively use the function.
*OFF may be specified to cause the RPG program to
return, but the program remains active and may be
called again with better performance results. *OFF
should be used when you are going to iteratively use
the function.
*IMMED may be specified to cause the RPG program to
end without performing a date check. The program is
de-activated. The next time the program is called,
the program must be activated. *IMMED should be
used if you have been iteratively using the function
and now want to end it.
Using the function from a HLL program
-------------------------------------
The major intent of the tool is to call the processing program
(written in RPG) and communicate using an Externally Described Data
Structure. The Data Structure is shipped as a Physical file which
can be displayed with the command:
DSPFMT FILE(TAADAUBP)
The following describes the fields:
DTINP The Input date to be checked. The format of the
date must adhere to the combination specified for
the date format and date separator. A field length
of 10 is provided, the value must be left adjusted.
See earlier discussion.
DTFMT The Date format to be used. The values that may be
entered are the same as described for the DATFMT
keyword. The value must be specified and must must
be left adjusted.
DTSEP The Date separator to be used. The values that may
be entered are the same as described for the DATSEP
keyword. If the value is left blank, *DFT is
assumed. The value must be left adjusted.
DTLO The low range of dates to check. If the field is
blank, *MAX is assumed meaning there is no check.
A number may be entered (plus, minus, or zero) See
the discussion with the DAYLORNG command parameter.
The value must be right adjusted (use a preceding
minus if negative).
DTHI The high range of dates to check. If the field is
blank, *MAX is assumed meaning there is no check.
A number may be entered (plus, minus, or zero) See
the discussion with the DAYHIRNG command parameter.
The value must be right adjusted (use a preceding
minus if negative).
DTCURY Whether to check if the date is within the current
year. If the field is blank, *NO is assumed meaning
the year is not checked.
If *YES is entered, the year of the entered date
must match the current year.
DTLR The LR setting to be used. The values that may be
entered are the same as described for the SETLR
command parameter. If the value is left blank, *ON
is assumed. The value must be left adjusted.
DTERR The return value if an error exists. A one byte
field that will be blank on the return of a valid
date check.
The field will contain an 'X' if an error occurred.
You may either check DTERR or DTMSG to determine an
error exists.
DTMSG The return message if any. The field is defined as
78 bytes so it may fit on one line of a display.
The value will be blank if the date is valid.
If the date is not valid, the text describes the
specific error condition which is intended to be
displayed to the end user.
DTCYMD The return date in CYMD format. The value is only
returned if the date is valid. Note that this
return field is not available if the command
interface is used.
DTRSV A reserved field of 43 bytes.
RPG III Code
------------
The following code would be typical and is in a format that can be
copied directly into an RPG III program.
I* Externally described DS supplied by CHKDAT3
IDATDS E DSTAADAUBP
.
.
C MOVEL'*yyy' DTFMT Date format
C MOVELxxxxx DTINP Date value
C CALL 'TAADAUBR' CHKDAT3
C PARM DATDS Date DS
C DTERR IFEQ 'X' If error
C*
C* The error text is in DTMSG
C*
C ENDIF If error
RPG IV Code
-----------
The following code would be typical and is in a format
that can be copied directly into an RPG IV program.
D* Externally described DS supplied by CHKDAT3
D DATDS E DS EXTNAME(TAADAUBP)
.
.
C MOVEL '*yyy' DTFMT
C MOVEL xxxxx DTINP
C CALL 'TAADAUBR'
C PARM DATDS
C DTERR IFEQ 'X'
C*
C* The error text is in DTMSG
C*
C ENDIF
Restrictions
------------
The date range checked for 4 digit years is between 1600 and 4000.
Prerequisites
-------------
The following TAA Tools must be on your system:
ADDDAT2 Add date 2
CVTDAT2 Convert date 2
RTVSYSVAL3 Retrieve system value 3
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
CHKDAT3 *CMD TAADAUB QATTCMD
TAADAUBC *PGM CLP TAADAUBC QATTCL
TAADAUBC2 *PGM CLP TAADAUBC2 QATTCL
TAADAUBR *PGM RPG TAADAUBR QATTRPG
TAADAUBP *FILE PF TAADAUBP QATTDDS
|
