ADD-DURATION

The ADD-DURATION function adds a duration to a date, time, or timestamp item, and returns the modified item.

The function type is date-time.

The length of the returned 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.

If a duration is added to a date item, the date returned must fall within a certain range:
  • For 4-digit dates, the range must be 0001/01/01 through 9999/12/31
  • For 2-digit dates, the range must be 0001/01/01 through 9999/12/31, but the year is truncated to 2 digits
  • For a 3-digit year (a 1-digit century and a 2-digit year), the range must be 1900/01/01 through 2899/12/31 (the default). This range can be changed by specifying the DATETIME compiler option.
If a duration is added to 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.

Format

Read syntax diagramSkip visual syntax diagramFUNCTION ADD-DURATION (argument-1argument-2argument-3)
argument-1
Must be date, time, or timestamp data item.

argument-1 is a data item containing a value to which a duration is added. The duration is specified in argument-2 and argument-3.

argument-2
argument-2 is a keyword that represents a duration. The valid duration keywords are:
  • YEARS
  • MONTHS
  • DAYS
  • HOURS
  • MINUTES
  • SECONDS
  • MICROSECONDS
  • PICOSECONDS
The duration keyword must be consistent with argument-1. For example, the duration keywords most obey the following rules:
  1. YEARS, MONTHS, and DAYS can only be added to a date or timestamp item.
  2. HOURS, MINUTES, SECONDS, and MICROSECONDS can only be added to a time or timestamp item.
  3. PICOSECONDS can only be added to a timestamp item.
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 added to argument-1.

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.

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

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

Examples

The following examples show how the ADD-DURATION intrinsic function can be used:

MOVE FUNCTION ADD-DURATION (date-3 MONTHS 1)
     TO  date-2.
MOVE FUNCTION ADD-DURATION (date-3 MONTHS int-1 * 2)
     TO  date-1.
MOVE FUNCTION ADD-DURATION (date-1  YEARS 1 MONTHS 5 DAYS 23)
     TO date-2.

Related references  
SUBTRACT-DURATION