Q(uick)BASIC Function: Rate#

Quick View

Rate#

A function that returns the interest rate per period for an annuity

Worth knowing

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

Syntax
  • Rate# (nper#, pmt#, pv#, fv#, type%, guess#, status%)
Description/Parameter(s)
nper# The number of payment periods in the annuity.
pmt# The payment to be made each period.
pv# The present value.
fv# The future value.
type% An integer expression:
  • 0 = end-of-period payment;
  • 1 = beginning-of-period payment.
guess# A value you guess is close to the result of Rate#.
status% A variable that returns a value indicating calculation failure or success:
  • 0 = success;
  • 1 = failure.
  • 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 pmt# is the payment made each period, and cannot change over the life of the annuity. Typically, pmt# contains principal and 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 guess# is a number you guess for what Rate# will be.
  • Rate# is calculated by iteration. Starting with the value of guess#, Rate# cycles through the calculation until the result is accurate within .00001%. If after 20 tries it can't find a result that works, Rate# returns a status of 1.
  • In most cases you can assume the argument guess# to be 0.1 (10%). However, if Rate# returns a status of 1 (failure), or if the result is not close to what you expected, try different values of guess#.
  • 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 Rate# in the QBX environment, use the FINANCER.QLB Quick library. To use Rate# 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 Rate#.
  • 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 Rate# function to determine the interest rate of a loan.
Note: To run this example you must use a Quick library that includes the procedures contained in the date/time/format and financial function library files. The following include files must also be present.

'$INCLUDE: 'FINANC.BI' '$INCLUDE: 'FORMAT.BI' CONST ENDPER = 0 CONST BEGINPER = 1 CONST PERCENT$ = "#0.0" DEFDBL A-Z DIM Status AS INTEGER PresVal = 8000 Pmnt = 200 Guess = .5 'Explain the premise. CLS PRINT "Your brother-in-law says he'll loan you $8000.00 if you agree to" PRINT "repay the loan over the next 4 years at $200.00 a month. What he" PRINT "doesn't tell you is the interest rate he's charging. Banks will " PRINT "charge you at least 12% a year. You need to know what your" PRINT "brother-in-law's interest rate is so you can get the best deal." PRINT 'Calculate the interest rate. IntRate = (Rate#(48, -Pmnt, PresVal, 0, BEGINPER, Guess, Status) * 12) * 100 'Examine Status to determine success or failure of Rate#. IF Status THEN 'If unsuccessful, announce a problem. PRINT "There was an error in calculating the interest rate." ELSE 'If successful format and display the results. IntRate$ = FormatD$(IntRate, PERCENT$) PRINT "Calculations show that your brother-in-law is only going to" PRINT "charge you "; IntRate$; "% per year. Sounds like a nice guy." END IF

See also: