IBM Extension

FORMAT Clause

The FORMAT clause is used to specify a default format for a DATA DIVISION date or time item. The format clause can also specify the default date or time format for an intrinsic function.

FORMAT Clause - Format

Read syntax diagramSkip visual syntax diagramFORMATOF DATETIMEISliteral-8SIZE Phrase 1LOCALE Phrase 1SIZEISinteger-4LOCALEISmnemonic-name-4
SIZE Phrase 1
Read syntax diagramSkip visual syntax diagramSIZEISinteger-3
LOCALE Phrase 1
Read syntax diagramSkip visual syntax diagramLOCALE ISmnemonic-name-3
literal-8
Specifies the default format of a date or time item. Literal-8 must be a nonnumeric literal at least 2 characters in length. Literal-8 must contain one or more conversion specifiers and zero or more separators. For more information about the effects of literal-8 on the LOCALE phrase, refer to LOCALE Phrase. For a list of the conversion specifiers that can be used in literal-8, refer to Table 1.
The following rules apply:
  • When no LOCALE phrase is specified with literal-8, the conversion specifications are replaced with values based on the COBOL locale. For more information about the COBOL locale, refer to IBM Rational Development Studio for i: ILE COBOL Programmer's Guide.
  • For a date item, literal-8 must contain a conversion specifier that will result in the day of the year. If literal-8 contains a year and month conversion specification, but no day conversion specification, the first day of the month is assumed. For a list of IBM® i date formats and their literal-8 equivalents, refer to Table 1.
  • If no FORMAT clause is specified for a date item, the default date item format is ISO.
  • If literal-8 is not specified, the LOCALE phrase must be specified.
  • For a time item, literal-8 must contain an hour and minute conversion specification. If no seconds (or milliseconds) are specified, a value of 0 is assumed. For a list of IBM i time formats and their literal-8 equivalents, refer to Table 2.
  • If no FORMAT clause is specified for a time item, the default time item format is ISO.

Table 1 lists the conversion specifiers that can be used in literal-8.

Table 1. Conversion Specifiers that Can Be Used in Literal-8
Specifier Description Length Allowed For
@C Replaced by the century as an integer [0,9] (0⁴ 20th century) 1 bytes D
%d Replaced by the day of month as an integer [01,31] 2 bytes D
%D Same as %m/%d/%y 8 bytes D
%H Replaced by the hour (24-hour clock) as an integer [00,23] 2 bytes T
%I Replaced by the hour (12-hour clock) as an integer [01,12] 2 bytes T
%j Replaced by the day of the year as an integer [001,366] 3 bytes D
%m Replaced by the month as an integer [01,12] 2 bytes D
%M Replaced by the minute as an integer [00,59] 2 bytes T
%p Replaced by the locale's equivalent of either a.m. or p.m. locale T
@p AM and PM can be any mix of upper and lower case 2 bytes T
%r Replaced by the time in a.m. and p.m. notation; in the POSIX locale this is equivalent to %I:%M:%S %p locale, at least 8 bytes T
%R Replaced by the time in 24 hour notation [%H:%M] 5 bytes T
%S Replaced by the second as an integer [00,61] 2 bytes T
@Sh Replaced by the hundredths of a second as an integer [00,99] 2 bytes T
@Sm Replaced by the millionths of a second as an integer [000000,999999] 6 bytes T
@So Replaced by the thousandths of a second as an integer [000,999] 3 bytes T
@St Replaced by the tenths of a second as an integer [0,9] 1 bytes T
%y Replaced by the year without century as an integer [00,99] 2 bytes D
%Y Replaced by the year with century as an integer usually 4 bytes D
@Y Replaced by the year with century as an integer 4 bytes D
%% Replaced by a % 1 byte D, T
@@ Replaced by a @ 1 byte D, T
Table 5 notes:
  1. Conversion specifiers are case-sensitive.
  2. The Allowed For column symbols have the following meaning:
    • D - DATE item
    • T - TIME item
  3. The Length column is based on the default COBOL locale, which is an EBCDIC single-byte encoding scheme (CCSID 37).
  4. By default, a value of zero represents the twentieth century (1900 to 1999). This value is based on the base century specified in the DATTIM PROCESS statement option.
Related Information:
End of IBM Extension