BR Wiki - User contributions [en]

User-defined function

2013-04-16T20:56:15Z

66.17.154.248: Redirected page to User Defined Functions

#redirect[[User Defined Functions]]

Library Facility

2013-04-15T19:33:00Z

66.17.154.248: /* Comparison of User-Defined Function Features */

[[Business Rules!]] now includes a comprehensive '''Library''' Facility. Similar to [[DLL]] (Dynamic Link Libraries), the Business Rules! Library Facility enables [[user-defined functions]] to be placed in a program ("library") that is separate from the main program. The library may be loaded "resident" (staying loaded regardless of the status of the main program), it may be loaded "present" (remaining active in current memory as long as the main program is active), or it may be loaded "as needed" (loaded when needed to execute a function, then unloaded as soon as the function has been executed).

A library is any [[Business Rules! program]] that contains library functions. A library must be identified to Business Rules! before a program can execute any of its functions. When a library is identified, Business Rules! adds its name to an internal table of library names. This table identifies the names of all the libraries that should be searched whenever a library function that is not yet linked to a library is called.

Business Rules! places no limits on the number of libraries that may be loaded into memory at one time. Business Rules! provides for maximum memory usage and performance flexibility by allowing libraries to be identified and loaded into memory via three different methods: the resident method, the present method and the as-needed method. See the separate descriptions below for specific information about each type of library.

==Advantages==

Some of the significant advantages of placing user-defined functions in a library rather than keeping them in the main program are as follows:

:1.) Reduces the size of executables - its no longer necessary to include a standard set of user-defined functions in every program in your application. For some applications (which may include literally hundreds of copies of the exact same code), the potential savings in disk space are tremendous.

:2.) Saves maintenance time - If you're in the habit of duplicating user-defined functions in every single program that needs them, you know what kind of effort it takes to make (and distribute to your clients) even a one-line change to a function. With Business Rules Library Facility, you make the change only once, and you replace only one program at the client's site.

:3.) Encourages use of programming standards - The use of library functions for a standard routine is a great way to encourage programming consistency and the setting of standards among your programmers.

==Library Function==

A '''library function''' is a specially defined [[user-defined function]]; it exists in a program which is frequently separate from the main program, but it may exist in the main program as well.

To qualify as a library function, a user-defined function must simply utilize the DEF statement's LIBRARY keyword. The following is an example of a library function definition:

52400 DEF LIBRARY FNRESLIB2
52500 PRINT "This is a library function"
52600 FNEND

Executing a library function is a two-step process. First, the program executing the library function must name the function in a LIBRARY statement, which establishes either named or unnamed linkage. Second, the program must call the library function; this may be accomplished using any of the same methods that is available for calling other user-defined functions. In the following example, line 01000 uses the LIBRARY statement to establish named linkage between the function FNPRESLIB2 and the library PRESLIB. Line 01100 causes the library PRESLIB to be loaded into present memory (if the library does not already exist in memory), then executes FNPRESLIB2.

01000 LIBRARY "PRESLIB": FNPRESLIB2
01100 LET FNPRESLIB2

===Implementation Considerations===

Business Rules Facility was carefully designed to offer a great deal of power and flexibility. Before you begin implementing this capability into your existing applications and ongoing development, ADS recommends that you consider the following:

:1.) Should your libraries remain resident?
Business Rules allows for libraries to remain resident in memory (providing maximum performance) or to be loaded and released as needed (providing best utilization of memory). Be sure to select the method or combination of methods that's best for your applications.

:2.) Will you use multiple versions of the same function?
Since maintaining more than one version of a function is one method of controlling program options, Business Rules' rule for library selection has been established with care. You should carefully review these rules and the ways in which multiple libraries can be of use to you as you plan your implementation.

Until you feel comfortable with the intricacies of the Business Rules Library Facility, ADS recommends that you give every library function a name that is unique from every other library function.

:3.) Do your existing functions utilize global program variables?
Unlike local user-defined functions, library functions that exist in a program separate from the main program cannot access main program variables globally. They have to be specifically passed. You should carefully review your usage of global variables before moving local functions into separate libraries.

===As needed Library===

An as-needed library is loaded and unloaded as needed for execution of specific functions. Loading a library only when it is needed allows the program to conserve memory usage.

Each library has its own global variables that are separate from the main program's variables. Global Variables in an as-needed library are cleared each time a function call to the library is completed and the library is subsequently unloaded from memory.

Programs can indicate that a library is to be loaded as needed by specifying the LIBRARY statement with both the RELEASE parameter and function names. This causes Business Rules to establish named linkage between the specified function(s) and the specified library, but it does not actually load the library. (The library is loaded only when one of the as-needed library's functions is actually called.) In the following example, line 00280 establishes linkage between the library ASNLIB and the function FNASNLIB1. Line 00290 causes the following to occur:

:1.) Load ASNLIB into memory,
:2.) Execute the function FNASNLIB1,
:3.) Remove ASNLIB from memory.

00280 LIBRARY RELEASE,"ASNLIB": FNASNLIB1
00290 LET FNASNLIB1

===Linkage Reassignment and Detachment===

Once Business Rules has established linkage between a specific function and a specific library, the linkage remains active until a specific event causes it to become reassigned or detached.

;REASSIGNMENT:
As noted previously, the LIBRARY statement may be used to establish linkage between a function and the library from which it is to be called. When the named LIBRARY statement is used, linkage is directly established between the named library and the named function(s). When the unnamed LIBRARY statement is used, Business Rules searches for the function according to some pre-set guidelines and assigns linkage to the first library within which the function definition is found.

Once a function has actually been linked to a library, the only way to subsequently establish linkage between the same function name and a different library is to execute another LIBRARY statement that names the same function and a different library. When all of a present library's linked functions are reassigned; the library is automatically removed from memory. When all of a resident library's linked functions are reassigned; the library may be removed from memory with the CLEAR command.

In the following example, lines 01100 and 01200 load the libraries PRESLIB1 and PRESLIB2 into present memory. Line 01300 uses a named library statement to establish linkage between PRESLIB1 and the function FNASSIGN, and line 01400 actually executes FNASSIGN from the PRESLIB1 library. Line 1500 then re-assigns linkage of FNASSIGN to the library PRESLIB2, and line 1600 executes FNASSIGN from the PRESLIB2 library.

01100 LIBRARY "PRESLIB1":
01200 LIBRARY "PRESLIB2":
01300 LIBRARY "PRESLIB1": FNASSIGN
01400 LET FNASSIGN
01500 LIBRARY "PRESLIB2": FNASSIGN
01600 LET FNASSIGN

;DETACHMENT:
Regardless of how a library is loaded (resident, present or as needed), all linkages are detached at the time that the main program ends.

There is no other way to completely detach a linkage other than ending the main program.

===Present Library===

A present library is a library that is loaded to remain in memory as long as the main program is active or until all linkages that have been established for the library are reassigned.

Each library has its own global variables that are separate from the main program's variables. Global Variables in a present library are cleared when the main program ends.

A library can be loaded present through three different methods:

1.The first method is to specify a LIBRARY statement that identifies a library name but no function names. When this method is used, the library is loaded at the time that the LIBRARY statement is executed. For example, when the following statement is executed, the CURLIB library is immediately loaded into memory:

00210 LIBRARY "CURLIB":

2.The second method of loading a library present is to specify the LIBRARY statement with both a library name and function names. When this method is used, the library is loaded the first time one of the specified functions is called. In the following example, line 00210 establishes linkage between the function FNCURLIB1 and the library CURLIB.

Line 00220 causes the following to occur:

:1.) The library CURLIB is loaded as a present library,
:2.) The function FNCURLIB is executed.

00210 LIBRARY "CURLIB": FNCURLIB1
00220 LET FNCURLIB1

3.The third way to end up with a library loaded present is to execute a CLEAR STATUS command on a library that has already been loaded resident and has attached functions, thus turning it into a present library.

===Resident Library===

A resident library is a library program that is loaded to remain in memory, regardless of the status of the main program. It does not get removed from memory until it is explicitly cleared or until the Business Rules session is terminated. Loading a library resident saves the overhead associated with loading a library each time it is needed.

Each library has its own global variables that are separate from the main program's variables. Business Rules allows resident libraries to handle their own global variables in any of three different ways:

:1.) Globals may be cleared when the main program ends,
:2.) Globals may be retained irrespective of the status of the main program, or
:3.) Globals may be cleared after each function call to the resident library.

The resident status of a resident library can be removed (thus changing the library into a present library) through the use of the CLEAR STATUS command.

A library can be made resident through use of the enhanced LOAD command. However, it is important to understand that functions cannot be executed from any library -even a library that has been loaded into resident memory -until a LIBRARY statement names the functions to be executed and establishes linkage (either named or unnamed) between the named function and the resident library.

In the following example, line 00130 causes RESLIB to be loaded into memory as a resident library. Line 00140 establishes named linkage between the function FNRESLIB1 and the RESLIB library. Line 00150 executes the function FNRESLIB1.

00130 EXECUTE "LOAD RESLIB,RESIDENT"
00140 LIBRARY "RESLIB": FNRESLIB1
00150 LET FNRESLIB1

==Comparison of User-Defined Function Features==

The following table illustrates the similarities and differences between regular user-defined functions (non-library) and library user-defined functions.

[[Image:Lib1.jpg]] 
[[Image:Lib2.jpg]] 
[[Image:Lib3.jpg]]

==Variable Usage==

Before you start placing all your existing user-defined functions into separate libraries, you should fully understand how library functions deal with global variables.

This section will focus on three main points:

:1.) How a main program and a library function can communicate,
:2.) How functions within a library communicate, and
:3.) When global variables are cleared for a library program.

===How main programs and library functions communicate===

Business Rules programs communicate with regular user-defined functions via passed parameters, the returned function value, and global variables (variables not passed in the parameter list). All of these same communication options are available for library functions that are defined within the main program. However, only the first two options are available to library functions that are separate from the main program. These functions cannot access the main program's global variables because global variables are only available to routines and functions, which are defined within the same program. As a result, user-defined functions, which are held within a main program, may need to be reviewed for their global variable usage before they are changed to library functions and placed into a separate library program.

If a program needs to communicate a large number of standard values to a library function, consider using an initialization function to pass the values to the library program. Then have the initialization function assign the passed values to global variables in the library so they will be available to all functions in the library.

===How functions within a library communicate===
Within each library, all functions share variables which are global to that library, and library global variables generally retain their values between function calls. (The exception is when the RELEASE keyword is used on the LIBRARY statement, which is accepted both for resident and as-needed libraries; in this case, global variables are cleared after each function call.)

The point at which globals are cleared for a library program varies according to several factors. See below for more information.

===When global Variables are cleared===
The point at which a library's global variables are cleared depends on how the library was loaded and -in the case of resident libraries-what options are used.

{\b Main program library} - For library functions that are defined within the main program, globals are cleared when a new main program is started or when the current main program is explicitly removed from memory.

'''Resident library''' - When a library is loaded resident, global variables may be cleared in any of three ways:
{|
|-valign="top"
|width="10%"|'''Default'''||By default, Business Rules clears a resident library's global variables when the main program ends.
|-valign="top"
|width="10%"|'''Retain'''||When the OPTION RETAIN statement is used in a resident library program, the library retains its global variables irrespective of when the main program ends. The only way to clear globals when this statement is used is to CLEAR the library from memory or to reload it with the LOAD RESIDENT command. Remember that the library must be loaded resident for the OPTION RETAIN statement to have any affect.
|-valign="top"
|width="10%"|'''Release'''||When a resident library is named on a LIBRARY statement with the RELEASE keyword, the library's global variables are cleared after each function call to the library. This capability is provided so that the decision to load a library resident or as-needed can be made on a case-by-case basis; the program code can remain the same (because Business Rules handles the variables the same) regardless of whether the library is loaded resident or as-needed.
|-valign="top"
|}
 
{\b Present library} - When a library is loaded present, global variables are cleared when the main program ends.

{\b As-needed library} - When a library is loaded as-needed, global variables are cleared after each function call to the library.

The following table summarizes the information presented above. The keywords used in the "When globals are cleared" column are the same keywords used in the STATUS LIBRARY display (second column from right) to identify when variables for the listed library will be cleared. (See the "STATUS" command in the Commands chapter for complete information about this display.) The keywords are defined as follows:

{|
|-valign="top"
|width="10%"|'''RUN'''||Globals are cleared when new main program is run.
|-valign="top"
|width="10%"|'''END'''||Globals are cleared when main program ends.
|-valign="top"
|width="10%"|'''EXIT'''||Globals are cleared after each function call to the library.
|-valign="top"
|width="10%"|'''RETAIN'''||Globals are retained, irrespective of main program status.
|-valign="top"
|}
 
[[Image:Help0188.jpg]]

==Additional Processing Consideration==

Active procedures and opened files are not affected by library function calls, unless the library issues commands that specifically affect them. This includes PROCERR settings.

A nice aspect of library functions is the capability of a program to call a library function, which, in turn, calls a function in the main program. This supports the concept of manager functions that provide overall functionality while the main program fills in the details that may vary from program to program.

The way to permit library routines to be overridden (functionally replaced) by corresponding functions in the main program is to have the library include those functions in a LIBRARY statement that doesn't specify a library name. Then have the library execute that statement after the main program has started. The library will then attach the library function in the main program instead of its own, even if a copy of the function exists in the library, because the main program is always regarded as having been loaded last for purposes of resolving unnamed library searches.

Note that if a LIBRARY statement within a resident library creates linkage and then the main program ends, the linkage is broken and that LIBRARY statement must be re-executed before the function can be called again by the resident library.

With respect to speed, parameters should be passed by reference (using the & in front of the variable name in the DEF statement) wherever possible. This avoids needless allocation of memory and copying of data, which is a significant part of function call processing.

If you want to avoid the processing time required to load a library until a function within it is called, simply name the library and function on the same LIBRARY statement. However, if you want to be sure that the named functions exist within the library, first load the library with a statement that contains no function names. This will cause the library to be loaded at the time the LIBRARY statement is executed. Then when the LIBRARY statement containing the function list is encountered, the library (which is now in memory) will be checked for the presence of each function.

It should be emphasized that executing a LOAD command does not establish function linkage. A subsequent LIBRARY statement must be processed to establish such linkage.

When replacing a resident library with a different library, the first library should be cleared with a CLEAR command to free its memory before loading the second library.

Updating a library (with the REPLACE command) has no effect on application environments until the library is (re)loaded. 
If a LIBRARY statement contains the name of a local function that is defined as non-library, a "duplicate function definition" error is generated when the program is run or saved.

If a LIBRARY statement refers to a library without RELEASE and another statement refers to the same program with RELEASE, an error is generated. Also RELEASE cannot be specified for any library with the OPTION RETAIN statement.

If a function in the main program, defined with the LIBRARY keyword, is called from within a library (a condition referred to as library loopback), the main program uses a fresh for-next stack. 
Therefore, pre-existing for-next processes are not recognized until the library returns normally to the main program.

If more than one DEF LIBRARY statement for the same function name appears in a program, the lowest numbered definition will be used. More than one non-library DEF for the same variable is no longer permitted.

Memory fragmentation can occur if a library is loaded resident while other programs are in memory, and then the main program chains leaving files open through either the CHAIN FILES statement, or having files open NOCLOSE. To avoid this problem, if you use CHAIN FILES or NOCLOSE, load your resident libraries before running application programs.

Alternate libraries can be interrogated with function key 9 during a program pause.

===Editing Active Libraries===

When both a main program and a library program that is separate from the main program are active ( a function in the library program is currently being executed), the LIST command will display the contents of the library program. When functions in multiple library programs are active, the program with the most recently called function will be displayed.

It is important to note that the only way to save changes made to a library program that has been activated by a main program is to list the library to a file and reload it from source later on. Because of this, it makes sense to develop a new library function first within the main program. Then once you've completed the testing and debugging process, you can break it out and test it as a separate library function.

===Linkage===

When used to its full potential, the Business Rules Library Facility enables multiple versions of the same function (with the same name) to exist in different libraries, all of which may be loaded into memory. The actual library that is used for a specific function call is determined according to Business Rules rule for linkage, which is the process of associating a function name with a library name. 
Business Rules keeps tracks of established linkages in a table that it references each time a function is called.

The LIBRARY statement may be used to establish linkage in one of two ways: the named method, or the unnamed method. These methods are defined as follows:

;Named
The LIBRARY statement explicitly links one or more specific functions to a specific library. This is the most efficient and foolproof method for assuring that the library function you wish to use gets executed.

In the following example, the functions FNRESLIB1 through FNRESLIB5 are explicitly linked to the library MAIN. When any of these functions is called, Business Rules will automatically execute them from the MAIN library. (Regardless of whether or not any other library currently in memory also contains functions by the same name.)

50300 LIBRARY "MAIN":FNRESLIB1,FNRESLIB2,FNRESLIB3,FNRESLIB4,FNRESLIB5

;Unnamed
The LIBRARY statement names the desired library functions and leaves it to Business Rules to determine which of the currently identified libraries they should be linked to. This determination is made according to the pre-set guidelines described below. The unnamed method of linkage is useful when your development methodology involves using multiple versions of the same function to control program options and features.

When the unnamed method is used, Business Rules first searches the main program, then each library that is currently either resident or present (in last loaded, first searched order) for each function listed on the LIBRARY statement. Once Business Rules finds the function, the linkage is established, and -unless the linkage is explicitly changed with another LIBRARY statement or detached because the main program ends -all future calls to the same function will continue to utilize the same linkage. Note that Business Rules does not search as-needed libraries when the unnamed method of establishing linkage is used. Also, it is important to understand that it can take significantly longer to establish linkage using the unnamed method of linkage than with the named method of linkage.

In the following example, line 01000 loads RESLIB as a resident library. Lines 01100 and 01200 load PRESLIB1 and PRESLIB2 as present libraries, and line 01300 names ASNLIB as an as-needed library. The LIBRARY statement on line 01400 establishes unnamed linkage for the function FNALIBI. When line 01500 is executed, Business Rules searches the currently loaded programs in the following order for FNALIBI: Main program, PRESLI2, PRESLIB1, RESLIB. Note that ASNLIB is not considered for this search because it is not currently loaded in memory.

01000 EXECUTE "LOAD RESLIB,RESIDENT"
01100 LIBRARY "PRESLIB1":
01200 LIBRARY "PRESLIB2":
01300 LIBRARY RELEASE,"ASNLIB": FNASNLIB1
01400 LIBRARY : FNALIBI
01500 LET FNALIBI

===Status Library===

Business Rules STATUS LIBRARY command may be used to display a table that identifies all the linkages that are currently active for each library. See "STATUS" in the Commands chapter for more information. For information about releasing and/or changing library linkages, see the term Linkage reassignment and detachment below.

==Sample Program==

The following two sample sections of code are, for convenience purposes, labeled "Main Program" and "Library". The Main Program references two functions (FNSEND and FNRECEIVE), which are located in the Library. Line 50 of the Main Program establishes the function linkage; line 70 prompts for a message; and line 110 calls the FNSEND function, which is defined on line 30 of the Library.

