Q(uick)BASIC Function: FV#

Quick View

FV#

A function that returns the future value 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

FV# (rate#, nper#, pmt#, pv#, type%, status%)

Description/Parameter(s)

rate#	The interest rate per period (for example, .12).
nper#	The number of payment periods in the annuity.
pmt#	The payment to be made each period.
pv#	The present value.
type%	An integer expression:
type%	0 = end-of-period payment; 1 = beginning-of-period payment.
status%	A variable that returns a value indicating calculation failure or success: 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 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 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.
The formula for FV# is described in the BASIC Language Reference manual.

Important

To use FV# in the QBX environment, use the FINANCER.QLB Quick library. To use FV# 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 FV#.
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 FV# function to return the future value of an investment. You are prompted to input required information.
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 ENDPERIOD = 0
CONST BEGINPERIOD = 1
CONST DOLLARFORMAT$ = "$#,###,##0.00"
CONST PERCENTFORMAT$ = "##.00"
 
DEFDBL A-Z
DIM APR AS SINGLE
DIM PaymentType AS INTEGER, Status AS INTEGER
 
CLS
INPUT "Enter the expected annual percentage rate "; APR
PRINT
INPUT "How much do you plan to invest each month"; Payment
PRINT
 
DO WHILE PaymentTypeString$ <> "B" AND PaymentTypeString$ <> "E"
    PRINT "Make payments at the beginning or end of the month? ";
    PaymentTypeString$ = UCASE$(INPUT$(1))
LOOP
 
'Set up the correct payment type.
IF PaymentTypeString$ = "B" THEN
    PaymentType = BEGINPERIOD
    PRINT "Beginning"
ELSE
    PaymentType = ENDPERIOD
    PRINT "End"
END IF
 
PRINT
INPUT "How long, in months, do you expect to invest"; Period
PRINT
 
INPUT "What is the current value, if any, of this investment"; CurVal
PRINT
 
'Calculate and format the results.
 
'Put APR in proper form.
IF APR <= 1 THEN
    PercentageRate$ = FORMATS$(APR * 100, PERCENTFORMAT$) + "%"
ELSE
    PercentageRate$ = FORMATS$(APR, PERCENTFORMAT$) + "%"
    APR = APR / 100
END IF
 
Payment$ = FormatD$(Payment, DOLLARFORMAT$)
CurValue$ = FormatD$(CurVal, DOLLARFORMAT$)
FutrVal = FV#(APR / 12, Period, -Payment, -CurVal, PaymentType, Status)
FutureValue$ = FormatD$(FutrVal, DOLLARFORMAT$)
 
'Examine Status to determine success or failure of FV#.
IF Status THEN
    'If unsuccessful, announce a problem.
    PRINT "There was an error in calculating the future value."
ELSE
    'If successful, display the results.
    PRINT
    PRINT "At "; PercentageRate$; " interest, your "; Payment$; " per month"
 
    IF PaymentType = BEGINPERIOD THEN
  PRINT "(paid at the beginning of each month), "
    ELSE
  PRINT "(paid at the end of each month), "
    END IF
 
    IF CurVal > 0 THEN
  PRINT "plus the "; CurValue$; " your investment is currently worth,"
    END IF
 
    PRINT "will be worth "; FutureValue$; " after"; Period; "months."
END IF