CVTDAT (Convert Date)

CVTDAT Command syntax diagram

 

Purpose

The Convert Date (CVTDAT) command converts 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 desired 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.

Restriction: This command is valid only within a control language (CL) program.

 

Required Parameters

DATE

Specifies the constant or CL variable that contains the date to be converted. When a constant is specified that contains separator characters, it must be enclosed in apostrophes (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.

TOVAR

Specifies the name of the CL variable to receive 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. The following table explains the field sizes and minimum variable lengths for the various formats.

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 table to determine the required minimum length of the variable.

Table 1. 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

TO FMT	Field Size
	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)

 

Optional Parameters

FROMFMT

Specifies the current format of the date being converted.

*JOB: The format specified on the job attribute DATFMT is used.

*SYSVAL: The format specified by the system value QDATFMT is used.

*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.

TOFMT

Specifies the format to which the date is being converted.

*JOB: The format specified on the job attribute DATFMT is used.

*SYSVAL: The date 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.

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 is used as the 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 (,).

Examples for CVTDAT

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".

Error messages for CVTDAT

*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.