FNSEND opens the communications port and sends the operator-specified message to the terminal connected to the port. The Main Program then calls the FNRECEIVE function, which is defined on line 80 of the Library. This function waits up to 15 seconds for a response (by default), returns the response in the parameter, and returns its length as a function value. Finally, the Main Program prints the response or the message "No Response".

;MAIN PROGRAM:

00010 ! MAIN PROGRAM
00020 !
00030 DIM MESG$*60, RESPONSE$*120
00040 !
00050 LIBRARY "TOOLS\LIB1": FNSEND, FNRECEIVE
00060 !
00070 PRINT "Specify Message"
00080 LINPUT MESG$
00090 IF LEN(MESG$) = 0 THEN STOP
00100 !
00110 LET FNSEND(MESG$)
00120 !
00130 IF FNRECEIVE(RESPONSE$) THEN !:PRINT RESPONSE$ !:ELSE !:PRINT "No Response"
00140 GOTO 70

Library:
00010 ! LIB1
00020 !
00030 DEF LIBRARY, FNSEND(MESSAGE$*60)
00040 IF NOT COMM OPENED THEN !:OPEN #40: "NAME=COM2:, FORMAT=ASYNC,BAUD=2400",DISPLAY, OUTIN !:COMM OPENED = 1
00050 PRINT #40: MESSAGES$
00060 FNEND
00070 !
00080 DEF LIBRARY FNRECEIVE(&RESP$)
00090 LINPUT #40: RESP$ IOERR 100
00100 FNRECEIVE = LEN(RESP$)
00110 FNEND

===Tips for implementing Library Functions in Existing Applications===

As mentioned above, it is important that you consider your current usage of global variables before converting your existing user-defined functions into library functions and placing them into a separate program. This section provides some examples of how you can modify existing applications to utilize library functions, even if the existing applications currently access or modify user-defined function variables from outside the function. Other examples shown in this section demonstrate how you can turn an entire program (such as a client maintenance program) into a library function that a user can invoke at will from within another program (such as order entry) and provide some tips on implementing libraries for programs that use [[FNSNAP]]! tools.

;Example 1:
Separating main program logic from user-defined functions 
The following is a very simple example of a program that uses a user-defined function.

;ORIGINAL PROGRAM:
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)
02000 DEF FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page, plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

The steps you would need to take to separate the function into a separate library and enable the main program to call the function would be as follows:

:1.) Place the user-defined functions into their own program.
:2.) Modify the DEF line for each of the functions in the new library program to utilize the LIBRARY keyword (demonstrated in line 02000 of the library program below).
:3.) Delete the separated functions from the main programs that are to use the new library.
:4.) Add a LIBRARY statement to the main program that names each function that is to be called from the library program (demonstrated in line 00005 of the main program below).

;MAIN PROGRAM:
00005 LIBRARY "howto1nl" : FNDOCEST
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)

;LIBRARY PROGRAM:
02000 DEF LIBRARY FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,lus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

;Example 2:
Function uses global variables established by main program

In the following program, the global variable PAGEEST is established by the main program logic on line 00020. This same global variable is accessed by the user-defined function at line 02010.

;MAIN PROGRAM:
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST

;LIBRARY PROGRAM:
02000 DEF FNDOCEST
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

As there is no way for a main program to share its global variables with a library function contained in a separate program, this program must be modified before it can be separated into "main" and "library" programs. In the following example, line 02000 has been modified (as shown in italics) to pass the PAGEEST variable by reference, thereby causing the library function to use the main program's copy of the variable.

;MAIN PROGRAM:
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)

;LIBRARY PROGRAM:
02000 DEF FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

;Example 3:
Existing program queries function variable from outside function 
This example shows the same starting program as shown in Example 1, except that line 00040 has been added to demonstrate a situation where the main program logic queries (without changing) a variable that has been established by the user-defined function. This programming technique also is not allowed when functions are separated into library programs,
as there is just one way (via the function variable) for a separate library function to pass a value back to the main program.

;MAIN PROGRAM:
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST
00040 IF WRITETIME>8 THEN PRINT "Total days: ";WRITETIME/8

;LIBRARY PROGRAM:
02000 DEF FNDOCEST
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

When starting new programming projects that are to utilize Business Rules Libraries, ADS recommends against the programming technique shown here. However, if your programs already use this technique and you want to utilize the benefits of libraries with as little work as possible, you could change the programs in the manner shown below.

The following two code sections show the original program as it would be when split into main program and library, and with a "rigged" technique for the program to get the value of the queried variable from the library. The "rig" is that all references to the WRITETIME variable in the main logic have been changed to FNWRITETIME, and FNWRITETIME has been added to the library to query the value of WRITETIME and pass it back to the main program. Note that there is a limitation to this technique: the program must be loaded into either resident memory (without use of RELEASE on the LIBRARY statement) or present memory for it to work. This is because the technique relies on the library's global variables remaining active even after function calls to it have been completed.

;MAIN PROGRAM:
00005 LIBRARY "howto2nl" : FNDOCEST,FNWRITETIME
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)
00040 IF FNWRITETIME>8 THEN PRINT "Total days: ";FNWRITETIME/8

;LIBRARY:
02000 DEF LIBRARY FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page, plus 15% for index
02020 PRINT "Documentation estimate is:";WRITETIME;"hours"
02030 FNEND
03000 DEF LIBRARY FNWRITETIME=WRITETIME

;Example 4:
Existing program queries or modifies function variable from outside function 
In the following example, line 00120 of the main program logic modifies the value of TOTTIME, which is established by the FNDOCEST function. It is important that this modified value be communicated back to the function, because line 02030 of the function uses it for subsequent calls. Note also that lines 00100 and 00130 of the main program logic also query (without modifying) the value of TOTTIME.

;MAIN PROGRAM:
00010 PRINT "Enter estimated number of pages for chapter 1:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)
00040 PRINT "Enter estimated number of pages for chapter 2:"
00050 INPUT PAGEEST
00060 PRINT "Is subject matter highly technical? (Y/N)"
00070 INPUT TECHLEVEL$
00080 LET FNDOCEST(PAGEEST)
00090 IF UPRC$(TECHLEVEL$)="Y" THEN
00100 LET SURPLUS=TOTTIME*.2
00110 PRINT "Surplus time for technical matter: ";SURPLUS;"hours"
00120 LET TOTTIME+=SURPLUS
00130 PRINT "Total time is ";TOTTIME;"hours"
00140 END IF

;LIBRARY:
02000 DEF FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 PRINT "Accumulated total is: ";TOTTIME+=WRITETIME;"hours"
02040 FNEND

As noted for the previous example in this section, programming practices such as this are not recommended for new development that is to utilize the Library Facility. These examples are supplied to help you quickly modify existing programs so they can utilize the benefits of libraries.

The next two programs (main and library) show how the original program was changed to work with libraries.

;MAIN PROGRAM:
00005 LIBRARY "HOWTO3NL" : FNDOCEST,FNADD TOTTIME
00010 PRINT "Enter estimated number of pages for chapter 1:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)
00040 PRINT "Enter estimated number of pages for chapter 2:"
00050 INPUT PAGEEST
00060 PRINT "Is subject matter highly technical? (Y/N)"
00070 INPUT TECHLEVEL$
00080 LET FNDOCEST(PAGEEST)
00090 IF UPRC$(TECHLEVEL$)="Y" THEN
00100 LET SURPLUS=FNADD TOTTIME(0)*.2
00110 PRINT "Surplus time for technical matter: ";SURPLUS;"hours"
00130 PRINT "Total time is ";FNADD TOTTIME(SURPLUS);"hours"
00140 END IF

;LIBRARY PROGRAM:
02000 DEF LIBRARY FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 PRINT "Accumulated total is: ";TOTTIME+=WRITETIME;"hours"
02040 FNEND
03000 DEF LIBRARY
FNADD TOTTIME(ADDTOTTIME)=TOTTIME+=ADDTOTTIME

Once the required steps of separating the two programs, adding the necessary LIBRARY statement to the main program and adding the LIBRARY keyword to the DEF statement in the library program were completed for the above code, the following steps were conducted to enable the main program and function to communicate the value of TOTTIME. Note that there is a limitation to the technique shown: the library program must be loaded into either resident memory (without use of RELEASE on the LIBRARY statement) or present memory for it to work. This is because it relies on the library's global variables remaining active even after function calls to it have been completed.

:1.) The FNADD TOTTIME function was added to the library program (line 03000). This function takes a variable (representing the amount to add to TOTTIME) that is passed by the main program. It adds the passed variable to TOTTIME, and also assigns the new value of TOTTIME to the function variable FNADD TOTTIME.
:2.) The FNADD TOTTIME function name was added to the LIBRARY statement on line 00005 of the main program.
:3.) Line 00120 of the main program was removed, and line 00130 was modified to call the FNADD TOTTIME library function instead of modifying TOTTIME directly. The value of SURPLUS is passed to FNADD TOTTIME; FNADD TOTTIME takes over the job of modifying the value of TOTTIME and making sure that both the main program and the library program know its new value.
:4.) Line 00100 of the main program was changed to call the FNADD TOTTIME function as well. Since this line only needs to query the value of TOTTIME, it passes a value of 0 as the amount to add to TOTTIME.

;Example 5:
Turning an existing program into a user-invokable library function 
Business Rules Library Facility makes it very easy to turn an entire program into a library function that a user can invoke at will from within another program. For example, consider a standard application that includes both a client maintenance (MNTCUST) program and an order entry program (ORDERS). You would like to give users the ability to invoke the client maintenance program from within the order entry program whenever they press F4. The steps required to do this are as follows:

:1.) Modify MNTCUST by placing the entire original program into a user-defined library function and adding a few lines that cause the program to call itself as a library function whenever it is executed as the main program.
:a.) Move any user-defined functions that exist within the main body of the program to the end of the program (or to a separate library).
:b.) Add lines such as the following to the top of the program. NOTE that the (program name) in line 00030 represents the name of the program (such as a main menu) from which you currently normally invoke the client maintenance program.

00010 LIBRARY "MNTCUST" : FNMNTCUST
00020 LET FNMNTCUST
00030 CHAIN (program name)
00040 DEF LIBRARY FNMNTCUST

:c.) Add the following line to the end of the main body of the program (prior to any user-defined function definitions):

80000 FNEND

:2.) Modify ORDERS as follows:

:a.) Change the screen to include a label that identifies the operation of the F4 key.
:b.) Change the program to check for pressing of the F4 key.
:c.) Change the program to execute the following whenever F4 is pressed. Note that the LIBRARY statement in line 50000 utilizes the "RELEASE" keyword: this causes the MNTCUST library to be loaded into memory on an as-needed basis only. Thus the only time that the on-the-fly client maintenance feature uses system resources is when the user actually requests the capability by pressing F4.

50000 LIBRARY RELEASE, "MNTCUST" :FNMNTCUST
50010 LET FNMNTCUST

;Example 6:
Tips for moving [[FNSNAP]]! functions into separate libraries for users of [[FNSNAP]]! programming tools, modifying existing programs to use libraries will involve a combination of the techniques demonstrated above. Every developers programs are different, so this section cannot give you a beginning-to-end list of steps to complete to accomplish the task, but the following are some steps you can start with:

:1.) Place the FNSNAP! functions into their own program. (This example uses MAIN\\FNSNAP as the path and location of the new program.)
:2.) Modify the DEF line for each of the functions in FNSNAP to utilize the LIBRARY keyword. For example:

Change this:

60150 DEF FNOK

To this:

60150 DEF LIBRARY FNOK

:3.) Add the following FNFNSNAP INIT function to the FNSNAP program. This function sets all the global variables that are used by the FNSNAP functions (in the past, FNSNAP! users were instructed to add these variable settings to the start of their programs). FNFNSNAP INIT also executes a LIBRARY statement for the FNSNAP program. This LIBRARY statement establishes linkage for all the functions in the FNSNAP program that are called by other functions in the same program.

00121 DEF LIBRARY FNFNSNAP INIT
00122 LET DATFMT$="MM-DD-CCYY" !:LET FULLSCR=0 !:LET MAXSROWS=22 !:LET WINDEV=OWINDEV=69 !:LET MGA$="24,2,C 78," !:IF NOT SSAV THEN LET SSAV=101 !:!Common Variables required by FNSNAP! !:
00124 LIBRARY "MAIN\FNSNAP" : FNRELPART,FNSAVPART, FNPM, FNAUTO, FNOK, FNWIN,FNCLSWIN, FNZERO, FNTIMMILREG, FNSSAV,FNSAVSCR, FNSETBAD, FNPURGE, FNFLDSEL$
00130 FNEND !:
:4.) Delete the separated functions from the main programs that are to use the FNSNAP library.

:5.) Add the following program line to each of the main programs that are to use the FNSNAP library. This statement establishes linkage between the functions to be called and the program they are located in, and it calls the FNFNSNAP INIT function, which sets the library's global values:

00160 LIBRARY "MAIN\FNSNAP":FNFNSNAP INIT, FNSSAV, FNPOPWIN,FNPOPBAR, FNWINDEV, FNPOPWIN INIT,FNPOPBAR INIT, FNCO$, FNMGCLR, FNTOP,FNOK, FNSAVSCR, FNSCRMGR, FNSAVPART,FNRELPART, FNCLRPART, FNZERO, FNNULL$,FNTIMMILREG, FNDIALOG$, FNWIN, FNCLSWIN,FNNOKEY, FNPOPUP, FNPM, FNAUTO,FNPFKEYLINE !:LET FNFNSNAP INIT !:!

==Error Processing==

If an error is not trapped in a library function, the error is reported back to the calling program. At this time the following system variables are set:

{|
|-valign="top"
|width="10%"|'''LINE'''||The line number of the calling program function call.
|-valign="top"
|width="10%"|'''ERR'''||The error number that occurred in the library function.
|-valign="top"
|width="10%"|'''CNT'''||The appropriate value as if the error occurred in the calling program.
|-valign="top"
|}
 
If an error occurs while attempting to match parameters between a function call and the function definition, CNT is set to the number of parameters successfully matched.

<noinclude>
[[Category:User Defined Functions and Libraries]]
[[Category:Facility]]
</noinclude>

Library Facility

2013-04-15T19:29:36Z

66.17.154.248: /* Present Library */

[[Business Rules!]] now includes a comprehensive '''Library''' Facility. Similar to [[DLL]] (Dynamic Link Libraries), the Business Rules! Library Facility enables [[user-defined functions]] to be placed in a program ("library") that is separate from the main program. The library may be loaded "resident" (staying loaded regardless of the status of the main program), it may be loaded "present" (remaining active in current memory as long as the main program is active), or it may be loaded "as needed" (loaded when needed to execute a function, then unloaded as soon as the function has been executed).

A library is any [[Business Rules! program]] that contains library functions. A library must be identified to Business Rules! before a program can execute any of its functions. When a library is identified, Business Rules! adds its name to an internal table of library names. This table identifies the names of all the libraries that should be searched whenever a library function that is not yet linked to a library is called.

Business Rules! places no limits on the number of libraries that may be loaded into memory at one time. Business Rules! provides for maximum memory usage and performance flexibility by allowing libraries to be identified and loaded into memory via three different methods: the resident method, the present method and the as-needed method. See the separate descriptions below for specific information about each type of library.

==Advantages==

Some of the significant advantages of placing user-defined functions in a library rather than keeping them in the main program are as follows:

:1.) Reduces the size of executables - its no longer necessary to include a standard set of user-defined functions in every program in your application. For some applications (which may include literally hundreds of copies of the exact same code), the potential savings in disk space are tremendous.

:2.) Saves maintenance time - If you're in the habit of duplicating user-defined functions in every single program that needs them, you know what kind of effort it takes to make (and distribute to your clients) even a one-line change to a function. With Business Rules Library Facility, you make the change only once, and you replace only one program at the client's site.

:3.) Encourages use of programming standards - The use of library functions for a standard routine is a great way to encourage programming consistency and the setting of standards among your programmers.

==Library Function==

A '''library function''' is a specially defined [[user-defined function]]; it exists in a program which is frequently separate from the main program, but it may exist in the main program as well.

To qualify as a library function, a user-defined function must simply utilize the DEF statement's LIBRARY keyword. The following is an example of a library function definition:

52400 DEF LIBRARY FNRESLIB2
52500 PRINT "This is a library function"
52600 FNEND

Executing a library function is a two-step process. First, the program executing the library function must name the function in a LIBRARY statement, which establishes either named or unnamed linkage. Second, the program must call the library function; this may be accomplished using any of the same methods that is available for calling other user-defined functions. In the following example, line 01000 uses the LIBRARY statement to establish named linkage between the function FNPRESLIB2 and the library PRESLIB. Line 01100 causes the library PRESLIB to be loaded into present memory (if the library does not already exist in memory), then executes FNPRESLIB2.

01000 LIBRARY "PRESLIB": FNPRESLIB2
01100 LET FNPRESLIB2

===Implementation Considerations===

Business Rules Facility was carefully designed to offer a great deal of power and flexibility. Before you begin implementing this capability into your existing applications and ongoing development, ADS recommends that you consider the following:

:1.) Should your libraries remain resident?
Business Rules allows for libraries to remain resident in memory (providing maximum performance) or to be loaded and released as needed (providing best utilization of memory). Be sure to select the method or combination of methods that's best for your applications.

:2.) Will you use multiple versions of the same function?
Since maintaining more than one version of a function is one method of controlling program options, Business Rules' rule for library selection has been established with care. You should carefully review these rules and the ways in which multiple libraries can be of use to you as you plan your implementation.

Until you feel comfortable with the intricacies of the Business Rules Library Facility, ADS recommends that you give every library function a name that is unique from every other library function.

:3.) Do your existing functions utilize global program variables?
Unlike local user-defined functions, library functions that exist in a program separate from the main program cannot access main program variables globally. They have to be specifically passed. You should carefully review your usage of global variables before moving local functions into separate libraries.

===As needed Library===

An as-needed library is loaded and unloaded as needed for execution of specific functions. Loading a library only when it is needed allows the program to conserve memory usage.

Each library has its own global variables that are separate from the main program's variables. Global Variables in an as-needed library are cleared each time a function call to the library is completed and the library is subsequently unloaded from memory.

Programs can indicate that a library is to be loaded as needed by specifying the LIBRARY statement with both the RELEASE parameter and function names. This causes Business Rules to establish named linkage between the specified function(s) and the specified library, but it does not actually load the library. (The library is loaded only when one of the as-needed library's functions is actually called.) In the following example, line 00280 establishes linkage between the library ASNLIB and the function FNASNLIB1. Line 00290 causes the following to occur:

:1.) Load ASNLIB into memory,
:2.) Execute the function FNASNLIB1,
:3.) Remove ASNLIB from memory.

00280 LIBRARY RELEASE,"ASNLIB": FNASNLIB1
00290 LET FNASNLIB1

===Linkage Reassignment and Detachment===

Once Business Rules has established linkage between a specific function and a specific library, the linkage remains active until a specific event causes it to become reassigned or detached.

;REASSIGNMENT:
As noted previously, the LIBRARY statement may be used to establish linkage between a function and the library from which it is to be called. When the named LIBRARY statement is used, linkage is directly established between the named library and the named function(s). When the unnamed LIBRARY statement is used, Business Rules searches for the function according to some pre-set guidelines and assigns linkage to the first library within which the function definition is found.

