SQL Server ConstantCashFlow Function

Updated 2024-02-16 14:59:21.310000

Description

Use the table-valued function ConstantCashFlow to return the cash flow schedule for a loan with with a fixed maturity date and annuity-style payments. ConstantCashFlow computes the periodic interest and principal amounts through to the maturity date.

The payment period is entered in ConstantCashFlows as the number of months between payments. For example, a loan with monthly payments would have a frequency of 1. A loan with quarterly payments would have frequency of 3. A loan with annual payments would have a frequency of 12.

ConstantCashFlow supports both an initial grace period and an additional grace period during the life of the loan. All payments and their associated dates are calculated with respect to the reference date supplied to the function (which should not be confused with the start date). If an initial grace period is entered in ConstantCashFlow and it is greater than the reference date, then it becomes the first interest payment date and subsequent interest payments are calculated from that date forward.

If any payments would otherwise occur in the specified grace period, then that payment is moved to the end of the grace period and all remaining payments are calculated from the end of the grace period.

If no initial grace period is specified then the first payment date is calculated using the interest payment frequency. If the start date has been entered and the number of months between the start date and the reference date is less than the frequency, then the first payment date is calculated by adding the frequency (as a number of months) to the start date.

If no start date has been entered but a previous payment date has been entered and the number of months between the previous payment date and the reference date is less than the frequency, then the first payment date is calculated by adding the frequency (as a number of months) to the previous payment date.

If there is no start date and previous payment dates or the number of months between those dates and the reference date is greater than the frequency, then the first payment date is calculated by adding the frequency (as a number of months) to the reference date.

All payments in the resultant table are moved to the end of the month and interest is calculated using these end-of-month dates.

The interest payment is calculated as:

I=P\times\left[\left(\left(1+\frac{R\times{F}}{12}\right)^{12\slash{F}}\right)^T\right]-1

Where:

If the irregular period is longer than the regular period then the interest amount is broken out into the regular interest amount and a 'grace' interest amount.

Syntax

SELECT * FROM [westclintech].[wct].[ConstantCashFlow](
  <@OutstandingAmount, float,>
 ,<@LastPrinPayAmount, float,>
 ,<@InterestRate, float,>
 ,<@PaymentFrequency, int,>
 ,<@MaturityDate, datetime,>
 ,<@ReferenceDate, datetime,>
 ,<@PrevPayDate, datetime,>
 ,<@StartDate, datetime,>
 ,<@FirstPayDate, datetime,>
 ,<@GracePeriodStartDate, datetime,>
 ,<@GracePeriodEndDate, datetime,>)

Arguments

@OutstandingAmount

the principal amount of the loan. @OutstandingAmount is an expression of type float or of a type that can be implicitly converted to float.

@LastPrinPayAmount

the amount of principal to be paid off on the the maturity date. @OutstandingAmount is an expression of type float or of a type that can be implicitly converted to float.

@InterestRate

the annual rate of interest for the loan. @InterestRate is an expression of type float or of a type that can be implicitly converted to float.

@PaymentFrequency

the number of months in a regular payment. @PaymentFrequency is an expression of type int or of a type that can be implicitly converted to int.

@MaturityDate

the last payment date of the loan. @MaturityDate is an expression that returns a datetime or smalldatetime value, or a character string in date format.

@ReferenceDate

the starting date for the number of months with respect to all other dates. @ReferenceDate is an expression that returns a datetime or smalldatetime value, or a character string in date format.

@PrevPayDate

the last payment date prior to the reference date. @PrevPayDate is an expression that returns a datetime or smalldatetime value, or a character string in date format.

@StartDate

the start date of the loan. @StartDate is an expression that returns a datetime or smalldatetime value, or a character string in date format.

@FirstPayDate

the first payment date of the loan if other than a regular periodic payment. @FirstPayDate is an expression that returns a datetime or smalldatetime value, or a character string in date format.

@GracePeriodStartDate

the date on which the (interim) grace period commences. @GracePeriodStartDate is an expression that returns a datetime or smalldatetime value, or a character string in date format.

@GracePeriodEndDate

the date on which the (interim) grace period concludes. @GracePeriodEndDate is an expression that returns a datetime or smalldatetime value, or a character string in date format.

Return Type

table

Remarks

The PaymentDate for all rows is generated as the last day of the month.

For Period = 0, PrincipalPayment, InterestPayment, CashFlow, NumberOfMonth, GraceInterest, and InterestRate are set to 0.

If @Frequency is NULL then @Frequency = 1.

If @InterestRate is NULL then @InterestRate = 0.

If @ReferenceDate is NULL then @ReferenceDate = GETDATE().

GraceInterest is only calculated on @FirstPayDate and @GracePeriodEndDate.

GraceInterest is only calculated if NumberOfMonth – NumberOfMonth(Period-1) > @PaymentFrequency.

GraceInterest is the difference between the interest for the period from the previous row to the current row minus interest that would have been calculated for a period with length equal to @PaymentFrequency.

