Libraries Tutorial

Introduction to User-Defined Functions

Internal functions are very useful, but what if you want to regularly repeat an action that isn't already built into BR? You can write your own functions, called user-defined functions. The special feature of BR is that, once defined accurately, these functions can be accessed and used from other programs too. This access is called the LIBRARY facility. Basically, all programs also become potential libraries of functions.

Sample User Defined Function

We'll create a simple accounting program, called SALES1, containing a user-defined function entitled FnTotalsales to calculate tax and sales commission for sales.

00030     print Newpage
00040     print fields "2,2,cr 25; 3,2,cr 25": "Total gross sales amount?","Commission rate?(%)"
00050     input fields "2,28,n 10; 3,28,n 10.2": Sales,Comrate
00060  !
00070     library : Fntotalsales
00080     let Totalsales=Fntotalsales(Sales,Comrate,.0825,tax,commission)
00090  !
00100     print fields "6,4,cr 12;6,16,pic($$$$,$$$);8,4,cr 12;8,16,PIC($$$,$$$.##)" : "Tax:",Tax,"Commission:",Commission
00110     print fields "10,4,cr 12;10,16,pic($$$$,$$$.##)": "TOTAL:",Totalsales
00120  !
00130     stop
00140  !
00170     def library Fntotalsales(Sales,Comrate,Taxrate;&Tax,&Commission)
00180        let Tax = Sales*Taxrate
00190        let Comrate=Comrate/100
00200        let Commission=Sales*Comrate
00210        let Fntotalsales=Sales-Commission+Tax
00220     fnend

Line 70 defines the function as a library, which means that other programs can find and use this function. Since the function is contained here in this program, only the function name is required after the colon. If the function was contained in another program, the program would be named (with its location if it's not found in the same folder). For example:

library "sales1" : Fntotalsales

Line 80 initiates the function and provides it with the variables necessary. Line 130 stops the program from continuing into the function again. The function has been placed outside of the main program for clarity and organization, in lines 170 to 220. Note that line 170 specifies that this is a library function, the function name and the variables needed.

Regarding variables: If the variables must be passed back to the program, the variable name must be preceded by an ampersand (&) symbol (line 170). If the variables must be passed in and out sometimes, but not every time the function is called, they are listed after a semi-colon. If placed after the semicolon, variables by the same name that are mentioned elsewhere in the program will not be affected by the function.

Calling a Library Function

To demonstrate the LIBRARY facility, we will write a second program, called SALES2, to access the function from the first. This program determines sales, tax, and commission, based on how many subscriptions are sold.

00020     print Newpage
00030     print fields "2,2,cr 25; 3,2,cr 25;4,2,cr 25": "Total subscriptions sold?","Commission rate?(%)","Bonus commission?(%)"
00040     input fields "2,28,n 10; 3,28,n 10.2; 4,28,n 10.2": subscriptions,Comrate,bonusrate
00050  !
00060     let sales=subscriptions*150
00070     let comrate=comrate+bonusrate
00080  !
00090     library "sales1" : Fntotalsales
00100     let Totalsales=Fntotalsales(Sales,Comrate,.0825,tax,commission)
00110  !
00120     print fields "6,4,cr 12;6,16,pic($$$$,$$$);8,4,cr  12;8,16,PIC($$$,$$$.##)" : "Tax:",Tax,"Commission:",Commission
00130     print fields "10,4,cr 12;10,16,pic($$$$,$$$.##)": "TOTAL:",Totalsales
00140  !
00150     stop

In Line 90, the library and function are called. The program containing the function is named in quotations before the colon, while the function name is listed after the colon again.

Line 100 initiates the function and provides the variables necessary.

Since functions in libraries can be accessed from other programs, it helps the programmer standardize activity across different programs while also shortening program length by removing repeated sections. Also, changes only need to be made to the library function instead of individually updating all programs when needed. For these reasons, many programmers choose to create a program that is solely used as a library, a single place to store all their functions and access them for use from each individual program when needed.

Next: Advanced Array Processing
Back: Table of Contents