Once a function has actually been linked to a library, the only way to subsequently establish linkage between the same function name and a different library is to execute another LIBRARY statement that names the same function and a different library. When all of a present library's linked functions are reassigned; the library is automatically removed from memory. When all of a resident library's linked functions are reassigned; the library may be removed from memory with the CLEAR command.

In the following example, lines 01100 and 01200 load the libraries PRESLIB1 and PRESLIB2 into present memory. Line 01300 uses a named library statement to establish linkage between PRESLIB1 and the function FNASSIGN, and line 01400 actually executes FNASSIGN from the PRESLIB1 library. Line 1500 then re-assigns linkage of FNASSIGN to the library PRESLIB2, and line 1600 executes FNASSIGN from the PRESLIB2 library.

01100 LIBRARY "PRESLIB1":
01200 LIBRARY "PRESLIB2":
01300 LIBRARY "PRESLIB1": FNASSIGN
01400 LET FNASSIGN
01500 LIBRARY "PRESLIB2": FNASSIGN
01600 LET FNASSIGN

;DETACHMENT:
Regardless of how a library is loaded (resident, present or as needed), all linkages are detached at the time that the main program ends.

There is no other way to completely detach a linkage other than ending the main program.

===Present Library===

A present library is a library that is loaded to remain in memory as long as the main program is active or until all linkages that have been established for the library are reassigned.

Each library has its own global variables that are separate from the main program's variables. Global Variables in a present library are cleared when the main program ends.

A library can be loaded present through three different methods:

1.The first method is to specify a LIBRARY statement that identifies a library name but no function names. When this method is used, the library is loaded at the time that the LIBRARY statement is executed. For example, when the following statement is executed, the CURLIB library is immediately loaded into memory:

00210 LIBRARY "CURLIB":

2.The second method of loading a library present is to specify the LIBRARY statement with both a library name and function names. When this method is used, the library is loaded the first time one of the specified functions is called. In the following example, line 00210 establishes linkage between the function FNCURLIB1 and the library CURLIB.

Line 00220 causes the following to occur:

:1.) The library CURLIB is loaded as a present library,
:2.) The function FNCURLIB is executed.

00210 LIBRARY "CURLIB": FNCURLIB1
00220 LET FNCURLIB1

3.The third way to end up with a library loaded present is to execute a CLEAR STATUS command on a library that has already been loaded resident and has attached functions, thus turning it into a present library.

===Resident Library===

A resident library is a library program that is loaded to remain in memory, regardless of the status of the main program. It does not get removed from memory until it is explicitly cleared or until the Business Rules session is terminated. Loading a library resident saves the overhead associated with loading a library each time it is needed.

Each library has its own global variables that are separate from the main program's variables. Business Rules allows resident libraries to handle their own global variables in any of three different ways:

:1.) Globals may be cleared when the main program ends,
:2.) Globals may be retained irrespective of the status of the main program, or
:3.) Globals may be cleared after each function call to the resident library.

The resident status of a resident library can be removed (thus changing the library into a present library) through the use of the CLEAR STATUS command.

A library can be made resident through use of the enhanced LOAD command. However, it is important to understand that functions cannot be executed from any library -even a library that has been loaded into resident memory -until a LIBRARY statement names the functions to be executed and establishes linkage (either named or unnamed) between the named function and the resident library.

In the following example, line 00130 causes RESLIB to be loaded into memory as a resident library. Line 00140 establishes named linkage between the function FNRESLIB1 and the RESLIB library. Line 00150 executes the function FNRESLIB1.

00130 EXECUTE "LOAD RESLIB,RESIDENT"
00140 LIBRARY "RESLIB": FNRESLIB1
00150 LET FNRESLIB1

==Comparison of User-Defined Function Features==

The following table illustrates the similarities and differences between regular user-defined functions (non-library) and library user-defined functions.

[[Image:Help0185.jpg]] 
[[Image:Help0186.jpg]] 
[[Image:Help0187.jpg]]

==Variable Usage==

Before you start placing all your existing user-defined functions into separate libraries, you should fully understand how library functions deal with global variables.

This section will focus on three main points:

:1.) How a main program and a library function can communicate,
:2.) How functions within a library communicate, and
:3.) When global variables are cleared for a library program.

===How main programs and library functions communicate===

Business Rules programs communicate with regular user-defined functions via passed parameters, the returned function value, and global variables (variables not passed in the parameter list). All of these same communication options are available for library functions that are defined within the main program. However, only the first two options are available to library functions that are separate from the main program. These functions cannot access the main program's global variables because global variables are only available to routines and functions, which are defined within the same program. As a result, user-defined functions, which are held within a main program, may need to be reviewed for their global variable usage before they are changed to library functions and placed into a separate library program.

If a program needs to communicate a large number of standard values to a library function, consider using an initialization function to pass the values to the library program. Then have the initialization function assign the passed values to global variables in the library so they will be available to all functions in the library.

===How functions within a library communicate===
Within each library, all functions share variables which are global to that library, and library global variables generally retain their values between function calls. (The exception is when the RELEASE keyword is used on the LIBRARY statement, which is accepted both for resident and as-needed libraries; in this case, global variables are cleared after each function call.)

The point at which globals are cleared for a library program varies according to several factors. See below for more information.

===When global Variables are cleared===
The point at which a library's global variables are cleared depends on how the library was loaded and -in the case of resident libraries-what options are used.

{\b Main program library} - For library functions that are defined within the main program, globals are cleared when a new main program is started or when the current main program is explicitly removed from memory.

'''Resident library''' - When a library is loaded resident, global variables may be cleared in any of three ways:
{|
|-valign="top"
|width="10%"|'''Default'''||By default, Business Rules clears a resident library's global variables when the main program ends.
|-valign="top"
|width="10%"|'''Retain'''||When the OPTION RETAIN statement is used in a resident library program, the library retains its global variables irrespective of when the main program ends. The only way to clear globals when this statement is used is to CLEAR the library from memory or to reload it with the LOAD RESIDENT command. Remember that the library must be loaded resident for the OPTION RETAIN statement to have any affect.
|-valign="top"
|width="10%"|'''Release'''||When a resident library is named on a LIBRARY statement with the RELEASE keyword, the library's global variables are cleared after each function call to the library. This capability is provided so that the decision to load a library resident or as-needed can be made on a case-by-case basis; the program code can remain the same (because Business Rules handles the variables the same) regardless of whether the library is loaded resident or as-needed.
|-valign="top"
|}
 
{\b Present library} - When a library is loaded present, global variables are cleared when the main program ends.

{\b As-needed library} - When a library is loaded as-needed, global variables are cleared after each function call to the library.

The following table summarizes the information presented above. The keywords used in the "When globals are cleared" column are the same keywords used in the STATUS LIBRARY display (second column from right) to identify when variables for the listed library will be cleared. (See the "STATUS" command in the Commands chapter for complete information about this display.) The keywords are defined as follows:

{|
|-valign="top"
|width="10%"|'''RUN'''||Globals are cleared when new main program is run.
|-valign="top"
|width="10%"|'''END'''||Globals are cleared when main program ends.
|-valign="top"
|width="10%"|'''EXIT'''||Globals are cleared after each function call to the library.
|-valign="top"
|width="10%"|'''RETAIN'''||Globals are retained, irrespective of main program status.
|-valign="top"
|}
 
[[Image:Help0188.jpg]]

==Additional Processing Consideration==

Active procedures and opened files are not affected by library function calls, unless the library issues commands that specifically affect them. This includes PROCERR settings.

A nice aspect of library functions is the capability of a program to call a library function, which, in turn, calls a function in the main program. This supports the concept of manager functions that provide overall functionality while the main program fills in the details that may vary from program to program.

The way to permit library routines to be overridden (functionally replaced) by corresponding functions in the main program is to have the library include those functions in a LIBRARY statement that doesn't specify a library name. Then have the library execute that statement after the main program has started. The library will then attach the library function in the main program instead of its own, even if a copy of the function exists in the library, because the main program is always regarded as having been loaded last for purposes of resolving unnamed library searches.

Note that if a LIBRARY statement within a resident library creates linkage and then the main program ends, the linkage is broken and that LIBRARY statement must be re-executed before the function can be called again by the resident library.

With respect to speed, parameters should be passed by reference (using the & in front of the variable name in the DEF statement) wherever possible. This avoids needless allocation of memory and copying of data, which is a significant part of function call processing.

If you want to avoid the processing time required to load a library until a function within it is called, simply name the library and function on the same LIBRARY statement. However, if you want to be sure that the named functions exist within the library, first load the library with a statement that contains no function names. This will cause the library to be loaded at the time the LIBRARY statement is executed. Then when the LIBRARY statement containing the function list is encountered, the library (which is now in memory) will be checked for the presence of each function.

It should be emphasized that executing a LOAD command does not establish function linkage. A subsequent LIBRARY statement must be processed to establish such linkage.

When replacing a resident library with a different library, the first library should be cleared with a CLEAR command to free its memory before loading the second library.

Updating a library (with the REPLACE command) has no effect on application environments until the library is (re)loaded. 
If a LIBRARY statement contains the name of a local function that is defined as non-library, a "duplicate function definition" error is generated when the program is run or saved.

If a LIBRARY statement refers to a library without RELEASE and another statement refers to the same program with RELEASE, an error is generated. Also RELEASE cannot be specified for any library with the OPTION RETAIN statement.

If a function in the main program, defined with the LIBRARY keyword, is called from within a library (a condition referred to as library loopback), the main program uses a fresh for-next stack. 
Therefore, pre-existing for-next processes are not recognized until the library returns normally to the main program.

If more than one DEF LIBRARY statement for the same function name appears in a program, the lowest numbered definition will be used. More than one non-library DEF for the same variable is no longer permitted.

Memory fragmentation can occur if a library is loaded resident while other programs are in memory, and then the main program chains leaving files open through either the CHAIN FILES statement, or having files open NOCLOSE. To avoid this problem, if you use CHAIN FILES or NOCLOSE, load your resident libraries before running application programs.

Alternate libraries can be interrogated with function key 9 during a program pause.

===Editing Active Libraries===

When both a main program and a library program that is separate from the main program are active ( a function in the library program is currently being executed), the LIST command will display the contents of the library program. When functions in multiple library programs are active, the program with the most recently called function will be displayed.

It is important to note that the only way to save changes made to a library program that has been activated by a main program is to list the library to a file and reload it from source later on. Because of this, it makes sense to develop a new library function first within the main program. Then once you've completed the testing and debugging process, you can break it out and test it as a separate library function.

===Linkage===

When used to its full potential, the Business Rules Library Facility enables multiple versions of the same function (with the same name) to exist in different libraries, all of which may be loaded into memory. The actual library that is used for a specific function call is determined according to Business Rules rule for linkage, which is the process of associating a function name with a library name. 
Business Rules keeps tracks of established linkages in a table that it references each time a function is called.

The LIBRARY statement may be used to establish linkage in one of two ways: the named method, or the unnamed method. These methods are defined as follows:

;Named
The LIBRARY statement explicitly links one or more specific functions to a specific library. This is the most efficient and foolproof method for assuring that the library function you wish to use gets executed.

In the following example, the functions FNRESLIB1 through FNRESLIB5 are explicitly linked to the library MAIN. When any of these functions is called, Business Rules will automatically execute them from the MAIN library. (Regardless of whether or not any other library currently in memory also contains functions by the same name.)

50300 LIBRARY "MAIN":FNRESLIB1,FNRESLIB2,FNRESLIB3,FNRESLIB4,FNRESLIB5

;Unnamed
The LIBRARY statement names the desired library functions and leaves it to Business Rules to determine which of the currently identified libraries they should be linked to. This determination is made according to the pre-set guidelines described below. The unnamed method of linkage is useful when your development methodology involves using multiple versions of the same function to control program options and features.

When the unnamed method is used, Business Rules first searches the main program, then each library that is currently either resident or present (in last loaded, first searched order) for each function listed on the LIBRARY statement. Once Business Rules finds the function, the linkage is established, and -unless the linkage is explicitly changed with another LIBRARY statement or detached because the main program ends -all future calls to the same function will continue to utilize the same linkage. Note that Business Rules does not search as-needed libraries when the unnamed method of establishing linkage is used. Also, it is important to understand that it can take significantly longer to establish linkage using the unnamed method of linkage than with the named method of linkage.

In the following example, line 01000 loads RESLIB as a resident library. Lines 01100 and 01200 load PRESLIB1 and PRESLIB2 as present libraries, and line 01300 names ASNLIB as an as-needed library. The LIBRARY statement on line 01400 establishes unnamed linkage for the function FNALIBI. When line 01500 is executed, Business Rules searches the currently loaded programs in the following order for FNALIBI: Main program, PRESLI2, PRESLIB1, RESLIB. Note that ASNLIB is not considered for this search because it is not currently loaded in memory.

01000 EXECUTE "LOAD RESLIB,RESIDENT"
01100 LIBRARY "PRESLIB1":
01200 LIBRARY "PRESLIB2":
01300 LIBRARY RELEASE,"ASNLIB": FNASNLIB1
01400 LIBRARY : FNALIBI
01500 LET FNALIBI

===Status Library===

Business Rules STATUS LIBRARY command may be used to display a table that identifies all the linkages that are currently active for each library. See "STATUS" in the Commands chapter for more information. For information about releasing and/or changing library linkages, see the term Linkage reassignment and detachment below.

==Sample Program==

The following two sample sections of code are, for convenience purposes, labeled "Main Program" and "Library". The Main Program references two functions (FNSEND and FNRECEIVE), which are located in the Library. Line 50 of the Main Program establishes the function linkage; line 70 prompts for a message; and line 110 calls the FNSEND function, which is defined on line 30 of the Library.

FNSEND opens the communications port and sends the operator-specified message to the terminal connected to the port. The Main Program then calls the FNRECEIVE function, which is defined on line 80 of the Library. This function waits up to 15 seconds for a response (by default), returns the response in the parameter, and returns its length as a function value. Finally, the Main Program prints the response or the message "No Response".

;MAIN PROGRAM:

00010 ! MAIN PROGRAM
00020 !
00030 DIM MESG$*60, RESPONSE$*120
00040 !
00050 LIBRARY "TOOLS\LIB1": FNSEND, FNRECEIVE
00060 !
00070 PRINT "Specify Message"
00080 LINPUT MESG$
00090 IF LEN(MESG$) = 0 THEN STOP
00100 !
00110 LET FNSEND(MESG$)
00120 !
00130 IF FNRECEIVE(RESPONSE$) THEN !:PRINT RESPONSE$ !:ELSE !:PRINT "No Response"
00140 GOTO 70

Library:
00010 ! LIB1
00020 !
00030 DEF LIBRARY, FNSEND(MESSAGE$*60)
00040 IF NOT COMM OPENED THEN !:OPEN #40: "NAME=COM2:, FORMAT=ASYNC,BAUD=2400",DISPLAY, OUTIN !:COMM OPENED = 1
00050 PRINT #40: MESSAGES$
00060 FNEND
00070 !
00080 DEF LIBRARY FNRECEIVE(&RESP$)
00090 LINPUT #40: RESP$ IOERR 100
00100 FNRECEIVE = LEN(RESP$)
00110 FNEND

===Tips for implementing Library Functions in Existing Applications===

As mentioned above, it is important that you consider your current usage of global variables before converting your existing user-defined functions into library functions and placing them into a separate program. This section provides some examples of how you can modify existing applications to utilize library functions, even if the existing applications currently access or modify user-defined function variables from outside the function. Other examples shown in this section demonstrate how you can turn an entire program (such as a client maintenance program) into a library function that a user can invoke at will from within another program (such as order entry) and provide some tips on implementing libraries for programs that use [[FNSNAP]]! tools.

;Example 1:
Separating main program logic from user-defined functions 
The following is a very simple example of a program that uses a user-defined function.

;ORIGINAL PROGRAM:
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)
02000 DEF FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page, plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

The steps you would need to take to separate the function into a separate library and enable the main program to call the function would be as follows:

:1.) Place the user-defined functions into their own program.
:2.) Modify the DEF line for each of the functions in the new library program to utilize the LIBRARY keyword (demonstrated in line 02000 of the library program below).
:3.) Delete the separated functions from the main programs that are to use the new library.
:4.) Add a LIBRARY statement to the main program that names each function that is to be called from the library program (demonstrated in line 00005 of the main program below).

;MAIN PROGRAM:
00005 LIBRARY "howto1nl" : FNDOCEST
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)

;LIBRARY PROGRAM:
02000 DEF LIBRARY FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,lus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

;Example 2:
Function uses global variables established by main program

In the following program, the global variable PAGEEST is established by the main program logic on line 00020. This same global variable is accessed by the user-defined function at line 02010.

;MAIN PROGRAM:
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST

;LIBRARY PROGRAM:
02000 DEF FNDOCEST
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

As there is no way for a main program to share its global variables with a library function contained in a separate program, this program must be modified before it can be separated into "main" and "library" programs. In the following example, line 02000 has been modified (as shown in italics) to pass the PAGEEST variable by reference, thereby causing the library function to use the main program's copy of the variable.

;MAIN PROGRAM:
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)

;LIBRARY PROGRAM:
02000 DEF FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

;Example 3:
Existing program queries function variable from outside function 
This example shows the same starting program as shown in Example 1, except that line 00040 has been added to demonstrate a situation where the main program logic queries (without changing) a variable that has been established by the user-defined function. This programming technique also is not allowed when functions are separated into library programs,
as there is just one way (via the function variable) for a separate library function to pass a value back to the main program.

;MAIN PROGRAM:
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST
00040 IF WRITETIME>8 THEN PRINT "Total days: ";WRITETIME/8

;LIBRARY PROGRAM:
02000 DEF FNDOCEST
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

When starting new programming projects that are to utilize Business Rules Libraries, ADS recommends against the programming technique shown here. However, if your programs already use this technique and you want to utilize the benefits of libraries with as little work as possible, you could change the programs in the manner shown below.

The following two code sections show the original program as it would be when split into main program and library, and with a "rigged" technique for the program to get the value of the queried variable from the library. The "rig" is that all references to the WRITETIME variable in the main logic have been changed to FNWRITETIME, and FNWRITETIME has been added to the library to query the value of WRITETIME and pass it back to the main program. Note that there is a limitation to this technique: the program must be loaded into either resident memory (without use of RELEASE on the LIBRARY statement) or present memory for it to work. This is because the technique relies on the library's global variables remaining active even after function calls to it have been completed.

;MAIN PROGRAM:
00005 LIBRARY "howto2nl" : FNDOCEST,FNWRITETIME
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)
00040 IF FNWRITETIME>8 THEN PRINT "Total days: ";FNWRITETIME/8

;LIBRARY:
02000 DEF LIBRARY FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page, plus 15% for index
02020 PRINT "Documentation estimate is:";WRITETIME;"hours"
02030 FNEND
03000 DEF LIBRARY FNWRITETIME=WRITETIME

;Example 4:
Existing program queries or modifies function variable from outside function 
In the following example, line 00120 of the main program logic modifies the value of TOTTIME, which is established by the FNDOCEST function. It is important that this modified value be communicated back to the function, because line 02030 of the function uses it for subsequent calls. Note also that lines 00100 and 00130 of the main program logic also query (without modifying) the value of TOTTIME.

