The OpenEdge Hive

The primary tailoring occurs in the launch program, abl2db_launcher.p which is found at the top of the src directory. At the top of this program you will find a section of variable definitions labelled Application Specific Definitions. You need to edit the initial values for these definitions to match your application.

The values in the code provided apply to sample code from an ERP package called Integrity/Solutions which was based on Varnet and which has not been maintained for 10 years. In some ways, this makes it a good "bad" example, including source files with no extensions and a lot of trash in the source tree which would have been cleaned up if maintained by modern standards. The code for this application is located on my system in \work\IS with the database under the DB directory and the code under ISRel. It uses two databases.

Variables in Launcher
The tailorings should be fairly self-explanatory, but here is an explanation of the variables:

Variables for selecting files from source directories

• chCompilableExtensions is a list of all of the extensions of those files which you expect to compile.
• chSourceExtensions is a list of all of the extensions which you want to consider "source" including compilable ones and not. This clearly would include include files, but could involve more depending on your sites naming standards.
• lgExcludeNoExtension is a flag which allows you to include or exclude files that have no extension, should you be cursed with such. Files with no extension will be included in both the compilable list and the source list.
• chNonSourceExt is not used in ordinary processing, but can be useful in debugging and lists extensions of files in the source tree which are not source, e.g., documentation or examples.
• chJunkExt is similar to chNonSourceExt except that it specifically points to files in the source tree which really shouldn't be there, but which have not yet been cleaned up. One can use BuildDirectoryTree.cls to identify these files and hopefully clean up the source directory going forward.

Database and Schema Variables:

• chDataBaseList is a list of fully qualified database names to which a connection should be made for compilation. These databases need only schema; i.e., they can be empty.
• chLogicalDataBaseList is a list of just the DB names used by the application. I.e., if no -ld is used in the connection parameters, this will be just the DB name from the list above, but if -ld is used, then these are the logical names established by those parameters. If including a SchemaFile for DICTDB, then include a final DICTDB on this list as well. I.e., the number of entries here should match the number in chSchemaFileList, not chDataBaseList.
• chAliasList is an optional list of aliased to create after connecting the database. These should match the databases one for one. Leave empty to create no aliases.
• chDataBaseConnectParams is a | separated list of the connection parameters needed to connect to the corresponding databases in the list above. Defaults is "-1|-1" etc. for single user (no server). Include -ld if logical names are to be used.
• chSchemaDirectory is a fully qualified path to a directory containing one or more.df files containing all schema referenced by the application. Note, the proparse.schema file used by Proparse will be created in this directory.
• chSchemaFileList is a comma-delimited list of logical database names whose schema is containing in the chSchemaDirectory directory. The files are LogicalDBName.df. If the application accesses metaschema directly, e.g., _user, include a DICTDB.df for the needed metaschema files unless such references are fully qualified in the code.

Propath for compile

• chPropath is the propath to use when compiling the application.

Source Variables

• chSourceDirectoryList is a comma-delimited list of fully qualified paths to the directories containing the source.
• chRunDirectoryList is a comma-delimited list of fully qualified paths to the directories which will contain the R-code.
• chXrefDirectoryList is a comma-delimited list of fully qualified paths to the directories where the XML XREF files will be put.
• chListDirectoryList is a comma-delimited list of fully qualified paths to the directories where the LIST files will be put.
• chDebugDirectoryList is a comma-delimited list of fully qualified paths to the directories where the DEBUG listings will be put.

Other variables

• chReportDestination is a fully qualified path to a directory where each stage will write its report of exceptions and totals.
• MenuFile is a fully qualified path to a file which contains the menu definitions (see below).
• MenuItemFile is a fully qualified path to a file which contains the menu item definitions (see below).
• chFunctionalUnitFile is a fully qualified path to a file which contains the functional unit definitions (see below).
• chPrimaryLog is a fully qualified path to a file in which to place the overall log of for the run. This will show the execution of each stage and any unexpected errors.

Note that for the directory lists, there is a positional correspondence. I.e., the first source directory will be compiled into the first run directory with the xref in the first xref directory and so on.

Menu, Menu Item, and Functional Unit Files
The mechanism for menus is inherently specific to the code base, but provides an important clue as to the functionality of the application because it is the mechanism by which a user accesses that functionality (or most of it). To make it easy to load the menu structure, ABL2DB uses three text files in export format to load the menu structure.

The first file is a list of all menus, not the items on the menu. This consists of

• a menu name, as the menu is referenced in the application, and
• a menu description, such as might be displayed as the title of a menu.

For batch programs and other functions not accessed by a user menu per se, pseudomenu entries should be created.

The second is a list of menu items, i.e., things that appear on a menu (or, in the case of pseudomenus, the items in that category). This consists of:

• the menu name, same as is used in the prior file,
• a sequence number indicating the order on the menu,
• a flag, yes or no, as to whether the menu item is itself a menu, and
• a link name.

The link name is either the name of a menu (submenu), as in the prior file, or of a functional unit (see below).

The third file is a list of functional units. In our UML Profile for ABL, a Functional Unit is all code which can be reached from a particular menu selection. That is empirically constructed here by associating a name with the compile unit which is run by the menu item. We can identify the full Functional Unit by following the links from the initial compile unit to all include files and compile units run from or by all those compile units. This is obviously a natural unit of study when making changes to any menu item functionality. The file consists of:

• a functional unit name, e.g., how the unit is referenced in the application,
• a description, e.g., what might be displayed on the menu to identify this option, and
• the full path to the compile unit.

This compile unit path is then used to find the previously loaded compile unit and link to it.

For any application with a data driven menu system, it should be reasonably straightforward to export files in the desired format. It may be necessary to supplement this automatic list with some manual entries to cover batch functions and the like which do not appear on a menu. For an application which has hard coded menus in the code (shame, shame) manual or other automated procedures will be required to create these input files. While one may start using ABL2DB with empty files, users are encourage to create valid input by whatever means since a functional unit is the basic unit for analysis in many cases and one will have to manually identify the appropriate compile unit instead, if no functional units are defined.

Program Descriptions
If they are available, it can be very handy to have even a short description of source code units. With some frequency (though varying quality), then is some kind of description at the top of some or all source code disk files. The exact position and the label, if any, identifying this description varies. The GetDescription.cls has been provided to extract these descriptions when they are available. The customizable portion is in the method ExtractDescripiton which takes a source file as input. It copies the source file into a longchar variable where its lines can be accessed with entry() using a newline delimiter. The supplied version looks for a comment on the first line and extracts everything following an initial argument and a space, which works for Varnet style code. This is easily adapted to look for a particular line or to search through the initial lines for a keyword such as "Purpose:" or "Description:".

SchemaUtilities.cls
This class has two methods which are appropriate for site customization. MassageMetaDBName is called when there is a table reference in which the table name begins with an underscore, i.e., a metaschema table. When these occur in code unqualified, the cross reference will indicate Analysis as the database since that is the first connected database. The standard version converts this to a reference to DICTDB to indicate that it might be any database. Qualified references to other databases are left alone. One might wish to change this default.

The other method is FindTableForBuffer which is intended to use local naming conventions to convert a buffer name to a table name. How easy this is to do depends on the adherence to standards in the code and the nature of the standards. The sample code illustrates a number of prefix and suffix standards. In the worst case, one might have to create a lookup table.

Not Yet Implemented Features
Note that there are a number of features, particularly related to schema, which are not yet implemented because I have no sample .dfs incorporating them to work from. Generally, these are things that are trivial to implement if I just have a sample, so let me know if you run into something with your own code base. In particular, on the schema side is support for non-OE databases and LOB fields.