Convert Date (CVTDAT)

Where allowed to run: Compiled CL program or interpreted REXX (*BPGM *IPGM *BREXX *IREXX)
Threadsafe: Yes

The Convert Date (CVTDAT) command converts the format of a date value from one format to another, without changing its value. The command ignores any date separators used in the old format, but if separators are included in the converted result, a separator character can be specified on the command.

Only valid dates can be converted. If either the from-format or the to-format use only 2 digits to specify the year (for example, *MDY, *DMY, *YMD, or *JUL), valid dates are in the range of January 1, 1940, to December 31, 2039. Otherwise, valid dates are in the range of August 24, 1928, to May 9, 2071. If the year is specified with only 2 digits, years in the range of 40 to 99 are assumed to be 1940 to 1999; years in the range 00 to 39 are assumed to be 2000 to 2039. The command works in conjunction with the QLEAPADJ system value.

Restrictions: This command is valid only within a CL program or ILE CL procedure.

Top

Parameters

Keyword	Description	Choices	Notes
DATE	Date to be converted	Character value	Required, Positional 1
TOVAR	CL var for converted date	Character value	Required, Positional 2
FROMFMT	From date format	SYSVAL, MDY, DMY, YMD, JUL, JOB, MDYY, DMYY, YYMD, CYMD, ISO, USA, EUR, JIS, *LONGJUL	Optional, Positional 3
TOFMT	To date format	SYSVAL, MDY, DMY, YMD, JUL, JOB, MDYY, DMYY, YYMD, CYMD, ISO, USA, EUR, JIS, *LONGJUL	Optional, Positional 4
TOSEP	To date separator	SYSVAL, NONE, JOB, BLANK, '/', '-', '.', ','	Optional, Positional 5

Top

Date to be converted (DATE)

Specifies the constant or CL variable containing the date to be converted. When a constant is specified that contains separator characters, it must be enclosed in single quotation marks (the separator characters are ignored in the conversion). If separators are used in a constant, leading zeros in each part of the date can be omitted (3/3/88 or 03/03/88 are both valid). If a variable is specified, it must be long enough to contain the date type and its date separators, if used. The valid date separators are the slash (/), hyphen (-), period (.), and comma (,). A variable containing all blanks (X'40') is considered to have a date of length zero, and is not valid.

This is a required parameter.

Top

CL var for converted date (TOVAR)

Specifies the name of the CL variable that contains the converted date value.

For every format except Julian, the month and day subfields in the converted result are each 2 bytes in length, are right-justified, and (if necessary) a leading zero is used as a padding character to fill each 2-byte field.

For the Julian and long Julian formats, the day field is 3 bytes long and padded with leading zeros (if necessary). The year field is 2 bytes long for Julian and 4 bytes long for long Julian.

Use the following tables to determine the required minimum length of the variable.

Field Size and Minimum Variable Length

TO FMT                  TO SEP  Minimum Variable Length
----------------------  ------  -----------------------------
*JUL                    *NONE   5
*JUL                    Any     6
*MDY, *DMY, *YMD        *NONE   6
*MDY, *DMY, *YMD        Any     8
*MDYY, *DMYY, *YYMD     *NONE   8
*MDYY, *DMYY, *YYMD     Any     10
*CYMD                   *NONE   7
*CYMD                   Any     9
*LONGJUL                *NONE   7
*LONGJUL                Any     8
*ISO, *USA, *EUR, *JIS          10
*JOB                            Depends on job date format
*SYSVAL                         Depends on value of QDATFMT

                            Field Size
TO FMT                   Month  Day  Year
-----------------------  -----  ---  ----
*JUL                     N/A    3    2
*MDY, *DMY, *YMD         2      2    2
*MDYY, *DMYY, *YYMD      2      2    4
*ISO, *USA, *EUR, *JIS   2      2    4
*CYMD                    2      2    2 (+1 byte century field)

This is a required parameter.

Top

From date format (FROMFMT)

Specifies the current format of the date to be converted.

*JOB: The date has the format specified by the job attribute, DATFMT.
*SYSVAL: The date has the format specified by the system value, QDATFMT.
*MDY: The date has the month, day, year format, mmddyy.
*MDYY: The date has the month, day, year format, mmddyyyy.
*DMY: The date has the day, month, year format, ddmmyy.
*DMYY: The date has the day, month, year format, ddmmyyyy.
*YMD: The date has the year, month, day format, yymmdd.
*YYMD: The date has the year, month, day format, yyyymmdd.
*CYMD: The date has the century, year, month, day format, cyymmdd, where c is 0 for years 1928 through 1999 and is 1 for years 2000 through 2071.
*JUL: The date has the Julian format, yyddd.
*ISO: The date has the International Organization for Standardization (ISO) date format, yyyy-mm-dd.
*USA: The date has the United States date format, mm/dd/yyyy.
*EUR: The date has the European date format, dd.mm.yyyy.
*JIS: The date has the Japanese Industrial Standard date format, yyyy-mm-dd.
*LONGJUL: The date has the long Julian format, yyyyddd.