;MAIN PROGRAM:
00010 PRINT "Enter estimated number of pages for chapter 1:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)
00040 PRINT "Enter estimated number of pages for chapter 2:"
00050 INPUT PAGEEST
00060 PRINT "Is subject matter highly technical? (Y/N)"
00070 INPUT TECHLEVEL$
00080 LET FNDOCEST(PAGEEST)
00090 IF UPRC$(TECHLEVEL$)="Y" THEN
00100 LET SURPLUS=TOTTIME*.2
00110 PRINT "Surplus time for technical matter: ";SURPLUS;"hours"
00120 LET TOTTIME+=SURPLUS
00130 PRINT "Total time is ";TOTTIME;"hours"
00140 END IF

;LIBRARY:
02000 DEF FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 PRINT "Accumulated total is: ";TOTTIME+=WRITETIME;"hours"
02040 FNEND

As noted for the previous example in this section, programming practices such as this are not recommended for new development that is to utilize the Library Facility. These examples are supplied to help you quickly modify existing programs so they can utilize the benefits of libraries.

The next two programs (main and library) show how the original program was changed to work with libraries.

;MAIN PROGRAM:
00005 LIBRARY "HOWTO3NL" : FNDOCEST,FNADD TOTTIME
00010 PRINT "Enter estimated number of pages for chapter 1:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)
00040 PRINT "Enter estimated number of pages for chapter 2:"
00050 INPUT PAGEEST
00060 PRINT "Is subject matter highly technical? (Y/N)"
00070 INPUT TECHLEVEL$
00080 LET FNDOCEST(PAGEEST)
00090 IF UPRC$(TECHLEVEL$)="Y" THEN
00100 LET SURPLUS=FNADD TOTTIME(0)*.2
00110 PRINT "Surplus time for technical matter: ";SURPLUS;"hours"
00130 PRINT "Total time is ";FNADD TOTTIME(SURPLUS);"hours"
00140 END IF

;LIBRARY PROGRAM:
02000 DEF LIBRARY FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 PRINT "Accumulated total is: ";TOTTIME+=WRITETIME;"hours"
02040 FNEND
03000 DEF LIBRARY
FNADD TOTTIME(ADDTOTTIME)=TOTTIME+=ADDTOTTIME

Once the required steps of separating the two programs, adding the necessary LIBRARY statement to the main program and adding the LIBRARY keyword to the DEF statement in the library program were completed for the above code, the following steps were conducted to enable the main program and function to communicate the value of TOTTIME. Note that there is a limitation to the technique shown: the library program must be loaded into either resident memory (without use of RELEASE on the LIBRARY statement) or present memory for it to work. This is because it relies on the library's global variables remaining active even after function calls to it have been completed.

:1.) The FNADD TOTTIME function was added to the library program (line 03000). This function takes a variable (representing the amount to add to TOTTIME) that is passed by the main program. It adds the passed variable to TOTTIME, and also assigns the new value of TOTTIME to the function variable FNADD TOTTIME.
:2.) The FNADD TOTTIME function name was added to the LIBRARY statement on line 00005 of the main program.
:3.) Line 00120 of the main program was removed, and line 00130 was modified to call the FNADD TOTTIME library function instead of modifying TOTTIME directly. The value of SURPLUS is passed to FNADD TOTTIME; FNADD TOTTIME takes over the job of modifying the value of TOTTIME and making sure that both the main program and the library program know its new value.
:4.) Line 00100 of the main program was changed to call the FNADD TOTTIME function as well. Since this line only needs to query the value of TOTTIME, it passes a value of 0 as the amount to add to TOTTIME.

;Example 5:
Turning an existing program into a user-invokable library function 
Business Rules Library Facility makes it very easy to turn an entire program into a library function that a user can invoke at will from within another program. For example, consider a standard application that includes both a client maintenance (MNTCUST) program and an order entry program (ORDERS). You would like to give users the ability to invoke the client maintenance program from within the order entry program whenever they press F4. The steps required to do this are as follows:

:1.) Modify MNTCUST by placing the entire original program into a user-defined library function and adding a few lines that cause the program to call itself as a library function whenever it is executed as the main program.
:a.) Move any user-defined functions that exist within the main body of the program to the end of the program (or to a separate library).
:b.) Add lines such as the following to the top of the program. NOTE that the (program name) in line 00030 represents the name of the program (such as a main menu) from which you currently normally invoke the client maintenance program.

00010 LIBRARY "MNTCUST" : FNMNTCUST
00020 LET FNMNTCUST
00030 CHAIN (program name)
00040 DEF LIBRARY FNMNTCUST

:c.) Add the following line to the end of the main body of the program (prior to any user-defined function definitions):

80000 FNEND

:2.) Modify ORDERS as follows:

:a.) Change the screen to include a label that identifies the operation of the F4 key.
:b.) Change the program to check for pressing of the F4 key.
:c.) Change the program to execute the following whenever F4 is pressed. Note that the LIBRARY statement in line 50000 utilizes the "RELEASE" keyword: this causes the MNTCUST library to be loaded into memory on an as-needed basis only. Thus the only time that the on-the-fly client maintenance feature uses system resources is when the user actually requests the capability by pressing F4.

50000 LIBRARY RELEASE, "MNTCUST" :FNMNTCUST
50010 LET FNMNTCUST

;Example 6:
Tips for moving [[FNSNAP]]! functions into separate libraries for users of [[FNSNAP]]! programming tools, modifying existing programs to use libraries will involve a combination of the techniques demonstrated above. Every developers programs are different, so this section cannot give you a beginning-to-end list of steps to complete to accomplish the task, but the following are some steps you can start with:

:1.) Place the FNSNAP! functions into their own program. (This example uses MAIN\\FNSNAP as the path and location of the new program.)
:2.) Modify the DEF line for each of the functions in FNSNAP to utilize the LIBRARY keyword. For example:

Change this:

60150 DEF FNOK

To this:

60150 DEF LIBRARY FNOK

:3.) Add the following FNFNSNAP INIT function to the FNSNAP program. This function sets all the global variables that are used by the FNSNAP functions (in the past, FNSNAP! users were instructed to add these variable settings to the start of their programs). FNFNSNAP INIT also executes a LIBRARY statement for the FNSNAP program. This LIBRARY statement establishes linkage for all the functions in the FNSNAP program that are called by other functions in the same program.

00121 DEF LIBRARY FNFNSNAP INIT
00122 LET DATFMT$="MM-DD-CCYY" !:LET FULLSCR=0 !:LET MAXSROWS=22 !:LET WINDEV=OWINDEV=69 !:LET MGA$="24,2,C 78," !:IF NOT SSAV THEN LET SSAV=101 !:!Common Variables required by FNSNAP! !:
00124 LIBRARY "MAIN\FNSNAP" : FNRELPART,FNSAVPART, FNPM, FNAUTO, FNOK, FNWIN,FNCLSWIN, FNZERO, FNTIMMILREG, FNSSAV,FNSAVSCR, FNSETBAD, FNPURGE, FNFLDSEL$
00130 FNEND !:
:4.) Delete the separated functions from the main programs that are to use the FNSNAP library.

:5.) Add the following program line to each of the main programs that are to use the FNSNAP library. This statement establishes linkage between the functions to be called and the program they are located in, and it calls the FNFNSNAP INIT function, which sets the library's global values:

00160 LIBRARY "MAIN\FNSNAP":FNFNSNAP INIT, FNSSAV, FNPOPWIN,FNPOPBAR, FNWINDEV, FNPOPWIN INIT,FNPOPBAR INIT, FNCO$, FNMGCLR, FNTOP,FNOK, FNSAVSCR, FNSCRMGR, FNSAVPART,FNRELPART, FNCLRPART, FNZERO, FNNULL$,FNTIMMILREG, FNDIALOG$, FNWIN, FNCLSWIN,FNNOKEY, FNPOPUP, FNPM, FNAUTO,FNPFKEYLINE !:LET FNFNSNAP INIT !:!

==Error Processing==

If an error is not trapped in a library function, the error is reported back to the calling program. At this time the following system variables are set:

{|
|-valign="top"
|width="10%"|'''LINE'''||The line number of the calling program function call.
|-valign="top"
|width="10%"|'''ERR'''||The error number that occurred in the library function.
|-valign="top"
|width="10%"|'''CNT'''||The appropriate value as if the error occurred in the calling program.
|-valign="top"
|}
 
If an error occurs while attempting to match parameters between a function call and the function definition, CNT is set to the number of parameters successfully matched.

<noinclude>
[[Category:User Defined Functions and Libraries]]
[[Category:Facility]]
</noinclude>

Library Facility

2013-04-15T19:29:05Z

66.17.154.248: Created page with "Business Rules! now includes a comprehensive '''Library''' Facility. Similar to DLL (Dynamic Link Libraries), the Business Rules! Library Facility enables [[user-defin..."

[[Business Rules!]] now includes a comprehensive '''Library''' Facility. Similar to [[DLL]] (Dynamic Link Libraries), the Business Rules! Library Facility enables [[user-defined functions]] to be placed in a program ("library") that is separate from the main program. The library may be loaded "resident" (staying loaded regardless of the status of the main program), it may be loaded "present" (remaining active in current memory as long as the main program is active), or it may be loaded "as needed" (loaded when needed to execute a function, then unloaded as soon as the function has been executed).

A library is any [[Business Rules! program]] that contains library functions. A library must be identified to Business Rules! before a program can execute any of its functions. When a library is identified, Business Rules! adds its name to an internal table of library names. This table identifies the names of all the libraries that should be searched whenever a library function that is not yet linked to a library is called.

Business Rules! places no limits on the number of libraries that may be loaded into memory at one time. Business Rules! provides for maximum memory usage and performance flexibility by allowing libraries to be identified and loaded into memory via three different methods: the resident method, the present method and the as-needed method. See the separate descriptions below for specific information about each type of library.

==Advantages==

Some of the significant advantages of placing user-defined functions in a library rather than keeping them in the main program are as follows:

:1.) Reduces the size of executables - its no longer necessary to include a standard set of user-defined functions in every program in your application. For some applications (which may include literally hundreds of copies of the exact same code), the potential savings in disk space are tremendous.

:2.) Saves maintenance time - If you're in the habit of duplicating user-defined functions in every single program that needs them, you know what kind of effort it takes to make (and distribute to your clients) even a one-line change to a function. With Business Rules Library Facility, you make the change only once, and you replace only one program at the client's site.

:3.) Encourages use of programming standards - The use of library functions for a standard routine is a great way to encourage programming consistency and the setting of standards among your programmers.

==Library Function==

A '''library function''' is a specially defined [[user-defined function]]; it exists in a program which is frequently separate from the main program, but it may exist in the main program as well.

To qualify as a library function, a user-defined function must simply utilize the DEF statement's LIBRARY keyword. The following is an example of a library function definition:

52400 DEF LIBRARY FNRESLIB2
52500 PRINT "This is a library function"
52600 FNEND

Executing a library function is a two-step process. First, the program executing the library function must name the function in a LIBRARY statement, which establishes either named or unnamed linkage. Second, the program must call the library function; this may be accomplished using any of the same methods that is available for calling other user-defined functions. In the following example, line 01000 uses the LIBRARY statement to establish named linkage between the function FNPRESLIB2 and the library PRESLIB. Line 01100 causes the library PRESLIB to be loaded into present memory (if the library does not already exist in memory), then executes FNPRESLIB2.

01000 LIBRARY "PRESLIB": FNPRESLIB2
01100 LET FNPRESLIB2

===Implementation Considerations===

Business Rules Facility was carefully designed to offer a great deal of power and flexibility. Before you begin implementing this capability into your existing applications and ongoing development, ADS recommends that you consider the following:

:1.) Should your libraries remain resident?
Business Rules allows for libraries to remain resident in memory (providing maximum performance) or to be loaded and released as needed (providing best utilization of memory). Be sure to select the method or combination of methods that's best for your applications.

:2.) Will you use multiple versions of the same function?
Since maintaining more than one version of a function is one method of controlling program options, Business Rules' rule for library selection has been established with care. You should carefully review these rules and the ways in which multiple libraries can be of use to you as you plan your implementation.

Until you feel comfortable with the intricacies of the Business Rules Library Facility, ADS recommends that you give every library function a name that is unique from every other library function.

:3.) Do your existing functions utilize global program variables?
Unlike local user-defined functions, library functions that exist in a program separate from the main program cannot access main program variables globally. They have to be specifically passed. You should carefully review your usage of global variables before moving local functions into separate libraries.

===As needed Library===

An as-needed library is loaded and unloaded as needed for execution of specific functions. Loading a library only when it is needed allows the program to conserve memory usage.

Each library has its own global variables that are separate from the main program's variables. Global Variables in an as-needed library are cleared each time a function call to the library is completed and the library is subsequently unloaded from memory.

Programs can indicate that a library is to be loaded as needed by specifying the LIBRARY statement with both the RELEASE parameter and function names. This causes Business Rules to establish named linkage between the specified function(s) and the specified library, but it does not actually load the library. (The library is loaded only when one of the as-needed library's functions is actually called.) In the following example, line 00280 establishes linkage between the library ASNLIB and the function FNASNLIB1. Line 00290 causes the following to occur:

:1.) Load ASNLIB into memory,
:2.) Execute the function FNASNLIB1,
:3.) Remove ASNLIB from memory.

00280 LIBRARY RELEASE,"ASNLIB": FNASNLIB1
00290 LET FNASNLIB1

===Linkage Reassignment and Detachment===

Once Business Rules has established linkage between a specific function and a specific library, the linkage remains active until a specific event causes it to become reassigned or detached.

;REASSIGNMENT:
As noted previously, the LIBRARY statement may be used to establish linkage between a function and the library from which it is to be called. When the named LIBRARY statement is used, linkage is directly established between the named library and the named function(s). When the unnamed LIBRARY statement is used, Business Rules searches for the function according to some pre-set guidelines and assigns linkage to the first library within which the function definition is found.

Once a function has actually been linked to a library, the only way to subsequently establish linkage between the same function name and a different library is to execute another LIBRARY statement that names the same function and a different library. When all of a present library's linked functions are reassigned; the library is automatically removed from memory. When all of a resident library's linked functions are reassigned; the library may be removed from memory with the CLEAR command.

In the following example, lines 01100 and 01200 load the libraries PRESLIB1 and PRESLIB2 into present memory. Line 01300 uses a named library statement to establish linkage between PRESLIB1 and the function FNASSIGN, and line 01400 actually executes FNASSIGN from the PRESLIB1 library. Line 1500 then re-assigns linkage of FNASSIGN to the library PRESLIB2, and line 1600 executes FNASSIGN from the PRESLIB2 library.

01100 LIBRARY "PRESLIB1":
01200 LIBRARY "PRESLIB2":
01300 LIBRARY "PRESLIB1": FNASSIGN
01400 LET FNASSIGN
01500 LIBRARY "PRESLIB2": FNASSIGN
01600 LET FNASSIGN

;DETACHMENT:
Regardless of how a library is loaded (resident, present or as needed), all linkages are detached at the time that the main program ends.

There is no other way to completely detach a linkage other than ending the main program.

===Present Library===

A present library is a library that is loaded to remain in memory as long as the main program is active or until all linkages that have been established for the library are reassigned.

Each library has its own global variables that are separate from the main program's variables. Global Variables in a present library are cleared when the main program ends.

A library can be loaded present through three different methods:
#.The first method is to specify a LIBRARY statement that identifies a library name but no function names. When this method is used, the library is loaded at the time that the LIBRARY statement is executed. For example, when the following statement is executed, the CURLIB library is immediately loaded into memory:

00210 LIBRARY "CURLIB":

#.The second method of loading a library present is to specify the LIBRARY statement with both a library name and function names. When this method is used, the library is loaded the first time one of the specified functions is called. In the following example, line 00210 establishes linkage between the function FNCURLIB1 and the library CURLIB.

Line 00220 causes the following to occur:

:1.) The library CURLIB is loaded as a present library,
:2.) The function FNCURLIB is executed.

00210 LIBRARY "CURLIB": FNCURLIB1
00220 LET FNCURLIB1

#.The third way to end up with a library loaded present is to execute a CLEAR STATUS command on a library that has already been loaded resident and has attached functions, thus turning it into a present library.

===Resident Library===

A resident library is a library program that is loaded to remain in memory, regardless of the status of the main program. It does not get removed from memory until it is explicitly cleared or until the Business Rules session is terminated. Loading a library resident saves the overhead associated with loading a library each time it is needed.

Each library has its own global variables that are separate from the main program's variables. Business Rules allows resident libraries to handle their own global variables in any of three different ways:

:1.) Globals may be cleared when the main program ends,
:2.) Globals may be retained irrespective of the status of the main program, or
:3.) Globals may be cleared after each function call to the resident library.

The resident status of a resident library can be removed (thus changing the library into a present library) through the use of the CLEAR STATUS command.

A library can be made resident through use of the enhanced LOAD command. However, it is important to understand that functions cannot be executed from any library -even a library that has been loaded into resident memory -until a LIBRARY statement names the functions to be executed and establishes linkage (either named or unnamed) between the named function and the resident library.

In the following example, line 00130 causes RESLIB to be loaded into memory as a resident library. Line 00140 establishes named linkage between the function FNRESLIB1 and the RESLIB library. Line 00150 executes the function FNRESLIB1.

00130 EXECUTE "LOAD RESLIB,RESIDENT"
00140 LIBRARY "RESLIB": FNRESLIB1
00150 LET FNRESLIB1

==Comparison of User-Defined Function Features==

The following table illustrates the similarities and differences between regular user-defined functions (non-library) and library user-defined functions.

[[Image:Help0185.jpg]] 
[[Image:Help0186.jpg]] 
[[Image:Help0187.jpg]]

==Variable Usage==

Before you start placing all your existing user-defined functions into separate libraries, you should fully understand how library functions deal with global variables.

This section will focus on three main points:

:1.) How a main program and a library function can communicate,
:2.) How functions within a library communicate, and
:3.) When global variables are cleared for a library program.

===How main programs and library functions communicate===

Business Rules programs communicate with regular user-defined functions via passed parameters, the returned function value, and global variables (variables not passed in the parameter list). All of these same communication options are available for library functions that are defined within the main program. However, only the first two options are available to library functions that are separate from the main program. These functions cannot access the main program's global variables because global variables are only available to routines and functions, which are defined within the same program. As a result, user-defined functions, which are held within a main program, may need to be reviewed for their global variable usage before they are changed to library functions and placed into a separate library program.

If a program needs to communicate a large number of standard values to a library function, consider using an initialization function to pass the values to the library program. Then have the initialization function assign the passed values to global variables in the library so they will be available to all functions in the library.

===How functions within a library communicate===
Within each library, all functions share variables which are global to that library, and library global variables generally retain their values between function calls. (The exception is when the RELEASE keyword is used on the LIBRARY statement, which is accepted both for resident and as-needed libraries; in this case, global variables are cleared after each function call.)

The point at which globals are cleared for a library program varies according to several factors. See below for more information.

