Q(uick)BASIC Function: IPmt#

Quick View

IPmt#

A function that returns the interest payment for a given period of an annuity based on periodic, constant payments and a constant interest rate

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax
  • IPmt# (rate#, per#, nper#, pv#, fv#, type%, status%)
Description/Parameter(s)
rate# The interest rate per period (for example, .12).
per# The payment period; must be in the range from 1 to nper#.
nper# The number of payment periods in the annuity.
pv# The present value.
fv# The future value.
type% An integer expression:
  • 0 = end-of-period payment;
  • 1 = beginning-of-period payment.
status% A variable that indicates calculation success of failure:
  • 0 = success;
  • 1 = failure.
  • The argument rate# is the interest rate per period. For example, if you get a car loan at a 10% annual interest rate and make monthly payments, the rate per period would be .10/12, or .0083.
  • The argument nper# is the total number of payment periods in an annuity. For example, if you get a 4-year car loan and make monthly payments, your loan has a total number of 4x12, or 48 payment periods.
  • The arguments rate# and nper# must use consistent units. For example:
rate# nper# Loan description
.10/12 4*12 Monthly payment, 4-year loan, 10% annual interest
.10 4 Annual payment, 4-year loan, 10% annual interest
  • The argument pv# is the present value, or lump sum that a series of payments to be paid in the future is worth now. For example, when you borrow money to buy a car, the loan amount is the present value to the lender of the monthly car payments you will make.
  • The argument fv# is the future value, or cash balance sometime in the future after the final payment is made. The future value of a loan, for example, is 0. As another example, if you think you will need $50,000 in 18 years to pay for your child's education, then $50,000 is the future value.
  • The argument status% can be any variable that returns information about the success or failure of the calculation. The value of status% will be 0 if the calculation was successful, and 1 if it was not.

Usage Notes

  • An annuity is a series of constant cash payments made over a continuous period of time. An annuity can be a loan (such as a home mortgage), or an investment (such as a monthly savings plan).
  • For all arguments, cash you pay out, such as deposits to savings, is represented by negative numbers; cash you receive, such as dividend checks, is represented by positive numbers.

Important

  • To use IPmt# in the QBX environment, use the FINANCER.QLB Quick library. To use IPmt# outside the QBX environment, link your program with the appropriate FINANCxx.LIB file. Depending on the compiler options you chose when you installed BASIC, one or more of the following files will be available:
Filename Compiler options
FINANCER.LIB 80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB Alternate math; DOS or OS/2 real mode
FINANCEP.LIB 80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB Alternate math; OS/2 protected mode
  • The FINANC.BI header file contains the necessary function declarations for IPmt#.
  • For more information on using libraries, see "Creating and Using Quick Libraries" and "Using LINK and LIB" in the BASIC Programmer's Guide.
Example

This example uses the IPmt# function to calculate how much you will pay over the lifetime of a loan where all the payments are of equal value.
Note: To run this example you must use a Quick library that includes the procedures contained in one of the financial function library files and the FORMATD$ function contained in one of the date/time/format function library files. The following include files must also be present.

'$INCLUDE: 'FINANC.BI' '$INCLUDE: 'FORMAT.BI' CONST ENDPER = 0 CONST BEGINPER = 1 CONST DOLLARFORMAT$ = "$###,###,###.00" FutrVal = 0 DEFDBL A-Z DIM St AS INTEGER CLS INPUT "Enter the annual percentage rate of your loan"; APR PRINT INPUT "What is the principal amount of your loan"; PresVal PRINT INPUT "How many monthly payments do you have to make"; Periods PRINT DO WHILE PaymentTypeString$ <> "B" AND PaymentTypeString$ <> "E" PRINT "Are payments due at the beginning or end of the month? "; PaymentTypeString$ = UCASE$(INPUT$(1)) LOOP 'Set up the correct payment type. IF PaymentTypeString$ = "B" THEN PaymtType = BEGINPER PRINT "Beginning" ELSE PaymtType = ENDPER PRINT "End" END IF PRINT 'Put APR in proper form. IF APR > 1 THEN APR = APR / 100 FOR Per = 1 TO Periods 'Calculate the Interest paid each month. IntPmt = ABS(IPmt#(APR / 12, Per, Periods, -PresVal, FutrVal, PaymtType, St)) 'Check for an error. IF St% THEN PRINT "There was a calculation error." END END IF 'Accumulate a total. TotalInterest = TotalInterest + IntPmt NEXT Per TotalInterest$ = FormatD$(TotalInterest, DOLLARFORMAT$) PresentVal$ = FormatD$(PresVal, DOLLARFORMAT$) TotalPaid$ = FormatD$(TotalInterest + PresVal, DOLLARFORMAT$) PRINT PRINT "You'll pay a total of "; TotalPaid$; " on your "; PresentVal$ PRINT "loan, of which "; TotalInterest$; " is interest."