%SUBDT (Extract a Portion of a Date, Time, or Timestamp)


%SUBDT(value : unit { : digits { : decpos } })

The unit can be *MSECONDS, *SECONDS, *MINUTES, *HOURS, *DAYS, *MONTHS, or *YEARS. You can also use the following abbreviated forms of the units: *MS, *S, *MN, *H, *D, *M, or *Y.

%SUBDT extracts a portion of the information in a date, time, or timestamp value. It returns an unsigned numeric value.

The first parameter is the date, time, or timestamp value.

The second parameter is the portion that you want to extract. The following values are valid:

For a date: *DAYS, *MONTHS, and *YEARS
For a time: *SECONDS, *MINUTES, and *HOURS
For a timestamp: *MSECONDS, *SECONDS, *MINUTES, *HOURS, *DAYS, *MONTHS, and *YEARS
The third parameter is optional. It represents the number of digits in the returned value.
The fourth parameter is optional. It represents the number of decimal places, or fractional seconds, in the returned value. It can be specified when the first parameter is a timestamp and the second parameter is *SECONDS or *S. For example, if you want the returned value to have 7 decimal places, specify 9 for the digits parameter and 7 for the decpos parameter.

For this function, *DAYS always refers to the day of the month not the day of the year (even if you are using a Julian date format). For example, the day portion of February 10 is 10 not 41.

This function always returns a 4-digit year, even if the date format has a 2-digit year.

For more information, see Date Operations or Built-in Functions.

Figure 1. %SUBDT Example

 *..1....+....2....+....3....+....4....+....5....+....6....+....7...+....

     date = d'1999-02-17';
     time = t'01.23.45';
     timestamp = z'1999-02-17-01.23.45.98765';

     num = %subdt(date:*YEARS);
     // num = 1999

     num = %subdt(time:*MN);
     // num = 23

     seconds = %subdt(timestamp:*S:5:3);
     // seconds = 45.987