===When global Variables are cleared===
The point at which a library's global variables are cleared depends on how the library was loaded and -in the case of resident libraries-what options are used.

{\b Main program library} - For library functions that are defined within the main program, globals are cleared when a new main program is started or when the current main program is explicitly removed from memory.

'''Resident library''' - When a library is loaded resident, global variables may be cleared in any of three ways:
{|
|-valign="top"
|width="10%"|'''Default'''||By default, Business Rules clears a resident library's global variables when the main program ends.
|-valign="top"
|width="10%"|'''Retain'''||When the OPTION RETAIN statement is used in a resident library program, the library retains its global variables irrespective of when the main program ends. The only way to clear globals when this statement is used is to CLEAR the library from memory or to reload it with the LOAD RESIDENT command. Remember that the library must be loaded resident for the OPTION RETAIN statement to have any affect.
|-valign="top"
|width="10%"|'''Release'''||When a resident library is named on a LIBRARY statement with the RELEASE keyword, the library's global variables are cleared after each function call to the library. This capability is provided so that the decision to load a library resident or as-needed can be made on a case-by-case basis; the program code can remain the same (because Business Rules handles the variables the same) regardless of whether the library is loaded resident or as-needed.
|-valign="top"
|}
 
{\b Present library} - When a library is loaded present, global variables are cleared when the main program ends.

{\b As-needed library} - When a library is loaded as-needed, global variables are cleared after each function call to the library.

The following table summarizes the information presented above. The keywords used in the "When globals are cleared" column are the same keywords used in the STATUS LIBRARY display (second column from right) to identify when variables for the listed library will be cleared. (See the "STATUS" command in the Commands chapter for complete information about this display.) The keywords are defined as follows:

{|
|-valign="top"
|width="10%"|'''RUN'''||Globals are cleared when new main program is run.
|-valign="top"
|width="10%"|'''END'''||Globals are cleared when main program ends.
|-valign="top"
|width="10%"|'''EXIT'''||Globals are cleared after each function call to the library.
|-valign="top"
|width="10%"|'''RETAIN'''||Globals are retained, irrespective of main program status.
|-valign="top"
|}
 
[[Image:Help0188.jpg]]

==Additional Processing Consideration==

Active procedures and opened files are not affected by library function calls, unless the library issues commands that specifically affect them. This includes PROCERR settings.

A nice aspect of library functions is the capability of a program to call a library function, which, in turn, calls a function in the main program. This supports the concept of manager functions that provide overall functionality while the main program fills in the details that may vary from program to program.

The way to permit library routines to be overridden (functionally replaced) by corresponding functions in the main program is to have the library include those functions in a LIBRARY statement that doesn't specify a library name. Then have the library execute that statement after the main program has started. The library will then attach the library function in the main program instead of its own, even if a copy of the function exists in the library, because the main program is always regarded as having been loaded last for purposes of resolving unnamed library searches.

Note that if a LIBRARY statement within a resident library creates linkage and then the main program ends, the linkage is broken and that LIBRARY statement must be re-executed before the function can be called again by the resident library.

With respect to speed, parameters should be passed by reference (using the & in front of the variable name in the DEF statement) wherever possible. This avoids needless allocation of memory and copying of data, which is a significant part of function call processing.

If you want to avoid the processing time required to load a library until a function within it is called, simply name the library and function on the same LIBRARY statement. However, if you want to be sure that the named functions exist within the library, first load the library with a statement that contains no function names. This will cause the library to be loaded at the time the LIBRARY statement is executed. Then when the LIBRARY statement containing the function list is encountered, the library (which is now in memory) will be checked for the presence of each function.

It should be emphasized that executing a LOAD command does not establish function linkage. A subsequent LIBRARY statement must be processed to establish such linkage.

When replacing a resident library with a different library, the first library should be cleared with a CLEAR command to free its memory before loading the second library.

Updating a library (with the REPLACE command) has no effect on application environments until the library is (re)loaded. 
If a LIBRARY statement contains the name of a local function that is defined as non-library, a "duplicate function definition" error is generated when the program is run or saved.

If a LIBRARY statement refers to a library without RELEASE and another statement refers to the same program with RELEASE, an error is generated. Also RELEASE cannot be specified for any library with the OPTION RETAIN statement.

If a function in the main program, defined with the LIBRARY keyword, is called from within a library (a condition referred to as library loopback), the main program uses a fresh for-next stack. 
Therefore, pre-existing for-next processes are not recognized until the library returns normally to the main program.

If more than one DEF LIBRARY statement for the same function name appears in a program, the lowest numbered definition will be used. More than one non-library DEF for the same variable is no longer permitted.

Memory fragmentation can occur if a library is loaded resident while other programs are in memory, and then the main program chains leaving files open through either the CHAIN FILES statement, or having files open NOCLOSE. To avoid this problem, if you use CHAIN FILES or NOCLOSE, load your resident libraries before running application programs.

Alternate libraries can be interrogated with function key 9 during a program pause.

===Editing Active Libraries===

When both a main program and a library program that is separate from the main program are active ( a function in the library program is currently being executed), the LIST command will display the contents of the library program. When functions in multiple library programs are active, the program with the most recently called function will be displayed.

It is important to note that the only way to save changes made to a library program that has been activated by a main program is to list the library to a file and reload it from source later on. Because of this, it makes sense to develop a new library function first within the main program. Then once you've completed the testing and debugging process, you can break it out and test it as a separate library function.

===Linkage===

When used to its full potential, the Business Rules Library Facility enables multiple versions of the same function (with the same name) to exist in different libraries, all of which may be loaded into memory. The actual library that is used for a specific function call is determined according to Business Rules rule for linkage, which is the process of associating a function name with a library name. 
Business Rules keeps tracks of established linkages in a table that it references each time a function is called.

The LIBRARY statement may be used to establish linkage in one of two ways: the named method, or the unnamed method. These methods are defined as follows:

;Named
The LIBRARY statement explicitly links one or more specific functions to a specific library. This is the most efficient and foolproof method for assuring that the library function you wish to use gets executed.

In the following example, the functions FNRESLIB1 through FNRESLIB5 are explicitly linked to the library MAIN. When any of these functions is called, Business Rules will automatically execute them from the MAIN library. (Regardless of whether or not any other library currently in memory also contains functions by the same name.)

50300 LIBRARY "MAIN":FNRESLIB1,FNRESLIB2,FNRESLIB3,FNRESLIB4,FNRESLIB5

;Unnamed
The LIBRARY statement names the desired library functions and leaves it to Business Rules to determine which of the currently identified libraries they should be linked to. This determination is made according to the pre-set guidelines described below. The unnamed method of linkage is useful when your development methodology involves using multiple versions of the same function to control program options and features.

When the unnamed method is used, Business Rules first searches the main program, then each library that is currently either resident or present (in last loaded, first searched order) for each function listed on the LIBRARY statement. Once Business Rules finds the function, the linkage is established, and -unless the linkage is explicitly changed with another LIBRARY statement or detached because the main program ends -all future calls to the same function will continue to utilize the same linkage. Note that Business Rules does not search as-needed libraries when the unnamed method of establishing linkage is used. Also, it is important to understand that it can take significantly longer to establish linkage using the unnamed method of linkage than with the named method of linkage.

In the following example, line 01000 loads RESLIB as a resident library. Lines 01100 and 01200 load PRESLIB1 and PRESLIB2 as present libraries, and line 01300 names ASNLIB as an as-needed library. The LIBRARY statement on line 01400 establishes unnamed linkage for the function FNALIBI. When line 01500 is executed, Business Rules searches the currently loaded programs in the following order for FNALIBI: Main program, PRESLI2, PRESLIB1, RESLIB. Note that ASNLIB is not considered for this search because it is not currently loaded in memory.

01000 EXECUTE "LOAD RESLIB,RESIDENT"
01100 LIBRARY "PRESLIB1":
01200 LIBRARY "PRESLIB2":
01300 LIBRARY RELEASE,"ASNLIB": FNASNLIB1
01400 LIBRARY : FNALIBI
01500 LET FNALIBI

===Status Library===

Business Rules STATUS LIBRARY command may be used to display a table that identifies all the linkages that are currently active for each library. See "STATUS" in the Commands chapter for more information. For information about releasing and/or changing library linkages, see the term Linkage reassignment and detachment below.

==Sample Program==

The following two sample sections of code are, for convenience purposes, labeled "Main Program" and "Library". The Main Program references two functions (FNSEND and FNRECEIVE), which are located in the Library. Line 50 of the Main Program establishes the function linkage; line 70 prompts for a message; and line 110 calls the FNSEND function, which is defined on line 30 of the Library.

FNSEND opens the communications port and sends the operator-specified message to the terminal connected to the port. The Main Program then calls the FNRECEIVE function, which is defined on line 80 of the Library. This function waits up to 15 seconds for a response (by default), returns the response in the parameter, and returns its length as a function value. Finally, the Main Program prints the response or the message "No Response".

;MAIN PROGRAM:

00010 ! MAIN PROGRAM
00020 !
00030 DIM MESG$*60, RESPONSE$*120
00040 !
00050 LIBRARY "TOOLS\LIB1": FNSEND, FNRECEIVE
00060 !
00070 PRINT "Specify Message"
00080 LINPUT MESG$
00090 IF LEN(MESG$) = 0 THEN STOP
00100 !
00110 LET FNSEND(MESG$)
00120 !
00130 IF FNRECEIVE(RESPONSE$) THEN !:PRINT RESPONSE$ !:ELSE !:PRINT "No Response"
00140 GOTO 70

Library:
00010 ! LIB1
00020 !
00030 DEF LIBRARY, FNSEND(MESSAGE$*60)
00040 IF NOT COMM OPENED THEN !:OPEN #40: "NAME=COM2:, FORMAT=ASYNC,BAUD=2400",DISPLAY, OUTIN !:COMM OPENED = 1
00050 PRINT #40: MESSAGES$
00060 FNEND
00070 !
00080 DEF LIBRARY FNRECEIVE(&RESP$)
00090 LINPUT #40: RESP$ IOERR 100
00100 FNRECEIVE = LEN(RESP$)
00110 FNEND

===Tips for implementing Library Functions in Existing Applications===

As mentioned above, it is important that you consider your current usage of global variables before converting your existing user-defined functions into library functions and placing them into a separate program. This section provides some examples of how you can modify existing applications to utilize library functions, even if the existing applications currently access or modify user-defined function variables from outside the function. Other examples shown in this section demonstrate how you can turn an entire program (such as a client maintenance program) into a library function that a user can invoke at will from within another program (such as order entry) and provide some tips on implementing libraries for programs that use [[FNSNAP]]! tools.

;Example 1:
Separating main program logic from user-defined functions 
The following is a very simple example of a program that uses a user-defined function.

;ORIGINAL PROGRAM:
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)
02000 DEF FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page, plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

The steps you would need to take to separate the function into a separate library and enable the main program to call the function would be as follows:

:1.) Place the user-defined functions into their own program.
:2.) Modify the DEF line for each of the functions in the new library program to utilize the LIBRARY keyword (demonstrated in line 02000 of the library program below).
:3.) Delete the separated functions from the main programs that are to use the new library.
:4.) Add a LIBRARY statement to the main program that names each function that is to be called from the library program (demonstrated in line 00005 of the main program below).

;MAIN PROGRAM:
00005 LIBRARY "howto1nl" : FNDOCEST
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)

;LIBRARY PROGRAM:
02000 DEF LIBRARY FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,lus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

;Example 2:
Function uses global variables established by main program

In the following program, the global variable PAGEEST is established by the main program logic on line 00020. This same global variable is accessed by the user-defined function at line 02010.

;MAIN PROGRAM:
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST

;LIBRARY PROGRAM:
02000 DEF FNDOCEST
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

As there is no way for a main program to share its global variables with a library function contained in a separate program, this program must be modified before it can be separated into "main" and "library" programs. In the following example, line 02000 has been modified (as shown in italics) to pass the PAGEEST variable by reference, thereby causing the library function to use the main program's copy of the variable.

;MAIN PROGRAM:
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)

;LIBRARY PROGRAM:
02000 DEF FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

;Example 3:
Existing program queries function variable from outside function 
This example shows the same starting program as shown in Example 1, except that line 00040 has been added to demonstrate a situation where the main program logic queries (without changing) a variable that has been established by the user-defined function. This programming technique also is not allowed when functions are separated into library programs,
as there is just one way (via the function variable) for a separate library function to pass a value back to the main program.

;MAIN PROGRAM:
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST
00040 IF WRITETIME>8 THEN PRINT "Total days: ";WRITETIME/8

;LIBRARY PROGRAM:
02000 DEF FNDOCEST
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 FNEND

When starting new programming projects that are to utilize Business Rules Libraries, ADS recommends against the programming technique shown here. However, if your programs already use this technique and you want to utilize the benefits of libraries with as little work as possible, you could change the programs in the manner shown below.

The following two code sections show the original program as it would be when split into main program and library, and with a "rigged" technique for the program to get the value of the queried variable from the library. The "rig" is that all references to the WRITETIME variable in the main logic have been changed to FNWRITETIME, and FNWRITETIME has been added to the library to query the value of WRITETIME and pass it back to the main program. Note that there is a limitation to this technique: the program must be loaded into either resident memory (without use of RELEASE on the LIBRARY statement) or present memory for it to work. This is because the technique relies on the library's global variables remaining active even after function calls to it have been completed.

;MAIN PROGRAM:
00005 LIBRARY "howto2nl" : FNDOCEST,FNWRITETIME
00010 PRINT "Enter estimated number of pages:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)
00040 IF FNWRITETIME>8 THEN PRINT "Total days: ";FNWRITETIME/8

;LIBRARY:
02000 DEF LIBRARY FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page, plus 15% for index
02020 PRINT "Documentation estimate is:";WRITETIME;"hours"
02030 FNEND
03000 DEF LIBRARY FNWRITETIME=WRITETIME

;Example 4:
Existing program queries or modifies function variable from outside function 
In the following example, line 00120 of the main program logic modifies the value of TOTTIME, which is established by the FNDOCEST function. It is important that this modified value be communicated back to the function, because line 02030 of the function uses it for subsequent calls. Note also that lines 00100 and 00130 of the main program logic also query (without modifying) the value of TOTTIME.

;MAIN PROGRAM:
00010 PRINT "Enter estimated number of pages for chapter 1:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)
00040 PRINT "Enter estimated number of pages for chapter 2:"
00050 INPUT PAGEEST
00060 PRINT "Is subject matter highly technical? (Y/N)"
00070 INPUT TECHLEVEL$
00080 LET FNDOCEST(PAGEEST)
00090 IF UPRC$(TECHLEVEL$)="Y" THEN
00100 LET SURPLUS=TOTTIME*.2
00110 PRINT "Surplus time for technical matter: ";SURPLUS;"hours"
00120 LET TOTTIME+=SURPLUS
00130 PRINT "Total time is ";TOTTIME;"hours"
00140 END IF

;LIBRARY:
02000 DEF FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 PRINT "Accumulated total is: ";TOTTIME+=WRITETIME;"hours"
02040 FNEND

As noted for the previous example in this section, programming practices such as this are not recommended for new development that is to utilize the Library Facility. These examples are supplied to help you quickly modify existing programs so they can utilize the benefits of libraries.

The next two programs (main and library) show how the original program was changed to work with libraries.

;MAIN PROGRAM:
00005 LIBRARY "HOWTO3NL" : FNDOCEST,FNADD TOTTIME
00010 PRINT "Enter estimated number of pages for chapter 1:"
00020 INPUT PAGEEST
00030 LET FNDOCEST(PAGEEST)
00040 PRINT "Enter estimated number of pages for chapter 2:"
00050 INPUT PAGEEST
00060 PRINT "Is subject matter highly technical? (Y/N)"
00070 INPUT TECHLEVEL$
00080 LET FNDOCEST(PAGEEST)
00090 IF UPRC$(TECHLEVEL$)="Y" THEN
00100 LET SURPLUS=FNADD TOTTIME(0)*.2
00110 PRINT "Surplus time for technical matter: ";SURPLUS;"hours"
00130 PRINT "Total time is ";FNADD TOTTIME(SURPLUS);"hours"
00140 END IF

;LIBRARY PROGRAM:
02000 DEF LIBRARY FNDOCEST(&PAGEEST)
02010 LET WRITETIME=(PAGEEST*2)*1.15 ! Two hours per page,plus 15% for index
02020 PRINT "Documentation estimate is: ";WRITETIME;"hours"
02030 PRINT "Accumulated total is: ";TOTTIME+=WRITETIME;"hours"
02040 FNEND
03000 DEF LIBRARY
FNADD TOTTIME(ADDTOTTIME)=TOTTIME+=ADDTOTTIME

Once the required steps of separating the two programs, adding the necessary LIBRARY statement to the main program and adding the LIBRARY keyword to the DEF statement in the library program were completed for the above code, the following steps were conducted to enable the main program and function to communicate the value of TOTTIME. Note that there is a limitation to the technique shown: the library program must be loaded into either resident memory (without use of RELEASE on the LIBRARY statement) or present memory for it to work. This is because it relies on the library's global variables remaining active even after function calls to it have been completed.

:1.) The FNADD TOTTIME function was added to the library program (line 03000). This function takes a variable (representing the amount to add to TOTTIME) that is passed by the main program. It adds the passed variable to TOTTIME, and also assigns the new value of TOTTIME to the function variable FNADD TOTTIME.
:2.) The FNADD TOTTIME function name was added to the LIBRARY statement on line 00005 of the main program.
:3.) Line 00120 of the main program was removed, and line 00130 was modified to call the FNADD TOTTIME library function instead of modifying TOTTIME directly. The value of SURPLUS is passed to FNADD TOTTIME; FNADD TOTTIME takes over the job of modifying the value of TOTTIME and making sure that both the main program and the library program know its new value.
:4.) Line 00100 of the main program was changed to call the FNADD TOTTIME function as well. Since this line only needs to query the value of TOTTIME, it passes a value of 0 as the amount to add to TOTTIME.

;Example 5:
Turning an existing program into a user-invokable library function 
Business Rules Library Facility makes it very easy to turn an entire program into a library function that a user can invoke at will from within another program. For example, consider a standard application that includes both a client maintenance (MNTCUST) program and an order entry program (ORDERS). You would like to give users the ability to invoke the client maintenance program from within the order entry program whenever they press F4. The steps required to do this are as follows:

:1.) Modify MNTCUST by placing the entire original program into a user-defined library function and adding a few lines that cause the program to call itself as a library function whenever it is executed as the main program.
:a.) Move any user-defined functions that exist within the main body of the program to the end of the program (or to a separate library).
:b.) Add lines such as the following to the top of the program. NOTE that the (program name) in line 00030 represents the name of the program (such as a main menu) from which you currently normally invoke the client maintenance program.

00010 LIBRARY "MNTCUST" : FNMNTCUST
00020 LET FNMNTCUST
00030 CHAIN (program name)
00040 DEF LIBRARY FNMNTCUST

:c.) Add the following line to the end of the main body of the program (prior to any user-defined function definitions):

80000 FNEND

:2.) Modify ORDERS as follows:

