Library Facility - Revision history

Snafoo972: /* Turning an Existing Program into a Callable Library Function */

2023-04-17T19:14:36Z

Turning an Existing Program into a Callable Library Function

← Older revision		Revision as of 19:14, 17 April 2023
Line 315:		Line 315:
	: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.		: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 NOFILES~~, RELEASE~~, "MNTCUST" :FNMNTCUST		50000 LIBRARY RELEASE, NOFILES, "MNTCUST" :FNMNTCUST
	50010 LET FNMNTCUST		50010 LET FNMNTCUST

John: /* Implementation Considerations */

2017-05-15T18:46:59Z

Implementation Considerations

← Older revision		Revision as of 18:46, 15 May 2017
Line 47:		Line 47:
	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.		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.

	'''Functions work the same irrespective of how a library is loaded. However variables are cleared each time a RELEASE function is called and they are retained across program loads when a library is loaded resident and includes an OPTION RETAIN statement.'''		'''Functions work the same irrespective of how a library is loaded. However variables are cleared each time a RELEASE function is called and they are retained across program loads when a library is loaded resident and includes an [[OPTION]] RETAIN statement.'''

	===As needed Library===		===As needed Library===

Gordon.dye: /* Turning an Existing Program into a Callable Library Function */

2014-10-12T20:36:50Z

Turning an Existing Program into a Callable Library Function

← Older revision		Revision as of 20:36, 12 October 2014
Line 319:		Line 319:

	The NOFILES specification (BR release 4.3 and later) lets the library have its own independent file system. That way there is no concern for file number conflicts. The MNTCUST program will perform file IO with the same file sharing rules it would have, had it been executed on a separate workstation.		The NOFILES specification (BR release 4.3 and later) lets the library have its own independent file system. That way there is no concern for file number conflicts. The MNTCUST program will perform file IO with the same file sharing rules it would have, had it been executed on a separate workstation.

			Files opened NOCLOSE by NOFILES libraries are opened as normal files. In
			such cases the NOCLOSE parameter is ignored.

	====Other====		====Other====

Gordon.dye: /* Error Processing */

2014-10-12T02:01:26Z

Error Processing

← Older revision		Revision as of 02:01, 12 October 2014
Line 326:		Line 326:
	==Error Processing==		==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:		If an error is not trapped in a library function, the error is reported back to the calling program. When that happens the following system variables are set:

	{\|		{\|

Gordon.dye: /* Turning an Existing Program into a Callable Library Function */

2014-10-12T01:58:58Z

Turning an Existing Program into a Callable Library Function

← Older revision		Revision as of 01:58, 12 October 2014
Line 294:		Line 294:
	Business Rules Library Facility makes it 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:		Business Rules Library Facility makes it 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.		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).		: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~~.		:b.) Add lines such as the following to the top of the program. Line 00030 should be replaced with the normal MNTCUST CHAIN statement to the menu.

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

Line 307:		Line 307:
	80000 FNEND		80000 FNEND

	:2.) Modify ORDERS as follows:		:d.) Change the normal main body CHAIN statement to GOTO the FNEND statement added in step c.

			2.) Modify ORDERS as follows:

	:a.) Change the screen to include a label that identifies the operation of the F4 key.		:a.) Change the screen to include a label that identifies the operation of the F4 key.
Line 313:		Line 315:
	: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.		: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		50000 LIBRARY NOFILES, RELEASE, "MNTCUST" :FNMNTCUST
	50010 LET FNMNTCUST		50010 LET FNMNTCUST

			The NOFILES specification (BR release 4.3 and later) lets the library have its own independent file system. That way there is no concern for file number conflicts. The MNTCUST program will perform file IO with the same file sharing rules it would have, had it been executed on a separate workstation.

	====Other====		====Other====

Gordon.dye: /* Tips for implementing Library Functions in Existing Applications */

2014-10-11T19:50:31Z

Tips for implementing Library Functions in Existing Applications

Show changes

