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.

Format

Read syntax diagramSkip visual syntax diagramFUNCTION 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 results in an alphanumeric return value.

The valid durations and their equivalent conversion specifications are:

  • YEARS ('@Y')
  • MONTHS ('%m')
  • DAYS ('%d')
  • HOURS ('%H')
  • MINUTES ('%M')
  • SECONDS ('%S')
  • MICROSECONDS ('@Sm')
  • PICOSECONDS ('@Sp')

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 in argument-2 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 @ (%p, in this case, becomes @p and @p is the non-locale-based equivalent of %p).

  4. PICOSECONDS can only be extracted from a timestamp item.

Examples


COMPUTE integer-1 = FUNCTION EXTRACT-DATE-TIME (date-3 MONTHS).
COMPUTE integer-1 = FUNCTION EXTRACT-DATE-TIME (date-3 '%m').
MOVE FUNCTION EXTRACT-DATE-TIME (date-2 '%m/%d') to alphanum-1.