:a.) Change the screen to include a label that identifies the operation of the F4 key.
:b.) Change the program to check for pressing of the F4 key.
:c.) Change the program to execute the following whenever F4 is pressed. Note that the LIBRARY statement in line 50000 utilizes the "RELEASE" keyword: this causes the MNTCUST library to be loaded into memory on an as-needed basis only. Thus the only time that the on-the-fly client maintenance feature uses system resources is when the user actually requests the capability by pressing F4.

50000 LIBRARY RELEASE, "MNTCUST" :FNMNTCUST
50010 LET FNMNTCUST

;Example 6:
Tips for moving [[FNSNAP]]! functions into separate libraries for users of [[FNSNAP]]! programming tools, modifying existing programs to use libraries will involve a combination of the techniques demonstrated above. Every developers programs are different, so this section cannot give you a beginning-to-end list of steps to complete to accomplish the task, but the following are some steps you can start with:

:1.) Place the FNSNAP! functions into their own program. (This example uses MAIN\\FNSNAP as the path and location of the new program.)
:2.) Modify the DEF line for each of the functions in FNSNAP to utilize the LIBRARY keyword. For example:

Change this:

60150 DEF FNOK

To this:

60150 DEF LIBRARY FNOK

:3.) Add the following FNFNSNAP INIT function to the FNSNAP program. This function sets all the global variables that are used by the FNSNAP functions (in the past, FNSNAP! users were instructed to add these variable settings to the start of their programs). FNFNSNAP INIT also executes a LIBRARY statement for the FNSNAP program. This LIBRARY statement establishes linkage for all the functions in the FNSNAP program that are called by other functions in the same program.

00121 DEF LIBRARY FNFNSNAP INIT
00122 LET DATFMT$="MM-DD-CCYY" !:LET FULLSCR=0 !:LET MAXSROWS=22 !:LET WINDEV=OWINDEV=69 !:LET MGA$="24,2,C 78," !:IF NOT SSAV THEN LET SSAV=101 !:!Common Variables required by FNSNAP! !:
00124 LIBRARY "MAIN\FNSNAP" : FNRELPART,FNSAVPART, FNPM, FNAUTO, FNOK, FNWIN,FNCLSWIN, FNZERO, FNTIMMILREG, FNSSAV,FNSAVSCR, FNSETBAD, FNPURGE, FNFLDSEL$
00130 FNEND !:
:4.) Delete the separated functions from the main programs that are to use the FNSNAP library.

:5.) Add the following program line to each of the main programs that are to use the FNSNAP library. This statement establishes linkage between the functions to be called and the program they are located in, and it calls the FNFNSNAP INIT function, which sets the library's global values:

00160 LIBRARY "MAIN\FNSNAP":FNFNSNAP INIT, FNSSAV, FNPOPWIN,FNPOPBAR, FNWINDEV, FNPOPWIN INIT,FNPOPBAR INIT, FNCO$, FNMGCLR, FNTOP,FNOK, FNSAVSCR, FNSCRMGR, FNSAVPART,FNRELPART, FNCLRPART, FNZERO, FNNULL$,FNTIMMILREG, FNDIALOG$, FNWIN, FNCLSWIN,FNNOKEY, FNPOPUP, FNPM, FNAUTO,FNPFKEYLINE !:LET FNFNSNAP INIT !:!

==Error Processing==

If an error is not trapped in a library function, the error is reported back to the calling program. At this time the following system variables are set:

{|
|-valign="top"
|width="10%"|'''LINE'''||The line number of the calling program function call.
|-valign="top"
|width="10%"|'''ERR'''||The error number that occurred in the library function.
|-valign="top"
|width="10%"|'''CNT'''||The appropriate value as if the error occurred in the calling program.
|-valign="top"
|}
 
If an error occurs while attempting to match parameters between a function call and the function definition, CNT is set to the number of parameters successfully matched.

<noinclude>
[[Category:User Defined Functions and Libraries]]
[[Category:Facility]]
</noinclude>

User Defined Functions

2013-04-15T19:11:21Z

66.17.154.248: Created page with "A '''User Defined Function''' in Business Rules! is an extremely useful tool. Using a function you can perform a series of similar tasks on one or more variables and retu..."

A '''User Defined Function''' in [[Business Rules!]] is an extremely useful tool. Using a function you can perform a series of similar tasks on one or more variables and return the changed variable, a result of the interaction of those variables on one another, or a combination of both. Generally a function is created by using a [[DEF]] statement. If the function only needs one line of code then there are no additional lines, the function stands on its own. More likely, however, is a multilined function, these also start with a DEF clause followed by various BR statements and end with an [[FNEND]] statement.

The lines of code between the DEF and the FNEND statements follow the same rules as "normal" BR code with a few exceptions relating to variables passed in to the function. If a variable is passed into a function it can be "by reference" or "by value".

See also the [[Library Facility]].

====By Value====

A By Value function variable can be passed to a function, but is not returned by the function. That is, any changes made to the variable in the called function have no affect on the variable in the calling program. The calling program passes just the value or content of the variable into the function, not the actual variable, so the called function has no way to change the real variable. When calling a function, if a parameter is being passed By Value, you may substitute a literal instead of a variable.

====By Reference====

A By Reference function variable is sent to the function and whatever changes the function makes on the variable are returned to (occur within) the calling program. By Reference variables are designated in the DEF statement with a leading ampersand "&". The calling program passes a memory reference to the variable itself, giving the function access to modify the variable. Matrices passed to a function are always passed By Reference, because it is much faster to pass just a reference to a large array into a function than it would be to pass the entire array By Value.

If a function definition lists a parameter as By Reference (you see the "&" in the def statement), then BR will not allow you to pass a literal as that parameter into the function. Instead you must pass an actual calling program variable.

====Matrix changes====

As mentioned above a [[Mat|matrix]] is always passed By Reference. It can be redimensioned, changed in many ways and then used by the calling program in it's changed state.

The only time when this will not happen is when the matrix is non-existent in the function call. A non-existent matrix is one that has been marked as an "Optional" variable in the DEF statement and no matrix was named in the program call to the function. The non-existent matrix can not then be re-dimensioned because it does not exist. If you want to re-dimension a matrix and have it passed out of the function then it is necessary to use a "dummy" matrix passed in so that the function does not use a NULL array by default.

====Library Function====

A function can either be a part of the program that is loaded, similar to a sub-routine, or it can be a library function that is either present in the program or located in another named program. A library function definition differs from a function definition because it includes the word library between the DEF and the name of the function. The program code for a library function is otherwise the same as a function.

In order to use a library function the library and the library function name must be designated in the program that calls the library function. (Libraries may call other libraries.) This is done with a "LIBRARY" statement.

LIBRARY "E:\\WB\\vol002\\fnsnap.dll":FNPRINTBOX,FNDRAWBOX

The above statement says that the library functions FNPRINTBOX and FNDRAWBOX are located in the Business Rules! program "[[FNSNAP.dll]]" that has been named with a dll suffix, rather than a .BR or .WB suffix, located in the "wb\\vol002" directory of drive E:. Note that Business Rules! automatically assigns a .BR or .WB suffix to programs when they are initially created, but a [[Business Rules!|BR]] program can have any suffix that you assign to it.

===Library Variables===

Any variable used with a program or library is common to all the functions, sub-routines and mainline routines within that program or library. This means that if, in library SAMPLE.br, library function FNFIRST uses a variable "X" to count how many times a routine is processed and it turns out that that number is 10, and library function FNSECOND, also included in SAMPLE.br, uses the variable "X" which it expects is initialized to zero because that function has not used it before, unexpected results will occur because the value of "X" is now 10, not zero. If FNSECOND were located in a different library, then the value of "X" set by FNFIRST would not be visible to it and FNSECOND would not use the value of 10, but might use a value previously set by FNSECOND.

It is good practice to avoid such problems by declaring 'work' variables as optional parameters within function definitions. Optional parameters are listed after required parameters and the two groups are separated with a semicolon (;). Listing work variables as optional parameters avoids both present and future variable name conflicts with other routines or functions.

===Library Sub-routines===

Sub-routines in programs are very useful. They can be used from different parts of the program without the necessity of duplicating code. They can also be used to keep complex manipulations out of the main logic of a program to make it easier to understand. Sub-routines can be used in functions, library functions, and libraries as well. Two library functions residing in the same library can each use the same sub-routine, located outside of the [[DEF]] / [[FNEND]] boundaries. This is true as long as the sub-routine is located within the same library as the library function(s) making use of it.

===Library Status===

Once a library has been created and it is being named in a program it can be loaded as a "RESIDENT", library, a "CURRENT" library or a "RELEASE" library.

====Resident Library====

A resident library once loaded remains in memory and can be called by any program that is subsequently loaded. It retains its variable values from program to program. It is only removed with a clear command or by exiting the [[Business Rules!|BR]] session.

00100 library resident "E:\\wb\\vol002\\getdates.br":FNDATE

====Current Library====

The default load of a library is a current library. It is active while the program that loads it is in memory and retains its variables only while that program is active. A current library, because it terminates when a program ends, cannot call a resident library.

00100 library "E:\\wb\\vol002\\getdates.br":FNDATE

====Release Library====

A library that is designated as release only maintains its variables while a call to it is active. As soon as the function reaches the FNEND statement and passes information back to the calling function or routine the variables are cleared. A released library, since it does not occupy memory when not active cannot call a current or a resident library.

00100 library release "E:\\wb\\vol002\\getdates.br":FNDATE

<noinclude>
[[Category:User Defined Functions and Libraries]]
[[Category:Basics]]
</noinclude>

PEM File

2013-04-15T18:47:02Z

66.17.154.248: Created page with "The '''PEM Files''' are used in Properties, Events, and Methods (PEM) and .NET controls. ===BR Directory=== *pemnet.dll *brconvert.dll *vcdlltest.exe (used fo..."

The '''PEM Files''' are used in [[Properties, Events, and Methods (PEM) and .NET controls]].

===BR Directory===
*[[pemnet.dll]]
*[[brconvert.dll]]
*[[vcdlltest.exe]] (used for testing)

===Windows===
Use the following files to install the necessary system programs.

*[[dotnetfx20.exe]] (Windows 2000) or [[dotnetfx35.exe]] (Windows XP or Vista) - to install/upgrade dot net
*[[vcredist_x86.exe]] - to install a required dot net support library

There are two main groups of supporting Dll's needed to use .Net controls with BR:

#VC++ shared libraries. These can be tested with [[vcdlltest.exe]] and installed with vcredist_x86.exe.

#The .Net framework. If you are using Windows 2000, you will need to use dotnetfx20.exe. If you are using windows XP or Vista use dotnetfx35.exe.

Category:Properties Events and Methods

2013-04-15T18:44:42Z

66.17.154.248:

See also: [[Properties, Events, and Methods (PEM) and .NET controls]]

External controls can now be placed on BR windows:

PRINT FIELDS "row,col,comp[onent] rows/cols,[,INDEPENDENT]": control-id$,mat properties$ [, mat events$]

INDEPENDENT will signify that the control is independently enabled and is not subject to the normal enabling restrictions associated with FIELDS operations.

control-id$ should be in the format "mycontrol:class-name"
mat properties$ will have property assignments (e.g. color=blue)
mat events$ will have event assignments to fkey values (TypChanged=1035)
- to clear pevious settings use TypChanged= -1
- setting events is optional

The above form cannot be used in the same statement as other controls.

The following forms can be used in the same FIELDS array as other controls:

PRINT FIELDS "row,col,comp[onent] [rows/cols]": mat properties$

INPUT FIELDS "row,col,comp[onent] rows/cols": mat properties$

Input Processing
'''Mat properties$''' has property names or property assignments.
Any assigned values will be ignored. The array will be populated with property assignments for all specified properties.

The syntax for retrieving all of the names:
INPUT FIELDS "row,col,comp[onent] rows/cols,PROPERTY_NAMES,depth": mat properties$
INPUT FIELDS "row,col,comp[onent] rows/cols,EVENT_NAMES": mat events$
INPUT FIELDS "row,col,comp[onent] rows/cols,METHOD_NAMES": mat methods$

To set or get individual properties:
set$("#fileno,row,col","city=Los Angeles")
set$("#fileno,row,col","address.city=Los Angeles")
get$("#fileno,row,col","city")

To invoke a method:
INVOKE("#fileno,row,col",method-name$, mat args$)

==PEM Data Conversion==

BR offers only two data types - [[string]] and [[numeric]]. Many other types are required by various controls available for outside resources.

Concerning .NET and other objects, BR provides conversion routines for the purpose of working with various data types. For example you may express colors as is done in HTML (#xxyyzz) and have them converted to and from a structure with RGB values for use by a .NET object.

These conversion routines are in a separate [[DLL]] that is automatically invoked based on the field's [[class]] type when a property value is sent or received by BR via a properties array, or a [[GET]], [[SET]] or [[INVOKE]] parameter. The DLL used to perform these conversions is included in the [[object toolbox DLL group]] located in the BR directory.

The first release of the DLL supports the following object types:
// conversion class for System.Drawing.Color
// conversion class for System.String
// conversion class for System.Int32

If there is a class that you would like to see a conversion routine for that does not exist and you wish to write one, this must implement the interface (DLL data type name) brconvert.BrConversion which has 2 methods:

int objectToString(System.String string, out System.Object value)
int stringToObject(System.Object value, out System.String string)

You must also prepend the name of the class with brconvert.BR so if you were going to make a conversion class for System.Drawing.Color the conversion class would need to be named:

brconvert.BRSystem.Drawing.Color.

==PEM File Requirements==

{{:PEM File}}

[[Category:4.20]]

Border Spec

2013-02-04T19:06:41Z

66.17.154.248: /* Syntax */

The "BORDER=spec" parameter represents an inserable syntax that specifies the visual characteristics of the window border, within the [[Open Window]] statement. The BORDER= keyword must be followed by one of four border specifications (as of 4.3 these work with CON GUI ON as well).

===Syntax===
[[image:Borderspec.png|500px]]

===Parameters===
*"B" indicates that the border is to be blank;
*"D" indicates a double-line border;
*"H" indicates that a shadowed or highlighted border be used;
*and "S" indicates that a single-lined border be used.
"Corners" and "8 chars" border specifications may be used for custom-designed window borders. See [[Screen I/O]] for illustrations and more information about border types and border graphics specifications. However, as of 4.3, Border=H and "8 chars" are no longer supported except that a new [[Option (Config)|OPTION]] 62 permits S, D, B, H or an eight character string followed by a colon and then attributes. For example:
BORDER=S|D|B|H|8-chars[:attributes]
While the colon is actually optional, it is recommended for readability when attributes are included.

Also within the BORDER= syntax, the "attributes" parameter may be specified immediately after the border specification (no spaces). The attributes specified here will affect the visual display of the border itself. See [[Definitions]] for the correct syntax to be used with the "attributes" parameter.

Border Spec

2013-02-04T19:06:08Z

66.17.154.248: /* Syntax */

The "BORDER=spec" parameter represents an inserable syntax that specifies the visual characteristics of the window border, within the [[Open Window]] statement. The BORDER= keyword must be followed by one of four border specifications (as of 4.3 these work with CON GUI ON as well).

===Syntax===
[[image:Borderspec.png|300px]]

===Parameters===
*"B" indicates that the border is to be blank;
*"D" indicates a double-line border;
*"H" indicates that a shadowed or highlighted border be used;
*and "S" indicates that a single-lined border be used.
"Corners" and "8 chars" border specifications may be used for custom-designed window borders. See [[Screen I/O]] for illustrations and more information about border types and border graphics specifications. However, as of 4.3, Border=H and "8 chars" are no longer supported except that a new [[Option (Config)|OPTION]] 62 permits S, D, B, H or an eight character string followed by a colon and then attributes. For example:
BORDER=S|D|B|H|8-chars[:attributes]
While the colon is actually optional, it is recommended for readability when attributes are included.

Also within the BORDER= syntax, the "attributes" parameter may be specified immediately after the border specification (no spaces). The attributes specified here will affect the visual display of the border itself. See [[Definitions]] for the correct syntax to be used with the "attributes" parameter.

Open Window

2013-02-04T19:05:20Z

66.17.154.248: /* Supplemental Syntax ("BORDER= spec") */

See also: [[Parent=None]] and [[Picture]]

The '''OPEN window''' (OPE) [[statement]] specifies the characteristics for a window and activates the window for input/output. OPEN window can specify the following window characteristics: screen placement and dimensions, border type and attributes, attributes to be used for the text area of the window, and a caption to be displayed within the top border of the window.

:1.) When a file is opened for both SHR and INPUT, Business Rules will no longer change the time and date of the file. As a result of this change, when a file is to be opened both for OUTIN and for INPUT, the OPEN for OUTIN must be executed first. Otherwise an error [[0608]] will result. This will affect current programs.
:2.) The OPEN window statement now allows for flexibility in the specification of window coordinates. Previously all four coordinates of the window had to be specified in terms of two exact row positions and two exact column positions. With release 3.50, only one exact row position and one exact column position must be specified. Business Rules will automatically calculate the other row and/or column position according to the values of the ROWS= and COLS= parameters, which indicate the desired length or width of the window.

The ROWS= parameter may be used in place of either the SROW= or the EROW= parameter, but not both. Likewise, the COLS= parameter may be used in place of either the SCOL= or the ECOL= parameter, but not both. The following examples show some of the possibilities that are available using this syntax option. Each statement opens a 10 row by 10 column window in the upper left corner of the screen. (NOTE: ROWS= and COLS= parameters are shown in lowercase for emphasis; case makes no difference in actual syntax.)

00010 OPEN #1:"rows=10,cols=10,EROW=10,ECOL=10",DISPLAY,OUTPUT
00020 OPEN #1:"rows=10,SCOL=1,EROW=10,cols=10",DISPLAY,OUTPUT
00030 OPEN #1:"rows=10,SCOL=1,EROW=10,ECOL=10",DISPLAY,OUTPUT
00040 OPEN #1:"SROW=1,cols=10,rows=10,EROW=10",DISPLAY,OUTPUT
00050 OPEN #1:"SROW=1,cols=10,EROW=10,ECOL=10",DISPLAY,OUTPUT
00060 OPEN #1:"SROW=1,SCOL=1,rows=10,cols=10",DISPLAY,OUTPUT
00070 OPEN #1:"SROW=1,SCOL=1,rows=10,ECOL=10",DISPLAY,OUTPUT
00080 OPEN #1:"SROW=1,SCOL=1,EROW=10,cols=10",DISPLAY,OUTPUT

:3.) The OPEN window statement's BORDER parameter now accepts S (drop-shadow) as an attribute for the border. See "S Attribute" in the [[BRConfig.sys]] Specification section for more information.
:4.) The NOCLOSE parameter in any OPEN statement will leave that file open when a program ends or chains to another program. The only way this file is closed is by explicitly closing the file, CLEAR ALL, or by exiting from Business Rules.

00010 OPEN #1:"NAME=TEST,NOCLOSE",INTERNAL,RELATIVE,INPUT

===Comments and Examples===
Business Rules creates two different types of windows: windows that are opened as separate input/output files, and field help windows. The OPEN window statement allows you to create the first type, windows that accept input and output. For information about field help windows, see [[Screen I/O]].