Top

To date format (TOFMT)

Specifies the format to which the date is to be converted.

*JOB: The date format is converted to the format specified by the job attribute, DATFMT.
*SYSVAL: The date format is converted to the format specified by the system value, QDATFMT.
*MDY: The date format is converted to the month, day, year format, mmddyy.
*MDYY: The date format is converted to the month, day, year format, mmddyyyy.
*DMY: The date format is converted to the day, month, year format, ddmmyy.
*DMYY: The date format is converted to the day, month, year format, ddmmyyyy.
*YMD: The date format is converted to the year, month, day format, yymmdd.
*YYMD: The date format is converted to the year, month, day format, yyyymmdd.
*CYMD: The date format is converted to the century, year, month, day format, cyymmdd, where c is 0 for years 1928 through 1999 and is 1 for years 2000 through 2071. If the year in the current format is only 2 digits, c will be set to 0 for years 40 through 99 and to 1 for years 00 through 39.
*JUL: The date format is converted to the Julian format, yyddd.
*ISO: The date format is converted to the International Organization for Standardization (ISO) date format, yyyy-mm-dd.
*USA: The date format is converted to the United States date format, mm/dd/yyyy.
*EUR: The date format is converted to the European date format, dd.mm.yyyy.
*JIS: The date format is converted to the Japanese Industrial Standard date format, yyyy-mm-dd.
*LONGJUL: The date has the long Julian format, yyyyddd.

Top

To date separator (TOSEP)

Specifies the type of date separators (if any) used in the converted date.

*JOB: The converted date has the separators specified by the job attribute, DATSEP.
*SYSVAL: The converted date has the separators specified by the system value, QDATSEP.
*NONE: No separator characters are contained in the converted date.
*BLANK: A blank space is used as the date separator in the converted date.
separator-character: Specify the character that is used as the date separator in the converted date. The valid separator characters are the slash (/), hyphen (-), period (.), and comma (,).

Top

Examples

Example 1: Converting to DMY Format

DCL   VAR(&DATE)  TYPE(*CHAR)  LEN(8)
:
CVTDAT   DATE('12-24-88')  TOVAR(&DATE)  TOFMT(*DMY)

This command converts the date 12-24-88, which is in the MDY format. Because the FROMFMT parameter was not specified, its default, *JOB, indicates that the job attribute DATFMT contains the MDY format. The date is converted to the DMY format, and the separator character specified in the job attribute DATSEP is inserted. If DATSEP contains a slash, the converted result is 24/12/88.

Example 2: Converting to Format Specified by Job Attribute

DCL   &PAYDAY  *CHAR  6
DCL   &NEWPDAY  *CHAR  6
:
CVTDAT   DATE(&PAYDAY)  TOVAR(&NEWPDAY)
         FROMFMT(*YMD)  TOSEP(*NONE)

This command converts the format of the date stored in &PAYDAY from year, month, day to the format specified by the job attribute DATFMT. If, for example, DATFMT contains the MDY format, the format of the converted date is month, day, and year. The converted date is stored in the variable &NEWPDAY. Because &NEWPDAY was declared as a 6-character variable, TOSEP(*NONE) is required; the converted result cannot include separator characters.

Example 3: Converting to CYMD format

DCL   &NEWDAY1  *CHAR  7
DCL   &NEWDAY2  *CHAR  7
:
CVTDAT   DATE('01/24/1939')  TOVAR(&NEWDAY1)
         FROMFMT(*MDYY)  TOFMT(*CYMD)  TOSEP(*NONE)
CVTDAT   DATE('01/24/39')  TOVAR(&NEWDAY2)
         FROMFMT(*MDY)  TOFMT(*CYMD)  TOSEP(*NONE)

The first CVTDAT command converts the date specified on the DATE parameter from the month, day, 4-digit year format to the century, year, month, day format. Because the year was specified with 4 digits and the first 2 digits are "19", the century digit is set to "0", so the value of "NEWDAY1 is "0390124".

The second CVTDAT command converts the date specified on the DATE parameter from the month, day, year format to the century, year, month, day format. Because the year was specified with only 2 digits and the year is less than 40, the century digit is set to "1", so the value of "NEWDAY2 is "1390124".

Top

Error messages

*ESCAPE Messages

CPF0550: Date too short for specified format.
CPF0551: Separators in date are not valid.
CPF0552: Date contains misplaced or extra separators.
CPF0553: Date contains too many or too few numeric characters.
CPF0554: Variable specified too short for converted date format.
CPF0555: Date not in specified format or date not valid.
CPF0556: Date contains two or more kinds of separators.
CPF0557: Date outside allowed range.

Top