Per-Field Date and Time Formats

Supported RPG Features

Individual date and time fields can override the default *ISO format using the DATFMT and TIMFMT keywords. These are supported as both inline type parameters and standalone declaration keywords:

// Inline format (parameter on the type keyword)
DCL-S usaDate  DATE(*USA);
DCL-S hmsTime  TIME(*HMS);

// Standalone keyword (equivalent)
DCL-S usaDate  DATE DATFMT(*USA);
DCL-S hmsTime  TIME TIMFMT(*HMS);

Fixed-format D-spec declarations use the keyword in columns 44 - 80:

     D usaDate         S               D   DATFMT(*USA)
     D hmsTime         S               T   TIMFMT(*HMS)

The per-field format affects how the field is rendered by DSPLY and implicit character conversions. Supported date formats on a declaration: *ISO, *USA, *EUR, *JIS, *MDY, *DMY, *YMD, *JUL, *MDYY, *DMYY, *YYMD. The century formats (*CYMD, *CMDY, *CDMY) and *LONGJUL are conversion-only - they are valid in %CHAR(date : *CYMD), %DATE(value : *CYMD), and MOVE factor 1, but they are rejected on a field declaration, and *ISO is substituted. Supported time formats: *ISO, *HMS, *USA, *EUR, *JIS. When neither DATFMT/TIMFMT nor an inline format is specified, the default is *ISO.

Note on the free-format spelling. DATFMT and TIMFMT are keywords of the fixed-format D-spec. In a free-form DCL-S the format goes in the type instead - DCL-S d DATE(*USA). Both spellings are shown above because both appear in real source; only the type-parameter form is valid in **FREE.

Separator Suffix

A date or time format may carry a trailing separator that overrides the one the format normally uses - *ISO-, *DMY/, *YMD., *MDY&. It is accepted anywhere a format is: the type parameter, DATFMT/TIMFMT, %CHAR, %DATE, %TIME and the other conversions.

DCL-S d DATE INZ(D'1996-01-15');

%CHAR(d : *MDY)    // 01/15/96   the format's own separator
%CHAR(d : *MDY-)   // 01-15-96
%CHAR(d : *MDY.)   // 01.15.96
%CHAR(d : *MDY,)   // 01,15,96
%CHAR(d : *MDY&)   // 01 15 96   '&' means a blank
%CHAR(d : *MDY0)   // 011596     '0' means no separator at all

Which separators a format accepts depends on the width of its year:

Because a four-digit-year format admits only the separator it already uses, a suffix there never changes the image - *ISO- renders exactly as *ISO. A separator a format does not accept (*ISO/, say) is rejected at compile time.

The suffix applies on input as well as output, so it also says how a character date is punctuated when it is parsed:

d = %DATE('01-15-96' : *MDY-);   // 1996-01-15
d = %DATE('011596'   : *MDY0);   // 1996-01-15

A format given explicitly on %CHAR overrides whatever the field was declared with.