Windows can also be opened separately from the main window. OPEN #0 is reserved for this. Also see [[Parent=Window]] for more information.

Regarding window size : (as of 4.3) when opening separate windows, 'NAME=window-name' indicates that BR is to save the position of the window at the time it is closed and restore it to that position when it is reopened, even across sessions. Replacement or overlaying windows can use the same window names to position themselves wherever and at whatever character size the user has changed it to. So once a window has been opened with a particular name, subsequent opens ignore ROW= and COL= and instead use the user positioned values.

As a result window positioning and size priority is as follows:
:1. NAME= window-name
:2. (for window zero only) un-named save font size and position.
:3. SROW, SCOL, MAXIMIZE, NOMAXIMIZE, ABSOLUTE, RELATIVE, FONTSIZE

Another attribute (that doesn't get saved) is OVERRIDE, which indicates that the SROW and SCOL (etc) settings in the OPEN statement are to be used even if NAME= is also specified. When OVERRIDE is specified in OPENDFLT, it only applies to the first OPEN of window #0. In all other cases Name= trumps SROW etc settings.

All of the above specifications apply to Window zero except it cannot be
opened RELATIVE.

"NOMAXIMIZE" also removes the maximize button from the window.

"NO_TASK_BAR" suppresses the task bar icon. This feature
is available on any window.

"MODAL" uses the same task bar icon as it's parent window. This ignores
any clicks on its parent window.

===Input Across Multiple Windows===
As of 4.3, BR allows for input across multiple windows, as in the following example:

00010 (R)INPUT FIELDS #121: “10, 10, C 20, UH; 10, 12, PIC(##/##/##), UH;#124,10, 10, C 30, UH”: aaa$, bbb$, ccc$

This will input the first two fields on window #121 and the third field on window #124. The ‘#window-number,’ prefix may appear in any row or col FIELDS specification and overrides the window number that follows the PRINT/INPUT/RINPUT keyword.

===Syntax===
[[Image:Openwindow.png|900px]]

===Defaults===
:1.) No border.
:2.) N (normal).
:3.) No caption.
:4.) Center caption.
:5.) Interrupt the program if an error occurs and ON is not active.
:6.) N (normal).

===Parameters===
"Wind-num" is a file number for the window being opened. It must be a numeric expression or integer that equals a value from 1 to 999, inclusive. No other open file or open window may use the same value. Open windows do not count against the operating system limit on open files.

From this point, there are two possible paths through the OPEN window syntax. The top path will be described first.

The "SROW = row" parameter identifies the starting row for the window. The "row" portion of this parameter can be any integer within the size of the main BR window. If a border is specified for the window, it must be 1 more than the desired starting place, to account for a one row border. The value of "row" cannot exceed the value of the ending row.

The "SCOL = column" parameter identifies the starting column for the window. The "column" portion for this parameter can be any integer within the size of the main BR window. If a border is specified for the window, it must be 1 more than the desired starting place, to account for a one colomn border. The value of "column" cannot exceed the value of the ending column.

The "EROW = row" parameter identifies the ending row for the window. The "row" portion of this parameter can be any integer (unless a border is specified for the window -then the value must be one less than the desired ending row, to account for a one row border) It cannot precede the starting row value.

The "ECOL = column" parameter identifies the ending column for the window. The "column" portion of this parameter can be any integer (unless a border is specified for the window-then the value must be one less than the desired ending column, to account for a one column border) It cannot precede the starting column value.

The optional "ROWS=int" parameter can be used instead of either "SROW=row" or "EROW=row" to specify the number of rows desired (instead of a specific starting or ending row).

The optional "COLS=int" parameter can be used instead of either "SCOL=col" or "ECOL=col" to specify the number of columns desired (instead of a specific starting or ending column).

Note that when opening a #0 window, only "ROWS=int" and "COLS=int" parameters are necessary, the others are not. See [[Parent=None]] for more information.

To specify a border, see the discussion on the supplemental BORDER=Spec syntax and parameters below.

Otherwise, continuing with the main syntax for OPEN window, the next available parameter is "N=attributes". This parameter identifies the attributes that are to affect the entire inner portion of the window. However, the attribute specified takes effect only after a PRINT NEWPAGE has been sent to the window. The B (blink) attribute is not available for this parameter.

"ABSOLUTE" and "RELATIVE" qualify SROW and SCOL to specify the position of a new independent window. RELATIVE (the default) indicates positioning relative to window zero (the main console), and ABSOLUTE indicates positioning relative to the screen. Using negative values positions an independent window to the left of or above the main console. BR will attempt to honor the request keeping the new window viewable up to the maximum size of the screen. Window zero ositioning is always ABSOLUTE. To position a window on a second monitor, specify a starting position to the right of the last position of the first monitor.

The "CAPTION=" keyword is used to identify text that is to appear in the top border of the window. It may optionally be followed by either a less-than (<) symbol for flush left text or a greater-than (>) symbol for flush right text. When no symbol is specified, the text is centered. The "title" parameter represents the text that is to be displayed.

All of the parameters described above (excluding the wind-num parameter) comprise the file definition string. The alternative to coding these parameters directly in the OPEN window statement is to reference them with the "string expression" parameter found in the bottom path of the syntax diagram.

No matter which path you choose for providing the file definition, two of the remaining parameters in the syntax diagram must be included in your OPEN window statement. "DISPLAY" identifies the window file as a display file, and one of the "INPUT", "OUTPUT" or "OUTIN" parameters must be used to indicate how the window will be used.

The "error-cond line-ref" parameter allows for error processing. See [[Error Conditions]] for more information.

===Supplemental Syntax ("BORDER= spec")===
{{:BorderSpec}}

===Technical Considerations===
:1.) Relevant error conditions are: [[ERROR]], [[EXIT]] and [[IOERR]].
:2.) Open window files do not count against your operating system limit on open files.
:3.) Using [[CONFIG]] SCREEN N xx to change the normal attribute of a window will only take affect on windows that are opened after the CONFIG SCREEN specification is executed. This applies only to the N (normal) attribute.
:4.) Unix / Linux terminals - See [[Terminal Consideration]] for special considerations when using windows with Unix / Linux terminals.
:5.) SROW and SCOL are based on FONTSIZE.

<noinclude>
[[Category:Statements]]
[[Category:Window File Processing Statements]]
</noinclude>

Syntax

2013-02-04T19:04:50Z

66.17.154.248: /* Syntax Diagrams */

==Parts Of A Business Rules Statement==

===Statements (Immediate Mode/Procedure Files)===

A typical [[Business Rules!]] statement consists of the following:
#A [[line number]].
#A [[line label]] (optional).
#A primary keyword.
#One or more secondary keywords or phrases along with their associated values (sometimes optional).
#One or more "error-cond line-ref" conditions (optional).
#Remark or comment (optional).

"Optional" items may be included but are not required.

Notice that the listed elements refer to a typical statement. Some statements consist mainly of a primary keyword [[RETURN]] or [[RETRY]] for instance, only the line number and optional programmer's remarks or a line label are permitted with these two statements. See the syntax diagrams for each [[Statements|Statement]] for specific details.

====Analysis of an Example Statement====

The following formatted Print statement will be used to describe the components of a statement:

00020 BIG: PRINT USING F1: A$,T(5) CONV 00520 ! remarks

{|
|-valign="top"
|width="10%"|'''00120'''||is a line number.
|-valign="top"
|width="10%"|'''BIG'''||is a line label.
|-valign="top"
|width="10%"|'''PRINT'''||is a primary keyword. Primary keywords specify the type of operation that you wish to perform.
|-valign="top"
|width="10%"|'''USING F1'''||is a secondary phrase. This phrase consists of the secondary keyword USING and the line reference F1 (a line label). Secondary keywords and secondary phrases add detail to the instructions in the statement.
|-valign="top"
|width="10%"|'''A$ and T(5)'''||are references to [[Variable|variables]].
|-valign="top"
|width="10%"|'''CONV 520'''||is an "error-cond line-ref" specification. It transfers control of the program to line 00520 if a CONV error occurs during execution of line 00120.
|-valign="top"
|width="10%"|'''! remarks'''||is an optional comment that follows the statement. An exclamation point signals the start of this remark; any comment the programmer wishes to make may follow. Note that certain statement keywords, for example, [[DATA]], do not allow for comments on the same line, in which case comments must be placed on an adjacent line alone.
|-valign="top"
|}

Each command in a procedure file may be followed by at least one space, an exclamation point (!) and a comment. Business Rules will ignore everything after the exclamation point.

Remarks may also reside on their own line in a procedure file, as follows:

LOAD MENU.BR
! Load the program MENU.BR
RUN

====Line labels - Procedure Files====

{{:Line Label (procedure)}}

====Line numbers====

{{:Line number}}

====Line labels - Program files====

{{:Line Label (program)}}

====Multiple statements====

{{:Multiple statements}}

====Line Continuation====

{{:Line Continuation}}

====Comments====

{{:Comment}}

===Syntax Diagrams===

Diagrams are used throughout this manual to explain the syntax of Business Rules commands, statements, and various other syntactical specifications. This section explains how to read the conventions used in the diagrams.

Syntax diagrams provide a road map through a command or statement's syntax. Following the main line of the diagram will eventually bring you to the end of the syntax, although you may wish to take allowable detours to obtain certain features. Syntax diagrams always follow a logical pattern.

If they require you to pass through a particular parameter, then that parameter is required. If they allow you to bypass a particular parameter, then that parameter is optional.

Although all syntax diagrams (whether for a command, statement or other specification) must be read the same way, the actual specification you are working with may be subject to other requirements or options as well. A statement, for example, must always reside on a line with a line number. See the parts at the end of this section for information about these additional requirements and options.

The "array-name" parameter is a name representing either a numeric or a string [[array]]. For rules regarding these names, see [[Variable]].

The "BAUD" parameter sets the transmission speed in bits per second. See the [[Open communications]] statement for details.

The "BORDER=spec" parameter represents an insertable syntax which is used in the OPEN window statement to identify a border type for the window being opened. See the OPEN window statement for additional information and the syntax diagram.

The [[BUFSIZE]] parameter specifies the size of the buffer for DOS versions of Business Rules. The default is 2000 bytes, which is low for high-speed data transmission. To avoid losing data with rates of 2400 bps or higher; an increased BUFSIZE is recommended.

In Business Rules, Unix and Linux versions ignore the BUFSIZE parameter, as the operating systems handle the buffering for these versions instead.

"Column" (not to be confused with "columns") is an integer {\b value} from 1 to 80, which indicates a column number on the screen.

"Columns" (not to be confused with "column") is an integer {\b constant}, which indicates the maximum size for the second through seventh dimensions of an array.

Concatenation is the joining of two or more strings. In Business Rules, the ampersand (&) is the concatenation operator. Concatenation may be used in any output or assignment statement to join any number of string expressions.

In the following example, lines 100 and 110 illustrate the concatenation of three strings. Lines 120 and 130 use concatenation and the string functions RTRM$, LTRM$ and RPT$ to print and center X$ on the 80-column screen:

00100 LET LINE$ = A$ & B$ & C$
00110 PRINT RTRM$(CITY$) & ", " & STATE$
00120 LET X$ = RTRM$(LTRM$(X$))
00130 PRINT RPT$(" ",(80-LEN(X$))/2) & X$

The printing and centering in lines 120 and 130 can be performed more efficiently with the CC format specifications as follows:

00140 PRINT USING 150: X$
00150 FORM CC 80

The "corners" parameter is used to specify custom-designed borders for both I/O windows and field help windows. Two characters must be specified for this parameter: the character to be used for the top left corner of the window and the character to be used for the bottom right corner of the window. Business Rules fills in the rest of the characters for you

"Drive" is a DOS-like drive letter, which must be followed by a colon. The drive parameter may specify certain special devices such as a printer or modem.

"Drive-num" is a digit, which indicates a System/23 drive; Business Rules translates it into a DOS drive letter. This parameter may not be specified with a redirection symbol (>) or when a drive letter is specified.

The "error-cond line-ref" parameter is replaced with one or more pairs of specifications. "Error-cond" is a specific error condition and "line-ref" is a line number or line label to which control should be transferred if that error occurs. See the Error Conditions chapter for more information about the various error conditions.

"Field-length" is an integer value, which identifies the number of columns in the specified field. This parameter is required as a part of any numeric format specification except PIC.

"Field-spec" represents an insertable syntax that is used to provide field definitions for the full screen processing statements. For additional information and a syntax diagram, see the Screen I/O chapter.

====Filenames====
"Filename" is a name consisting of up to eight alphabetic, numeric or underscore characters and an optional period and extension of up to three consecutive letters. Wildcard characters (* and ?) may be used in file names specified with the COPY, DIR, DROP, and FREE commands. Version 3.9 will support long filenames (greater than the 8.3 format) with a variety of alternatives with respect to case sensitivity. Unix defaults to case sensitive, and DOS/Windows defaults to case insensitive. Business Rules! defaults to lower case on all platforms, unless overridden by a FILENAMES configuration statement.

The file name requirements for all types of files are identical. However, one item to be aware of is that procedure files which use an extension of .$$$ will automatically delete themselves after closing. See the Procedures chapter for additional information.

"File-num" is a numeric expression or an integer that equals 255 or any number from zero to 127. A file number matches a logical file to a physical file or device. File numbers are defined in OPEN statements, then used in I/O statements for that file or device.

Two special file numbers which do not require OPEN statements are 0 (for input or output to the screen) and 255 (for output to the printer).

