Date Increment

The *DATE INCREMENT built-in function lets you add a quantity to a given date. You specify the kind of quantity to add using the *Duration type parameter.

Note that you should check the return code set by this function in order to catch any errors encountered.

This function is the converse of the *DURATION function.

The *DATE INCREMENT built-in function performs the operation: *Date1 = *Date2 + *Duration

There are eight parameters for this function type:

· Seven input parameters

° *Date2 specifies the beginning date. If it is of type NBR, it is interpreted as the number of days since January 1, 1801 (day one).

° *Duration specifies the quantity to be added to the beginning date. Its meaning is determined by the value of *Duration type.

° *Duration type specifies the meaning of the quantity to be added to the beginning date. See the table at the end of this topic. ° *Excluded days of week specifies days that are normally not to be included in the sum.

° *Date List name specifies the name of an existing date list. Date lists let you override selection rules set by the *Excluded days of week parameter for particular dates. The specified date list needs to be in the *Date Lists array when the built-in function executes.

° *Date list autoload determines whether the function is to automatically load the specified date list into the *Date Lists array when the function is executed.

° *Select days/dates lets you reverse the date selection determined by the *Date List name and *Excluded days of week parameters. The default is to select included dates.

· One output parameter, *Date1, which specifies the result date. If it is of type NBR, it is interpreted as the number of days since January 1, 1801 (day one).

The possible values for *Duration type and the effect each has on the meaning of the *Duration parameter are shown in the following table.

Example

Suppose you want to calculate the next interest payment date for a loan where an interest payment is due every 20 days, not including weekends. For example, if the last payment date was, August 4, 1994, the next interest payment is due, September 1, 1994.

Following are parameter specifications for the *DATE INCREMENT built-in function that produce this result. Scroll to view the *Date list autoload and *Selected days/dates parameters.

Duration

The *DURATION built-in function calculates the elapsed time between a beginning date and an ending date.

Note that you should check the return code set by this function in order to catch any errors encountered.

This function is the converse of the *DATE INCREMENT built-in function.

The *DURATION built-in function performs the operation: *Duration = *Date1 -- *Date2

The result is positive if *Date1 is after *Date2; it is negative if *Date1 is before *Date2.

There are eight parameters for this function type:

· Seven input parameters

° *Date2 and *Date1 specify the beginning and ending dates, respectively. When either date is of type NBR, it is interpreted as the number of days since January 1, 1801 (day one).

° *Duration type specifies the meaning of the result of the operation. See the table at the end of this topic.

° *Excluded days of week specifies days to be excluded from the operation; for example, weekends or days not worked by part-time employees.

° *Date List name specifies the name of an existing date list. Date lists let you override normal selection rules set by the *Excluded days of week parameter for particular dates. The specified date list needs to be in the *Date Lists array when the built-in function executes.

° *Date list autoload determines whether the function automatically loads the specified date list into the *Date Lists array when the function is executed.

° *Select days/dates lets you reverse the selection determined by the *Excluded days of week and *Date List name parameters.

The default is to select included dates. · One output parameter, *Duration. The meaning of this parameter is determined by the value of *Duration type.

The *Date list, *Excluded days of week, and *Select days/dates parameters affect only days/dates after the beginning date.

If the ending date is before the beginning date, these parameters affect only days/dates after the ending date.

The possible values for *Duration type and the effect each has on the meaning of *Duration are shown in the following table.

Example

Suppose you want to calculate the number of years, months, and days between the date an order was placed and the date payment was received.

Include Saturdays, but exclude Sundays and holidays from the count.

Following are parameter specifications for the *DURATION built-in function that will produce this result.

Note that this example assumes that you have created a Date List named Holidays that specifies the dates of holidays to be excluded from the count.

Scroll to change the *Date list autoload parameter to *YES.

Elapsed Time

The *ELAPSED TIME built-in function calculates the elapsed time between a beginning time and an ending time.

It is the converse of the *TIME INCREMENT built-in function.

The *ELAPSED TIME built-in function performs the operation: *Elapsed Time = *Time1 -- *Time2

The result is positive if *Time1 is after *Time2; it is negative if *Time1 is before *Time2.

There are four parameters for this function type:

· Three input parameters

° *Time2 and *Time1 specify the beginning and ending times, respectively. When either time is of type NBR, it is interpreted as the elapsed time since 0 a.m.

° *Time unit specifies the meaning of the *Elapsed time output parameter.

· One output parameter, *Elapsed time. The meaning of this parameter is determined by the value of *Time unit.

The valid values for *Time unit and the effect each has on the meaning of *Elapsed time are shown in the following table.

Example

Suppose you want to calculate the number of hours and minutes it took one of your company’s drivers to travel from the warehouse to the airport.

For example, if the driver left at 6:40 am and arrived at 7:55 am, the elapsed time is 1 hour and 15 minutes, or 0115 in *HHMM format. Following are parameter specifications for the *ELAPSED TIME built-in function that produce this result