ADDDUR (Add Duration)

Free-Form Syntax (not allowed - use the + or += operators with duration functions such as %YEARS and %MONTHS)
Code Factor 1 Factor 2 Result Field Indicators
ADDDUR (E) Date/Time Duration:Duration Code Date/Time _ ER _

The ADDDUR operation adds the duration specified in factor 2 to a date or time and places the resulting Date, Time or Timestamp in the result field.

Factor 1 is optional and may contain a Date, Time or Timestamp field, subfield, array, array element, literal or constant. If factor 1 contains a field name, array or array element then its data type must be the same data type as the field specified in the result field. If factor 1 is not specified the duration is added to the field specified in the result field.

Factor 2 is required and contains two subfactors. The first is a duration and may be a numeric field, array element or constant with zero decimal positions. If the duration is negative then it is subtracted from the date. The second subfactor must be a valid duration code indicating the type of duration. The duration code must be consistent with the result field data type. You can add a year, month or day duration but not a minute duration to a date field. For list of duration codes and their short forms see Date Operations.

The result field must be a date, time or timestamp data type field, array or array element. If factor 1 is blank, the duration is added to the value in the result field. If the result field is an array, the value in factor 2 is added to each element of the array. If the result field is a time field, the result will always be a valid Time. For example adding 59 minutes to 23:59:59 would give 24:58:59. Since this time is not valid, the compiler adjusts it to 00:58:59.

When adding a duration in months to a date, the general rule is that the month portion is increased by the number of months in the duration, and the day portion is unchanged. The exception to this is when the resulting day portion would exceed the actual number of days in the resulting month. In this case, the resulting day portion is adjusted to the actual month end date. The following examples (which assume a *YMD format) illustrate this point.
  • '98/05/30' ADDDUR 1:*MONTH results in '98/06/30'

    The resulting month portion has been increased by 1; the day portion is unchanged.

  • '98/05/31' ADDDUR 1:*MONTH results in '98/06/30'

    The resulting month portion has been increased by 1; the resulting day portion has been adjusted because June has only 30 days.

Similar results occur when adding a year duration. For example, adding one year to '92/02/29' results in '93/02/28', an adjusted value since the resulting year is not a leap year.

An error situation arises when one of the following occurs:
  • The value of the Date, Time or Timestamp field in factor 1 is invalid
  • Factor 1 is blank and the value of the result field before the operation is invalid
  • Overflow or underflow occurred (that is, the resulting value is greater than *HIVAL or less than *LOVAL).
In an error situation,
  • An error (status code 112 or 113) is signalled.
  • The error indicator (columns 73-74) — if specified — is set on, or the %ERROR built-in function — if the 'E' extender is specified — is set to return '1'.
  • The value of the result field remains unchanged.

To handle exceptions with program status codes 112 or 113, either the operation code extender 'E' or an error indicator ER can be specified, but not both. For more information on error handling, see Program Exception/Errors.

Note: The system places a 15-digit limit on durations. Adding a Duration with more than 15 significant digits will cause errors or truncation. These problems can be avoided by limiting the first subfactor in Factor 2 to 15 digits.

For more information on working with date-time fields, see Date Operations.

Figure 1. ADDDUR Operations
*...1....+....2....+....3....+....4....+....5....+....6....+....7...+....
HKeywords+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
H TIMFMT(*USA) DATFMT(*MDY&)
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++
 *
DDateconst        C                   CONST(D'12 31 92')
 *
 * Define a Date field and initialize
 *
DLoandate         S               D   DATFMT(*EUR) INZ(D'12 31 92')
DDuedate          S               D   DATFMT(*ISO)
Dtimestamp        S               Z
Danswer           S               T
CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq....
 * Determine a DUEDATE which is xx years, yy months, zz days later
 * than LOANDATE.
C     LOANDATE      ADDDUR    XX:*YEARS     DUEDATE
C                   ADDDUR    YY:*MONTHS    DUEDATE
C                   ADDDUR    ZZ:*DAYS      DUEDATE
 * Determine the date 23 days later
 *
C                   ADDDUR    23:*D         DUEDATE
 * Add a 1234 microseconds to a timestamp
 *
C                   ADDDUR    1234:*MS      timestamp
 * Add 12 HRS and 16 minutes to midnight
 *
C     T'00:00 am'   ADDDUR    12:*Hours     answer
C                   ADDDUR    16:*Minutes   answer
 * Subtract 30 days from a loan due date
 *
C                   ADDDUR    -30:*D        LOANDUE