IBM Extension

SUBTRACT-DURATION

The SUBTRACT-DURATION function subtracts a duration from a date, time, or timestamp item, and returns the modified item.

The function type is date-time.

Start of change The length of the return value depends on the length of the date, time, or timestamp item specified in argument-1. The returned value will be truncated to the length of argument-1. End of change

If a duration is subtracted from a date item, the date returned must fall within a certain range: If a duration is subtracted from a 2-digit date item, the range is the same as for a 4-digit year, but the year in the value returned is truncated to 2 digits.
Read syntax diagramSkip visual syntax diagram
Format

>>-FUNCTION SUBTRACT-DURATION----------------------------------->

                  .------------------------.      
                  V                        |      
>--(--argument-1----argument-2--argument-3-+--)----------------><

argument-1
Must be a date, time, or timestamp item.

Argument-1 is the value from which a duration is subtracted. The duration is specified in argument-2 and argument-3.

argument-2
Argument-2 is a keyword that represents a duration. The valid durations are:
  • YEARS
  • MONTHS
  • DAYS
  • HOURS
  • MINUTES
  • SECONDS
  • MICROSECONDS
  • Start of change PICOSECONDS End of change
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 subtracted from a date or timestamp item.
  2. HOURS, MINUTES, SECONDS, and MICROSECONDS can only be subtracted from a time or timestamp item.
  3. Start of change PICOSECONDS can only be subtracted from a timestamp item. End of change
argument-3
Must be an integer arithmetic expression. Argument-3 is the number of units of the duration, as specified in argument-2, that are to be subtracted from argument-1.

Argument-2 and argument-3 can be repeated. There should be no duplicate argument-2 in one intrinsic function.

Argument-3 can be a negative integer, but the function only takes its absolute value. If argument-3 is longer than 9 digits, it is truncated.

If a duration is subtracted from a date, and the result is invalid, the date is adjusted. For example, if a duration of 1 month is subtracted from the date May 31, 1997, the result would be the invalid date April 31, 1997. This date would be adjusted to the valid date April 30, 1997.

Related Information
End of IBM Extension