No file numbers are required when INPUT, LINPUT, RINPUT, or PRINT are used for I/O from the keyboard or to the display screen. File-num is always immediately preceded by a pound symbol (#).

The ">file-ref" parameter causes all information which would normally be printed on the screen to be sent to the file specified in the file-ref (see the "file-ref description for information about the correct syntax). One special case is the RUN command in which ">file-ref" redirects printer output to a file. Wherever ">file- ref" is indicated, ">>file-ref" (with two redirection arrows) may also be specified.

Using one redirection arrow causes the screen information to write directly over any contents that currently exist in the specified file. Using two redirection arrows cause the information that would normally go to the screen to be appended to the end of the specified file. The TYPE command with the >>file-ref parameter may thus be used to append a display file to another file. Likewise, the LIST command may be used with >>file-ref to append the contents of a program to another program which has been saved in source.

(Be careful about line numbers when using this technique, as line numbers that are duplicated in the same file will replace one another upon loading from source.)

Fixed-point numbers are numbers with a decimal point in a fixed position.

"Floating point form-spec" represents a format specification from the following group: D, S, or L. These format specifications are fast, but non-portable. See the File I/O chapter for more information.

Floating-point numbers are numbers, which allow the decimal point to "float" to any position. The Business Rules syntax is nEm, where n is a numeric constant indicating the sign and significant digits in the number, E represents base 10, and m is a signed integer representing the power to which 10 is raised.

The largest and smallest numbers available to the system vary according to the hardware and operating system being used. The system function INF can be used to print the largest possible number on any given system; 1/INF generates the smallest number. For all DOS, Unix and Linux versions available at the time of writing, the largest number is 1.000E+307; similarly, the smallest number is 1.000E-307. Some caution should be used in working with numbers near these extremes (e.g., using exponential notation in SORT). Also, for any given combination of hardware and Business Rules, the system infinity function INF and some testing should be combined to determine whether or not intermediate values used in calculations will be truncated.

The "fraction-length" parameter is an integer value that identifies the number of digits contained in the fractional portion of the item to be printed or input. This integer must be preceded by a decimal point.

"Wind-num" is the number of a window file that has been opened by an OPEN window statement. It must be a numeric expression or integer value that equals a value between 1 to 127. No other open file or open window may use the same value. Open windows do not count against the operating system limit on open files.

Wildcard characters (? and *) may be used in file names and extensions in place of alphabetic or numeric characters. They may not be used in drive, path, or directory specifications. They have the following meanings:
{|
|-valign="top"
|width="10%"|'''?'''||means that any character in that position (including null) is regarded as a match.
|-valign="top"
|width="10%"|'''*'''||denotes any number of ? characters.
|-valign="top"
|}
 
;Example:

A:VOL\NAME?.*

The above references all files in subdirectory VOL on drive A with a name consisting of NAME followed by any one character, a period, and any extension.

A "var-name" may be either numeric or string. It may be a subscripted or un-subscripted variable, or an array name preceded by MAT. Var-name items are used mainly in various types of input statements to assign values to variables. They typically occur in lists separated by commas.

The "string form-spec" parameter should be replaced with a string format specification from the following group: C, CC, CR, CL, CU, G, GL, GU, V, VL, VU. The specifications that are applicable for a given statement are identified in the parameters text for that statement. See the File I/O chapter for information about individual format specifications.

The CL, CU, GL, GU, VL, and VU specifications are valid only in full screen processing statements (PRINT FIELDS, INPUT FIELDS, and RINPUT FIELD); they cannot be used in either type of FORM statement.

The "string-expr" parameter represents one of several kinds of string elements, including string system functions, string user-defined functions, string constants, and string variables. See the definitions in this chapter for more information about string constants and string variables. See the Functions chapter for more information about string system functions. See the DEF statement discussion for more information about user-defined functions.

In addition to the four elements listed above, string expressions may utilize substring operators (to specify that only a portion of the string be used) and the concatenation operator (to specify that multiple string expressions be combined together). See the definitions for "Substring operation" and "concatenation operation" in this chapter for more information.

The "helpstring" parameter represents an insertable syntax, which is used in the full screen processing statements to specify the user level; window placement and text for field help windows. For additional information and a syntax diagram, see the Screen I/O chapter.

The "increment" parameter is used in the AUTO ATT and RENUM commands. It represents an integer value, which indicates how much the system should increase the numbers from one line number to the next.

The "INPUT" keyword identifies that the file is to be opened so that its data may only be used as input for the program.

The "int" parameter represents an unsigned, positive, non-zero whole number.

The "integer" parameter represents a whole number (no decimal points or fractions allowed). NOTE the difference between "integer" and "int".

The "internal form-spec" parameter should be replaced with a format specification from the following group: B, BL, BH, PD, ZD. See the File I/O chapter for information about individual format specifications.

The "key-length" parameter should be replaced with a number that identifies the number of characters (or columns) in the key.

"Key start-pos" indicates the record position of the first key character for the index.

"Length" is an integer value that sets the maximum length of all elements in the string variable or array.

A line label is an optional name for a program line that is specified immediately after the line number. It must be unique (no other line can be given the same line label), and it must be followed by a colon when it is defined. This line label can then subsequently be used in place of a line number to reference the line from a secondary expression. Business Rules allows most statement and command keywords to be used as line labels.

In the following example, the line label BIG is defined to represent line 120; it is then used as a line reference for the GOTO statement in line 300:

00120 BIG: PRINT USING F1: A$,T(5) CONV
o
o
o
00300 GOTO BIG

For information about the labels that are used in procedures, See the Procedures chapter.

The "line-num" parameter indicates that you must specify a line number rather than a line label. Line numbers can be used only in programs (not in procedure files) and must be integers from 1 to 99999.

The "line-ref" parameter indicates that you can specify either a line number or a line label as a parameter.

"Num-array" indicates that a numeric array name should be specified.

The "num-constant" parameter represents a number consisting mainly of the digits 0-9; other optional elements are a decimal point (.), a minus sign (-) to indicate a negative number, and a plus sign (+) to indicate a positive number (unsigned numbers are assumed to be positive). If a sign is specified, it must precede the digits. Spaces are not allowed in a numeric constant.

Integers, fixed-point numbers and floating point numbers (numbers in exponential notation) are three types of numeric constants. See the following examples:

;Number: 
:44 
:+15.38 
:-86.34 
:10,000 
;Integer: 
:44 
:n/a 
:n/a 
:10000 
;Fixed Point: 
:44 
:+15.38 
:-86.34 
:10000 
;Exponential: 
:4.4E+1 
:1.538E+1 
:-8.634E+1 
:1E+4

The "num-expr" parameter represents one of five kinds of numeric elements: conditional expressions, numeric constants, numeric variables, numeric system functions, and numeric user-defined functions. See the definitions in this chapter for more information about conditional expressions, numeric constants and numeric variables. See the Functions chapter for more information about numeric system functions. See the DEF statement discussion for more information about user-defined functions.

"Num-var" is a name that a programmer assigns to a storage location in the computer's memory; it is used for storing a number. Variables are created by being referenced in expressions or by being specified in the DIM statement. When used in numeric expressions, numeric variables can be either subscripted or un-subscripted. When specified in syntax diagrams in this book, however, num-var must be a simple (i.e., un-subscripted) variable name -except when stated otherwise in the "parameters" section for the specific statement.

A numeric variable name can be 1-30 alphanumeric characters and underscores, the first of which must be a letter. Examples of simple numeric variable names include A5, TOTAL, RATE, and EMPLRATE.

The same character sequence may be used as a name for both a variable (scalar) and an array. By adding a $ on the end, the same character sequence may be used for a string variable and a string array. Thus A, MAT A, A$, and MAT A$ all may co-exist in the same program.

Certain words are reserved by Business Rules, and cannot be used as variable names. Note that all words starting with the letters "FN" are reserved, as they are considered user-defined function names. See also [[Reserved Words]].

The "num form-spec" parameter should be replaced with a numeric format specification from the following group: G, GZ, N, or NZ. The specifications, which are applicable for a given statement, are identified in the parameters text for that statement. See the File I/O chapter for information about individual format specifications.

The "OUTIN" keyword indicates that the file is to be opened so that information may move in two directions: both into and out of the data file.

The "OUTPUT" parameter indicates that the file is to be opened so that information may only be output from the program to the file.

"PARITY=spec" is an OPEN communications parameter. The "PARITY" keyword and equal symbol (=) must be followed by one of three replacements for "spec": N (no parity checking), E (even parity) or O (odd parity).

The "path" parameter identifies the sequence of directories to be used. Each directory must be separated by a backslash "\\". When the path does not begin with a backslash, searching begins at the default directory.

The PIC format specification converts a number into characters according to the picture specified. The "pic-spec" parameter is the picture, and consists of one or more characters, which are either insertion characters to be printed as is, or digit identifiers to be replaced with a digit when printed. See the File I/O chapter for information about PIC and individual insertion characters and digit identifiers.

"Row" is an integer value from 1 to the number of rows in the screen or window that indicates a row number

"Rows" (not to be confused with "row") it is an integer constant which indicates the maximum size for the first dimension of an array.

"String-array" indicates that a string array name should be specified. For rules regarding these names, see "string variable" in this chapter.

A string constant is a series of characters enclosed in quotation marks. Each constant may contain from 0 to 250 characters.

Quotation marks are used as delimiters in string constants. They signal the beginning and end of a string. You may use either single or double quotation marks. If the enclosed string contains one kind of quotation mark, however, you must either use the other kind as a delimiter or express the inner quotation mark as a pair. Examples of string constants are: 

"Montana"
'Montana'
'The "Big Sky" Country'
"The ""Treasure"" State"

Note that in a "LIST" command single quotes represent case insensitive searching while double quotes represent case sensitive matching.

====Quote Processing====
Quotation marks suppress the recognition of separators in accordance with the following rules.
Standard BR Quote Processing
When examining str$ left to right, the first character (and the first character after each separator) is checked to see if is either (') or ("). If it is ether of those then it activates quotation processing which suppresses the recognition of separators until quotation processing is deactivated. The first character thus becomes the governing quote type until quotation processing is deactivated.

The string is copied until it ends or until an odd number of successive occurrences of the governing quote type is encountered. During this processing, two adjacent occurrences of the governing quote character denote an embedded occurrence of the quote character.
Examples
"abc,def" -> abc,def where the comma is not recognized as a separator and is part of the data
abc"def -> abc"def naturally embedded quotes may occur anywhere within a string after the first character
"abc"def" -> abcdef" quotation processing is deactivated by the center quote mark
"abcdef" -> abcdef normal data
"abc'def" -> abc'def the single quote is treated like any other character while double quotes govern
'abc"def' -> abc"def double quotes are treated like any other character while single quotes govern
"abc""def" -> abc"def pairs of governing quotes denote a single embedded quote
"abc"""def" -> abc"def" the third successive occurence deactivates quote processing

MAT2STR( MAT zzz$, str$ [, sep$ [, flags$]] )
Where flag$ is in the format:
[ quote-type ] [ :LTRM ] | [ :TRIM ] | [ :RTRM ]
Where quote-type can be Q, QUOTES, ('), or ("), case insensitive. Quote-type denotes that each element should be enclosed in quotation marks. The trim flags denote pre-processing of array elements and the leading colon is only present when quote-type is specified.
If Q or QUOTES is specified the BR automatically determines which quote type to apply as follows:
The element is scanned left to right for either type of quote character. If a quote character is encountered, then only the next character is examined. If two occurrences of the same quote character are encountered then that character is used to enclose the element. However, if a single occurrence of a quote character is encountered then the element is enclosed in the alternate quote type. If no quote character is encountered then double quotes are applied.
Examples
Quote Type is Q or QUOTES
abcdef -> "abcdef"
abc'def -> "abc'def"
abc"def -> 'abc"def'
abc""def -> "abc""def"
'abcdef -> "'abcdef"

Quote Type is ' ( quote type single )
abcdef -> 'abcdef'
'abcdef -> '''abcdef' single quotes get doubled when embedded in singles quotes
"abcdef -> '"abcdef' leading double quote is treated normally

Quote type double mirrors quote type single.
When using MAT2STR on a 2 dimensional array, the first delimiter is used for individual elements and the second delimiter at the end of each row. This principle also applies to three to seven dimensions.
Example
Given the following two dimensional array zzz$ containing the values-
1 2
3 4

The following statements-
10 Sep$(1)=","
20 Sep$(2)=hex$("0D0A") ! CRLF
30 MAT2STR( MAT zzz$, str$, MAT Sep$ )
40 PRINT str$

Will produce-
1,2
3,4

[[Category:BR Manual]]
[[Category:Statements]]
[[Category:Manual Vol 1]]
[[Category:BR Manual Chapter 1]]

Open Window

2013-02-04T19:04:16Z

66.17.154.248:

See also: [[Parent=None]] and [[Picture]]

The '''OPEN window''' (OPE) [[statement]] specifies the characteristics for a window and activates the window for input/output. OPEN window can specify the following window characteristics: screen placement and dimensions, border type and attributes, attributes to be used for the text area of the window, and a caption to be displayed within the top border of the window.

:1.) When a file is opened for both SHR and INPUT, Business Rules will no longer change the time and date of the file. As a result of this change, when a file is to be opened both for OUTIN and for INPUT, the OPEN for OUTIN must be executed first. Otherwise an error [[0608]] will result. This will affect current programs.
:2.) The OPEN window statement now allows for flexibility in the specification of window coordinates. Previously all four coordinates of the window had to be specified in terms of two exact row positions and two exact column positions. With release 3.50, only one exact row position and one exact column position must be specified. Business Rules will automatically calculate the other row and/or column position according to the values of the ROWS= and COLS= parameters, which indicate the desired length or width of the window.

The ROWS= parameter may be used in place of either the SROW= or the EROW= parameter, but not both. Likewise, the COLS= parameter may be used in place of either the SCOL= or the ECOL= parameter, but not both. The following examples show some of the possibilities that are available using this syntax option. Each statement opens a 10 row by 10 column window in the upper left corner of the screen. (NOTE: ROWS= and COLS= parameters are shown in lowercase for emphasis; case makes no difference in actual syntax.)

00010 OPEN #1:"rows=10,cols=10,EROW=10,ECOL=10",DISPLAY,OUTPUT
00020 OPEN #1:"rows=10,SCOL=1,EROW=10,cols=10",DISPLAY,OUTPUT
00030 OPEN #1:"rows=10,SCOL=1,EROW=10,ECOL=10",DISPLAY,OUTPUT
00040 OPEN #1:"SROW=1,cols=10,rows=10,EROW=10",DISPLAY,OUTPUT
00050 OPEN #1:"SROW=1,cols=10,EROW=10,ECOL=10",DISPLAY,OUTPUT
00060 OPEN #1:"SROW=1,SCOL=1,rows=10,cols=10",DISPLAY,OUTPUT
00070 OPEN #1:"SROW=1,SCOL=1,rows=10,ECOL=10",DISPLAY,OUTPUT
00080 OPEN #1:"SROW=1,SCOL=1,EROW=10,cols=10",DISPLAY,OUTPUT

:3.) The OPEN window statement's BORDER parameter now accepts S (drop-shadow) as an attribute for the border. See "S Attribute" in the [[BRConfig.sys]] Specification section for more information.
:4.) The NOCLOSE parameter in any OPEN statement will leave that file open when a program ends or chains to another program. The only way this file is closed is by explicitly closing the file, CLEAR ALL, or by exiting from Business Rules.

00010 OPEN #1:"NAME=TEST,NOCLOSE",INTERNAL,RELATIVE,INPUT

===Comments and Examples===
Business Rules creates two different types of windows: windows that are opened as separate input/output files, and field help windows. The OPEN window statement allows you to create the first type, windows that accept input and output. For information about field help windows, see [[Screen I/O]].

Windows can also be opened separately from the main window. OPEN #0 is reserved for this. Also see [[Parent=Window]] for more information.

Regarding window size : (as of 4.3) when opening separate windows, 'NAME=window-name' indicates that BR is to save the position of the window at the time it is closed and restore it to that position when it is reopened, even across sessions. Replacement or overlaying windows can use the same window names to position themselves wherever and at whatever character size the user has changed it to. So once a window has been opened with a particular name, subsequent opens ignore ROW= and COL= and instead use the user positioned values.

As a result window positioning and size priority is as follows:
:1. NAME= window-name
:2. (for window zero only) un-named save font size and position.
:3. SROW, SCOL, MAXIMIZE, NOMAXIMIZE, ABSOLUTE, RELATIVE, FONTSIZE

Another attribute (that doesn't get saved) is OVERRIDE, which indicates that the SROW and SCOL (etc) settings in the OPEN statement are to be used even if NAME= is also specified. When OVERRIDE is specified in OPENDFLT, it only applies to the first OPEN of window #0. In all other cases Name= trumps SROW etc settings.

All of the above specifications apply to Window zero except it cannot be
opened RELATIVE.

"NOMAXIMIZE" also removes the maximize button from the window.

"NO_TASK_BAR" suppresses the task bar icon. This feature
is available on any window.

"MODAL" uses the same task bar icon as it's parent window. This ignores
any clicks on its parent window.

===Input Across Multiple Windows===
As of 4.3, BR allows for input across multiple windows, as in the following example:

00010 (R)INPUT FIELDS #121: “10, 10, C 20, UH; 10, 12, PIC(##/##/##), UH;#124,10, 10, C 30, UH”: aaa$, bbb$, ccc$

This will input the first two fields on window #121 and the third field on window #124. The ‘#window-number,’ prefix may appear in any row or col FIELDS specification and overrides the window number that follows the PRINT/INPUT/RINPUT keyword.

===Syntax===
[[Image:Openwindow.png|900px]]

===Defaults===
:1.) No border.
:2.) N (normal).
:3.) No caption.
:4.) Center caption.
:5.) Interrupt the program if an error occurs and ON is not active.
:6.) N (normal).

===Parameters===
"Wind-num" is a file number for the window being opened. It must be a numeric expression or integer that equals a value from 1 to 999, inclusive. No other open file or open window may use the same value. Open windows do not count against the operating system limit on open files.

From this point, there are two possible paths through the OPEN window syntax. The top path will be described first.

The "SROW = row" parameter identifies the starting row for the window. The "row" portion of this parameter can be any integer within the size of the main BR window. If a border is specified for the window, it must be 1 more than the desired starting place, to account for a one row border. The value of "row" cannot exceed the value of the ending row.

The "SCOL = column" parameter identifies the starting column for the window. The "column" portion for this parameter can be any integer within the size of the main BR window. If a border is specified for the window, it must be 1 more than the desired starting place, to account for a one colomn border. The value of "column" cannot exceed the value of the ending column.

The "EROW = row" parameter identifies the ending row for the window. The "row" portion of this parameter can be any integer (unless a border is specified for the window -then the value must be one less than the desired ending row, to account for a one row border) It cannot precede the starting row value.

The "ECOL = column" parameter identifies the ending column for the window. The "column" portion of this parameter can be any integer (unless a border is specified for the window-then the value must be one less than the desired ending column, to account for a one column border) It cannot precede the starting column value.

The optional "ROWS=int" parameter can be used instead of either "SROW=row" or "EROW=row" to specify the number of rows desired (instead of a specific starting or ending row).

The optional "COLS=int" parameter can be used instead of either "SCOL=col" or "ECOL=col" to specify the number of columns desired (instead of a specific starting or ending column).

Note that when opening a #0 window, only "ROWS=int" and "COLS=int" parameters are necessary, the others are not. See [[Parent=None]] for more information.

To specify a border, see the discussion on the supplemental BORDER=Spec syntax and parameters below.

Otherwise, continuing with the main syntax for OPEN window, the next available parameter is "N=attributes". This parameter identifies the attributes that are to affect the entire inner portion of the window. However, the attribute specified takes effect only after a PRINT NEWPAGE has been sent to the window. The B (blink) attribute is not available for this parameter.

"ABSOLUTE" and "RELATIVE" qualify SROW and SCOL to specify the position of a new independent window. RELATIVE (the default) indicates positioning relative to window zero (the main console), and ABSOLUTE indicates positioning relative to the screen. Using negative values positions an independent window to the left of or above the main console. BR will attempt to honor the request keeping the new window viewable up to the maximum size of the screen. Window zero ositioning is always ABSOLUTE. To position a window on a second monitor, specify a starting position to the right of the last position of the first monitor.

The "CAPTION=" keyword is used to identify text that is to appear in the top border of the window. It may optionally be followed by either a less-than (<) symbol for flush left text or a greater-than (>) symbol for flush right text. When no symbol is specified, the text is centered. The "title" parameter represents the text that is to be displayed.

All of the parameters described above (excluding the wind-num parameter) comprise the file definition string. The alternative to coding these parameters directly in the OPEN window statement is to reference them with the "string expression" parameter found in the bottom path of the syntax diagram.

No matter which path you choose for providing the file definition, two of the remaining parameters in the syntax diagram must be included in your OPEN window statement. "DISPLAY" identifies the window file as a display file, and one of the "INPUT", "OUTPUT" or "OUTIN" parameters must be used to indicate how the window will be used.

The "error-cond line-ref" parameter allows for error processing. See [[Error Conditions]] for more information.

===Supplemental Syntax ("BORDER= spec")===
{{:Borderspec}}

===Technical Considerations===
:1.) Relevant error conditions are: [[ERROR]], [[EXIT]] and [[IOERR]].
:2.) Open window files do not count against your operating system limit on open files.
:3.) Using [[CONFIG]] SCREEN N xx to change the normal attribute of a window will only take affect on windows that are opened after the CONFIG SCREEN specification is executed. This applies only to the N (normal) attribute.
:4.) Unix / Linux terminals - See [[Terminal Consideration]] for special considerations when using windows with Unix / Linux terminals.
:5.) SROW and SCOL are based on FONTSIZE.

<noinclude>
[[Category:Statements]]
[[Category:Window File Processing Statements]]
</noinclude>

Border Spec

2013-02-04T19:00:55Z

66.17.154.248: Created page with "The "BORDER=spec" parameter represents an inserable syntax that specifies the visual characteristics of the window border, within the Open Window statement. The BORDER= ke..."

The "BORDER=spec" parameter represents an inserable syntax that specifies the visual characteristics of the window border, within the [[Open Window]] statement. The BORDER= keyword must be followed by one of four border specifications (as of 4.3 these work with CON GUI ON as well).

===Syntax===
[[image:Borderspec.png]]

===Parameters===
*"B" indicates that the border is to be blank;
*"D" indicates a double-line border;
*"H" indicates that a shadowed or highlighted border be used;
*and "S" indicates that a single-lined border be used.
"Corners" and "8 chars" border specifications may be used for custom-designed window borders. See [[Screen I/O]] for illustrations and more information about border types and border graphics specifications. However, as of 4.3, Border=H and "8 chars" are no longer supported except that a new [[Option (Config)|OPTION]] 62 permits S, D, B, H or an eight character string followed by a colon and then attributes. For example:
BORDER=S|D|B|H|8-chars[:attributes]
While the colon is actually optional, it is recommended for readability when attributes are included.

Also within the BORDER= syntax, the "attributes" parameter may be specified immediately after the border specification (no spaces). The attributes specified here will affect the visual display of the border itself. See [[Definitions]] for the correct syntax to be used with the "attributes" parameter.

Line Continuation

2013-02-04T18:49:25Z

66.17.154.248:

An '''!:''' in Business Rules! code performs a '''line continuation'''.

More than one clause (or [[statement]]) can reside on a single [[line]] when the statements are separated by a colon (:). When the statements are separated by both an exclamation point and a colon (!:), Business Rules will list them to separate physical lines, even though they continue to belong to the same line number. Each portion of a line seperated by an !: is referred to as a ''sub-line''.

[[Paragraph labels]] following line continuations are not allowed. However they are allowed following a subline [[comment] out ([[!]]), for example:

00010 TOP: ! !:
Print Newpage

<noinclude>
[[Category:Statements]]
[[Category:Terminology]]
[[Category:Basics]]
</noinclude>

Return

2013-02-03T21:03:09Z

66.17.154.248: Created page with "The '''Return (RETU)''' statement works in conjunction with the GoSub statement. After execution of a subroutine, RETURN transfers control back to the statement immedi..."

The '''Return (RETU)''' [[statement]] works in conjunction with the [[GoSub]] statement. After execution of a subroutine, RETURN transfers control back to the statement immediately following the most recently executed [[GOSUB]].

===Comments and Examples===
RETURN is required at the end of every subroutine. In the following example, the subroutine in line 5000 is repeated several times throughout the program. Each time the subroutine finishes executing, RETURN transfers control back to the first executable statement after the calling GOSUB.

00100 GOSUB 5000
o
o
o
05000 PRINT "This is my subroutine"
05010 RETURN

===Syntax===

[[file:Return.png]]

<noinclude>
[[Category:Statements]]
[[Category:Branching Statements]]
</noinclude>