Why use procedure libraries ?
Using procedure libraries often improves the performance in accessing your compiled Progress programs, and can make it easier to manage deployment packages.
- A procedure library contains compiled Progress programs. i.e ".r" files.
- Progress OpenEdge applications that use compiled .r files search the native file system for the individual .r files whenever these files are referenced. For large applications, this results in large directories, longer search times for each R-code file, and many (expensive) open/close operations on each file as it is used. This can result in a noticeable performance cost for larger applications with many separate R-code files.
- Procedure libraries can be used to group many R-code files into a single file from which an OpenEdge client can read and execute R-code files. Having a single place to look for R-code files eliminates the large directory and open/close issues since the library can open once and allow for faster searches.
- There can be more than one active library since libraries are specified in the session's PROPATH (discussed later).
- When loading and executing r-code procedures from a Procedure Library, Progress opens only one file, the library itself, to access all of the r-code files in the library. Running from procedure libraries.pl's will give an application performance gain in the following ways:
- Fewer file open and close operations which means less filesystem overhead
- Less I/O and disk space used for the temporary files that are used to hold r-code segments that are swapped out of memory. R-code segments read in from a library will be reread from the same library instead.
OpenEdge Client component
The OpenEdge client can search for R-code files in a library.
- Libraries can be named as fully qualified file names, partially qualified file names, or as simple file names.
- All libraries must have a ".pl" extension.
- The library is typically made available by adding it to the PROPATH (see below).
- The PROPATH can contain a mixture of directory names and library names.
- If the PROPATH environment variable is changed during a PROGRESS session, then any libraries that appeared on the old PROPATH but not on the new one are closed. Any libraries that were on the old PROPATH and the new one remain open.
- Libraries are only opened as needed. If all requests for R-code files are satisfied by directories earlier on the PROPATH than any libraries, then no libraries are opened.
Additional ABL functionality is available to inspect procedure libraries, or to access libraries that are not on the PROPATH :
- The SEARCH() function, used to identify if a file can be found on the PROPATH, returns the full path of a file if it's not in a library. If the file is found in a library, instead it returns the name of the library and the file within the library.
For example, the function: SEARCH("dict.r") may return "/usr/dlc/dictionary.pl<<dict.r>>" where 'dictionary.pl' is the library file, and dict.r is the r-code file within that library. - The LIBRARY() function takes a character string argument and either return the library name that the string mentions, or the unknown value if the argument doesn't denote a library. In the above example, LIBRARY(name) would return "/usr/dlc/dictionary.pl".
- The MEMBER() function returns the simple member name for a file in a library. In the above example, MEMBER("/usr/dlc/dictionary.pl<<dict.r>>") would return "dict.r".
Building libraries using the PROLIB tool
PROLIB is a stand-alone utility used to build the procedure library (.pl) files. The syntax is:
PROLIB <library-name>.pl <command> [<command>...]
Where:
- <library-name> is the name of the library and has a .pl extension. Use the .pl extension on the library name so that PROGRESS can detect a library on the PROPATH by just examining its extension.
- <command> is any of the commands listed below.
Commands that can be used with the PROLIB utility are:
1. -create
- Creates a new library.
- It generates an error if the library already exists, unless -nowarn is specified (see below).
2.
-add file [file...]
- Adds the specified files to the library.
- A file may not appear in the library more than once.
- If an error occurs that causes the PROLIB command containing the -add to fail, the resulting library is still correct, but may seem larger than it should be. This is the result of the new file actually being added to the end of the library file, without the directory being updated. (So, even though the bytes of the new file are in the library, the library doesn't know it). Running PROLIB with the -compress option will fix this (see below).
3. -replace file [file...]
- Replaces the specified file in the library.
- If you attempt to replace a file that isn't already in the library, you get an error (unless -nowarn is specified, see below).
4. -delete file [file...]
- Deletes the specified files from the library.
5. -list [file...]
- Lists the table of contents of the library, as well as some other information about the library.
- The listing is sorted by file name, and dates display in the format specified by the -date command (see below).
6. -date date-format
- Specifies the format of the date to use in displaying file timestamps in the -list command.
- The format of "date-format" is the same as that of the -d switch in PROGRESS (mdy)
7. -extract file [file...]
- Extracts the named files from the library.
- The files are copied from the library to files with the same path and file names that they have in the library.
- The directory structure must exist on disk, otherwise, the extract will fail.
- The directory structure required can be determined with the output from the -list command;
- Files extracted retain the same modification time that they had when they were added to the library and the access time is set to the timestamp of when the file was added to the library (as long as OS and filesystem support this functionality).
- If a file being extracted already exists outside of the library, it warns of this and prompts for an action (overwrite, rename, quit), unless you use -nowarn (see below).
- For further details refer to Article How to extract files from a procedure library ?
8. -nowarn
- When used with the PROLIB command options -add, -replace, -extract, -delete, -create, these options to do their work silently without warning as described above.
9. -yank
- This option works exactly like -extract except that any leading pathname component is stripped off so that the resulting file is placed in the current working directory.
- This is usually not recommended as compiled code pulled out of the library this way likely won't be runnable when relative path names within the code and class package names will fail to resolve correctly.
10. -compress
- Compresses the library by making a copy of it.
- The -compress option creates a temp file named PLBXXXXXX (where the X's are replaced by some number) in the current directory to accomplish the compression.
11. -f file
- This command allows you to supply command-line arguments in a file.
- This allows you to specify commands that would normally overflow the system command line length limits.
- The contents of the specified file are inserted in the command line replacing the"-f file" command.
- A file of command line arguments cannot itself contain a -f command.
12. -makeshared
13. -verbose
- PROLIB does its work silently.
- The verbose command directs PROLIB to tell you what's being done as it's happening.
- This is reassuring if you're doing multiple -add's (or -create's, or -extract's) and want to be sure the instruction is being carried out as intended.
1. Procedure libraries can contain a directory structure:
To avoid having to re-write the ABL code, ensure this directory structure matches the relative paths used in the code.
Example: Procedure library directory structure
- The ABL contains a statement: RUN debtors/processpayment.p.
- The location on disk before building the library is: //AppVersionX/financials/debtors/processpayment.p
- The PROPATH has the directory AppVersionX/financials
To make the implementation of the .pl transparent:
- The library would contain a copy of the directory tree starting from the debtors subdirectory.
- The reference to the .pl file can then replace the directory reference on the PROPATH; the search logic will find the relative path in the ABL statement within the library and load the R-code file.
2. Do not change the PROPATH during program execution:
When the PROPATH is changed in a way that removes a library from the PROPATH that contains a file that is currently active (i.e. contains a procedure that is currently running or is waiting for a subprocedure to return).
While the procedure itself will be kept in memory, if it has further dependencies on other procedures in the same library this can prevent the procedure from completing correctly because it can no longer find it's dependencies.
3. For optimal performance:
Place the .pl/.r files that are accessed the most frequently near the start of the PROPATH.
When locating r-code, the client always searches from the start of the propath and returns the first instance found.
Having frequently used code near the start means that the majority of searches completes in the shortest time possible.
Common known Procedure Library issues
1. A library can be opened indirectly, using a SEARCH or RUN statement that generates a library name that is not on the PROPATH.
- Libraries opened this way will stay open for the duration of the session.
- To conserve resources, avoid doing this unless absolutely necessary.
2. If the procedure libraries are on a network/file server, re-reading the r-code segments over the network may introduce a new performance bottleneck: Using the network can be slower than re-reading the segments from a local disk.
- Use the -pls startup parameter, which directs the OpenEdge client to use the conventional temp file technique to swap out library-based procedures instead of re-reading from the library.
- If you have a local disk or a RAM-disk that holds the client temp files, it is faster to use these than to do the remote file server accesses to the library.
3. Using the library requires memory for the library directories, which are dynamically allocated.
- In some cases, this can lead to memory shortages for the client, 32-bit client's in particular, which results in the runtime client failing due to a memory shortage when a library is used.
- To avoid memory shortages, use the command line switch "-plm" enables caching the library directories in small chunks, rather than being read in their entirety.
