DTADD: Incrementing a Date or Date-Time Component

How to:

Reference:

Given a date in standard date or date-time format, DTADD returns a new date after adding the specified number of a supported component. The returned date format is the same as the input date format.

Syntax: How to Increment a Date or Date-Time Component

DTADD(date, component, increment)

where:

date

Date or date-time

Is the date or date-time value to be incremented, which must provide a full component date.

component

Keyword

Is the component to be incremented. Valid components (and acceptable values) are:

  • YEAR (1-9999).
  • QUARTER (1-4).
  • MONTH (1-12).
  • WEEK (1-53). This is affected by the WEEKFIRST setting.
  • DAY (of the Month, 1-31).
  • HOUR (0-23).
  • MINUTE (0-59).
  • SECOND (0-59).
increment

Integer

Is the value (positive or negative) to add to the component.

Example: Incrementing the DAY Component of a Date

The following request against the WF_RETAIL data source adds three days to the employee date of birth:

DEFINE FILE WF_RETAIL
NEWDATE/YYMD = DTADD(DATE_OF_BIRTH, DAY, 3);
MGR/A3 = DIGITS(ID_MANAGER, 3);
END
TABLE FILE WF_RETAIL
SUM MGR NOPRINT DATE_OF_BIRTH NEWDATE
BY MGR
ON TABLE SET PAGE NOPAGE
END

The output is:

Reference: Usage Notes for DTADD

  • Each element must be manipulated separately. Therefore, if you want to add 1 year and 1 day to a date, you need to call the function twice, once for YEAR (you need to take care of leap years) and once for DAY. The simplified functions can be nested in a single expression, or created and applied in separate DEFINE or COMPUTE expressions.
  • With respect to parameter validation, DTADD will not allow anything but a standard date or a date-time value to be used in the first parameter.
  • The increment is not checked, and the user should be aware that decimal numbers are not supported and will be truncated. Any combination of values that increases the YEAR beyond 9999 returns the input date as the value, with no message. If the user receives the input date when expecting something else, it is possible there was an error.