Like the original JSP-COBOL processor, the Keywood Generator allows JSP-COBOL programs to include elements from Copy and Macro Libraries. The format of the files in Copy and Macro Libraries is exactly the same as it was for the original JSP-COBOL processor - no changes are required. The Generator can handle the formats used by both the PC and mainframe versions of the original processor.
Specifiying the Locations of Copy and Macro Libraries
When the Converter is invoked, the locations of any Copy and Macro Libraries must be passed to it. These locations are either file or directory names:
- A Copy Library can be a single file containing a number of copy elements (a Copy Library File), or it can be a directory that contains a number of files, each of which contains a number of copy elements (a Copy Library Directory). In other words, you can pass the names of individual files to the Generator if you want, but if there are a large number of them you can put them all together in a single directory and just pass the directory name to the Generator.
- A Macro Library is always a directory that contains a number of files, each of which contains a number of macro definitions (a Macro Library Directory).
(Note: The use of Copy Library Files is not recommended. Copy Library Directories offer the same functionality and are more efficient due to the Generator's use of indexes.)
If you are using the Generator as a stand-alone tool from a command prompt window, then the library locations must be passed to the Generator as command line parameters - the details are described in the sections for generating code from LST, JSP Tool and JSP-COBOL files.
If you are using the Generator indirectly through the Network Editor, then you will be able to enter the library locations using a dialogue box.
Copy and Macro Library Indexes
Some of the files in the Copy and Macro Libraries that Keywood encountered during development of the Generator were very large, and searching them linearly would have taken too long. Therefore the Generator creates indexes for each Copy and Macro Library Directory it uses.
The indexes are stored in files whose names end in _INDEX.TXT, and the Generator places them in the Directories to which they relate. The indexes are read into RAM when they are first needed for fast access. Each entry in an index relates the name of a copy element to the character position within the file that contains it, allowing direct access to it without a sequential search through the file.
IMPORTANT: If the contents of a Copy or Macro Library Directory are changed then its indexes are invalidated. A later release of the Generator will automatically detect out of date indexes and re-build them. For now though, if you make any changes to a Copy or Macro Library Directory you should delete all files ending in _INDEX.TXT from it, and this will cause the Generator to re-build the indexes the next time it needs them.
Logical Library Names
The JSP-COBOL syntax allows two kinds of copy statement - one where just the name of a copy element is specified, and one where the names of both a copy element and a library are specified. The Keywood Generator allows you to associate these 'logical' library names used in JSP-COBOL source files with physical library locations.
To associate a locigal library name with a physical library location just enclose the logical name in brackets and append it to the physical library location. For example if copy statements in your JSP-COBOL source programs referred to a library called 'MyLib', but the location of the copy library was actually '\MyJSPCobolFiles\CopyLibraries\MyLib\TestVersion', then when supplying the location to the Generator you would say '\MyJSPCobolFiles\CopyLibraries\MyLib\TestVersion(MyLib)'.
Note that if a copy statement does refer to a specifi library, but the Generator cannot find it in that library, then it will issue a warning and look for it in all the other libraries it has been informed of.