IBM Extension

EXTRACT-DATE-TIME

The EXTRACT-DATE-TIME function returns part of a date, time, or timestamp item.

The function type is integer or alphanumeric. If argument-2 is a keyword (such as MONTHS or DAYS), or consists of only numeric specifiers, an integer is returned. Otherwise, an alphanumeric data item is returned.

The length of the result depends on the values extracted from the date-time item.
Read syntax diagramSkip visual syntax diagram
Format

>>-FUNCTION EXTRACT-DATE-TIME--(--argument-1--argument-2--)----><

argument-1
Must be a date, time, or timestamp item.
argument-2
Specifies the values to be returned by the EXTRACT-DATE-TIME function.

Argument-2 is a keyword that represents a duration or a non-numeric literal that contains one or more separators and conversion specifications.

If the non-numeric literal contains only numeric conversion specifiers, the value returned by the EXTRACT-DATE-TIME function is an integer. A non-numeric literal containing separators or alphanumeric conversion specifiers will result in an alphanumeric return value.

If argument-2 is a keyword, an integer is returned.

The valid durations and their equivalent conversion specifications are:
  • YEARS ('@Y')
  • MONTHS ('%m')
  • DAYS ('%d')
  • HOURS ('%H')
  • MINUTES ('%M')
  • SECONDS ('%S')
  • MICROSECONDS ('@Sm').
  • Start of change PICOSECONDS ('@Sp'). End of change

For a list of other valid conversion specifications see Table 1 in the description of the FORMAT clause of the SPECIAL-NAMES paragraph.

The duration keyword or conversion specifier used must be consistent with argument-1. For example, the duration keywords must obey the following rules:
  1. YEARS, MONTHS, and DAYS can only be extracted from a date or timestamp item.
  2. HOURS, MINUTES, SECONDS, and MICROSECONDS can only be extracted from a time or timestamp item.
  3. If argument-1 is a locale-based data item, and argument-2 contains locale-based conversion specifiers (such as %p), the locale-based conversion specifier (%p, in this case) uses the locale of argument-1.

    If argument-1 is not a locale-based data item, then the locale-based conversion specifier (%p, in this case) is treated as a non-locale-based conversion specifier and the % is replaced with an @. Using our example, this means that %p would become @p, where @p is the non-locale-based equivalent of %p.

  4. Start of change PICOSECONDS can only be extracted from a timestamp item. End of change
Related Information
End of IBM Extension