CashFlow may change on @FirstPayDate or @GracePeriodEndDate due to GraceInterest.

The final payment is adjusted for CapitalAmountInDebt(Period-1) and the length of the period if it is less than @PaymentFrequency.

The last row returned will always be for the maturity date and may be shorter than a regular period depending on the combination of dates and @PaymentFrequency.

Examples

This is a simple a 300,000 loan with quarterly payments and an interest rate of 6.0%.

SELECT *
FROM wct.ConstantCashFlow(   300000,       --@OutstandingAmount
                             0,            --@LastPrinPayAmount
                             .06,          --@InterestRate
                             3,            --@PaymentFrequency
                             '2019-12-15', --@MaturityDate
                             '2014-12-15', --@ReferenceDate
                             NULL,         --@PrevPayDate
                             NULL,         --@StartDate
                             NULL,         --@FirstPayDate
                             NULL,         --@GracePeriodStartDate
                             NULL          --@GracePeriodEndDate
                         );

This produces the following result.

In this example, we modify the SQL to reflect a final principal payment of 172,000.

SELECT *
FROM wct.ConstantCashFlow(   300000,       --@OutstandingAmount
                             172000,       --@LastPrinPayAmount
                             .06,          --@InterestRate
                             3,            --@PaymentFrequency
                             '2019-12-15', --@MaturityDate
                             '2014-12-15', --@ReferenceDate
                             NULL,         --@PrevPayDate
                             NULL,         --@StartDate
                             NULL,         --@FirstPayDate
                             NULL,         --@GracePeriodStartDate
                             NULL          --@GracePeriodEndDate
                         );

This produces the following result.

In this example we modify the SQL by adding a first payment date of 15-June-2015.

SELECT *
FROM wct.ConstantCashFlow(   300000,       --@OutstandingAmount
                             172000,       --@LastPrinPayAmount
                             .06,          --@InterestRate
                             3,            --@PaymentFrequency
                             '2019-12-15', --@MaturityDate
                             '2014-12-15', --@ReferenceDate
                             NULL,         --@PrevPayDate
                             NULL,         --@StartDate
                             '2015-06-15', --@FirstPayDate
                             NULL,         --@GracePeriodStartDate
                             NULL          --@GracePeriodEndDate
                         );

This produces the following result.

We modify the SQL so that there are no payments in 2018.

SELECT *
FROM wct.ConstantCashFlow(   300000,       --@OutstandingAmount
                             172000,       --@LastPrinPayAmount
                             .06,          --@InterestRate
                             3,            --@PaymentFrequency
                             '2019-12-15', --@MaturityDate
                             '2014-12-15', --@ReferenceDate
                             NULL,         --@PrevPayDate
                             NULL,         --@StartDate
                             '2015-06-15', --@FirstPayDate
                             '2018-01-01', --@GracePeriodStartDate
                             '2019-01-01'  --@GracePeriodEndDate
                         );

This produces the following result.

In the example we modify the SQL by changing the @FirstPayDate to NULL and @PrevPayDate to '2014-11-15', so the the first payment date will be calculated using a previous payment date.

SELECT *
FROM wct.ConstantCashFlow(   300000,       --@OutstandingAmount
                             172000,       --@LastPrinPayAmount
                             .06,          --@InterestRate
                             3,            --@PaymentFrequency
                             '2019-12-15', --@MaturityDate
                             '2014-12-15', --@ReferenceDate
                             '2014-11-15', --@PrevPayDate
                             NULL,         --@StartDate
                             NULL,         --@FirstPayDate
                             '2018-01-01', --@GracePeriodStartDate
                             '2019-01-01'  --@GracePeriodEndDate
                         );

This produces the following result.

In this SQL, we eliminate the grace period and the previous payment date and add a start date.

SELECT *
FROM wct.ConstantCashFlow(   300000,       --@OutstandingAmount
                             172000,       --@LastPrinPayAmount
                             .06,          --@InterestRate
                             3,            --@PaymentFrequency
                             '2019-12-15', --@MaturityDate
                             '2014-12-15', --@ReferenceDate
                             NULL,         --@PrevPayDate
                             '2014-10-15', --@StartDate
                             NULL,         --@FirstPayDate
                             NULL,         --@GracePeriodStartDate
                             NULL          --@GracePeriodEndDate
                         );

This produces the following result.

See Also

BALLOON - Schedule with periodic interest payments and principal repaid at maturity

BULLET - Schedule with single interest and principal payment at maturity

CONSTANTPAYMENTAMOUNT - Schedule with no maturity with fixed periodic payment amount

CONSTANTPRINCIPAL - Schedule with fixed maturity date where the periodic principal payment is calculated on a straight-line basis

CONSTANTPRINCIPALAMOUNT - Schedule with no fixed maturity with a fixed periodic principal payment

CONSTANTPRINCIPALRATE - Schedule with no fixed maturity where a fixed percentage principal payment

PAYMENTPERIODS - Number of months until first payment date, start of grace period, end of grace period, and total number payments for a loan