Gordon.dye: /* Sample Program */

2014-10-11T19:41:47Z

Sample Program

← Older revision		Revision as of 19:41, 11 October 2014
Line 258:		Line 258:
	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.		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".		FNSEND opens a serial 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:		;MAIN PROGRAM:
Line 281:		Line 281:
	00020 !		00020 !
	00030 DEF LIBRARY, FNSEND(MESSAGE$*60)		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		00040 IF NOT COMM_OPENED THEN !:OPEN #40: "NAME=COM2:, FORMAT=ASYNC,BAUD=2400",DISPLAY, OUTIN !:COMM_OPENED = 1
	00050 PRINT #40: ~~MESSAGES~~$		00050 PRINT #40: MESSAGE$
	00060 FNEND		00060 FNEND
	00070 !		00070 !

Gordon.dye: /* Linkage */

2014-10-11T19:26:46Z

Linkage

← Older revision		Revision as of 19:26, 11 October 2014
Line 224:		Line 224:
	===Linkage===		===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.<br>~~		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 by the most recently executed LIBRARY statement establishing linkage to the function.
	~~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:		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:
Line 232:		Line 231:
	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.		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.)		In the following example, the functions FNRESLIB1 through FNRESLIB5 are explicitly linked to the library MAIN. When any of these functions are 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		50300 LIBRARY "MAIN":FNRESLIB1,FNRESLIB2,FNRESLIB3,FNRESLIB4,FNRESLIB5
			<br>

	;Unnamed		;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~~.		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 you have several libraries loaded and are not concerned with which library contains the desired function. An unnamed library statement '''must''' be used to establish linkage to perform callbacks to the main program for accessing or changing data in the main program.

	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.		When the unnamed method is used, Business Rules first searches the main program, then each library that is currently loaded (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 future calls to the same function will continue to utilize the same linkage until it is changed. Note that Business Rules does not search as-needed (RELEASE) libraries when using the unnamed method of establishing linkage. 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.		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.

Gordon.dye: /* Editing Active Libraries */

2014-10-11T19:06:53Z

Editing Active Libraries

← Older revision		Revision as of 19:06, 11 October 2014
Line 216:		Line 216:
	===Editing Active Libraries===		===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~~.		The LIST command displays the currently active program. This means if a program is interrupted while a library call is being processed, the LIST command will show the library program statements. If desired, use F9 to select another loaded program such as the main program, and then issue another LIST command or inspect variables in that module.

	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~~.		It is important to note that the only way to ''save changes'' made to a running library program is to list the library to a file and reload it from source later on. Because of this, it can be desirable to develop a new library function first within the main program. Then once you've completed the testing and debugging process, you can move it to a separate library and test it there.

			There is, however, another approach that can work. If you load the library program in a separate session, solely for the purpose of changing the stored program, and then test your changes by saving them in the extra session and restarting the main program, this can be a convenient way to change libraries. It only takes a few seconds to CLEAR PROC and rerun the main program. And the DEBUG breakpoints set in the library remain in effect until specifically cleared.

	===Linkage===		===Linkage===

Gordon.dye: /* Additional Processing Consideration */

2014-10-11T12:43:13Z

Additional Processing Consideration

← Older revision		Revision as of 12:43, 11 October 2014
Line 185:		Line 185:
	[[Image:Lib4.jpg]]		[[Image:Lib4.jpg]]

	==Additional Processing ~~Consideration~~==		==Additional Processing Considerations==

	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.		Alternate libraries can be interrogated with function key 9 during a program pause.

			Active procedures (scripts) 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.		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.		Main program functions can be called by libraries. These can even displace functions of the same name within the libraries. 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. 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.		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.
Line 203:		Line 205:
	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.		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.<br>		Updating a library (with the REPLACE command) has no effect on active application environments until the library is (re)loaded.<br>
	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 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 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.~~<br>~~		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.
	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. To avoid this problem, load your resident libraries before running application programs.

	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===		===Editing Active Libraries===