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.