Project

General

Profile

Wiki » Documentation » Conversion Handbook »

Conversion Hints

A conversion hint is a form of project configuration. It is a directive you provide to guide the conversion process in cases where required information cannot easily be determined by the FWD tools, or where you wish to override default conversion behavior to obtain a particular result. Hints can apply to either 4GL source code or to 4GL schema information. In the latter case, hints may apply to both permanent database objects and to temporary tables defined in 4GL source code.

Hints are provided in the form of XML files. These generally are co-located in the file system within the same directory tree as the source code or data files they are meant to affect. FWD conversion programs will attempt to load and use hints at various points during the conversion process.

Scope and Precedence

Hints files are differentiated by the scope of the project files to which they are applied:

  • Directory-Level - these files contain one or more hints that apply to all source files loaded from the specific path defined by their location, or from any sub-paths which are enclosed by that path.
  • File-Level - these files contain one or more hints that apply only to the exact source or data file being loaded.

A directory-level hints file is always named directory.hints. This file must reside in the subdirectory containing the source files to which the hints should be applied, or in an ancestor directory (but in any event not one which is above the 4GL source code root directory). The hints in this file will serve as defaults for all source code files residing in that directory and all of its descendant directories, unless overridden by lower-level directory hints or by file-level hints.

A file-level hints file is named the same the source or data file to which it applies, with an appended extension of .hints. For instance, all hints which should affect the conversion of a program named myprogram.p (and only that program) should be in a file named myprogram.p.hints, and that file should reside in the same subdirectory as myprogram.p.

Hints which apply to a permanent database's schema are always defined in a file whose name is determined by appending the extension .schema.hints to the root file name of the .df file which defines the Progress schema. So, given a Progress schema file named mydatabase.df, the associated schema hints file would be named mydatabase.schema.hints. This file must reside in the directory {project_root}/data/namespace/. Directory-level hints do not apply to permanent database schemas.

Hints which affect 4GL source code are loaded in the order found, from least specific to most specific. That is, when source code hints are required by the conversion process for a particular 4GL program, the search for related hints files starts in the base path (top-level source directory) and then walks downward to each more deeply nested directory, until finally the directory containing the target source file is searched. This means that all directory-level hints that exist in the path from the source code root directory to the directory containing the current program will be loaded (the search does not stop when the first directory hints file is found). Thus, any hint in a more specific directory (including one loaded from a file-level hints file) may override or augment a directory hint found at a higher level directory.

The particular override/augment behavior varies by hint type. In some cases, a more specific hint will provide information in addition to that provided by a less specific hint. In other cases, information in the more specific hint replaces the less specific one entirely. Note that currently, there is no provision for removing a hint that is specified at a higher directory level. Details of this behavior by hint type are provided in the Functionality section below.

Functionality

Hints control diverse aspects of conversion. Some types of hints - such as those that provide preprocessor substitutions or define artificial variables - may have limited lifespans. They are necessary only to provide enough assistance to the FWD parser to get through the front end of conversion. This allows reports to be generated, such that gap analysis can be performed. If a gap is found such that conversion of a particular construct is not possible or practical from its current form, a strategy must be developed to eliminate the problem. This might involve refactoring or replacing the problematic 4GL construct, or possibly adding a feature to the FWD technology, such that the conversion process can proceed further. In certain of these cases, the hint may become obsolete and can be removed after an alternate solution is implemented.

Other types of hints - such as those that control the conversion of database object names in a schema, or those that define implicit associations between database tables - provide information which flows through the entire conversion process. These are more likely to remain in place for as long as the conversion project is active.

The following table summarizes the types of hints currently supported by FWD:

Category Name 1 Override 2 Purpose
database database additive Loads the specified schema into the schema dictionary for the purpose of identifying database references while parsing a source file. See also the Code Preparation chapter (Database Connections section).
alias alias additive Defines an alias for a particular database schema for the purpose of identifying database references while parsing a source file. See also the Code Preparation chapter (Database Connections section).
variable variable additive Defines an “artificial” variable in the event a variable is referenced in source code, without having been formally defined. This hint was added to support an undocumented “trick”, in which an undefined variable named count, which evidently was implicitly associated with an ACCUMULATE statement, was being accessed directly in 4GL code. This hint allows the FWD parser to recognize such a construct as a “normal” defined variable.
preprocessor arguments preprocessor replacement Defines a suitable substitution value for a preprocessor argument in a parameterized 4GL program. This value should be representative of a substitution which normally would be provided at runtime when the target program is executed. The FWD preprocessor substitutes this value for all instances of the specified argument, so that the resulting file can be properly scanned and parsed.

This hint is designed to enable the front end phase of conversion to be completed. If a single substitution value is all that is ever provided in the legacy system, no further work is likely necessary, because the preprocessed form of the program will already expose functionality required by the application. However, if a variety of substitution values can normally be provided, a strategy must be developed to replace or refactor the target program, to allow all necessary functionality to be exposed in the converted system.
preprocessor global setting overrides preprocessor replacement This class of hint is specified to override the global settings unix-escapes, marker, batch, opsys, and winsys, all specified in cfg/p2j.cfg.xml. Please see the Project Setup chapter (Global Configuration section) for more information.
setting PROPATH (parsing support) propath replacement Defines an override for the global propath setting, specified in cfg/p2j.cfg.xml. The hint can be set to replace the global setting entirely, or to prepend or append additional paths to the global propath setting.
schema table/field name conversion schema replacement Overrides the default name conversion behavior for database table and field names for a particular table.

This hint generally is intended to give fine-grained control over the conversion of table and field names, primarily to resolve naming conflicts that might result from the global name conversion algorithm, which is lossy. Broader control over the name conversion process is available; please refer to the chapter Other Customization for details.

Can also be used to force a static name to be designated for a temporary table (normally a generated name is assigned to a temporary table during conversion).
schema table associations schema replacement Used to define or to clarify “informal” or “natural” foreign relations between database tables. Since the Progress database does not enforce foreign/primary key-based referential integrity, there is no formal definition of foreign constraints in a Progress database schema. However, some application-level coding constructs presume a “natural” foreign relation between certain tables. During conversion, such “natural joins” are detected, based upon idioms in the source code and the presence of certain indexes and matching fields in the tables involved. In some cases, the direction of the relation (i.e., which end is the “primary” end and which end is the “foreign” end) is not obvious. This type of hint is used to clarify this information, which is necessary both in downstream conversion phases and at runtime.
schema drop table/field schema replacement Used to drop a database table from a permanent database's schema, such that the target table does not exist in the converted schema. Optionally, one can designate a static name for a temporary table, which will be created in a separate, temporary table schema. The temporary table will have the dropped table's structure, including indexes.

If a table is dropped, but is referenced in application source code, accommodations must be made to allow such code to convert. This is typically done by introducing custom conversion logic. See the chapter Other Customization (Database section) for details.
schema “synthetic” index schema replacement Defines a “synthetic” index to be created in a converted database schema. A “synthetic” index is one that does not exist in the legacy schema, but which is desirable in the converted schema, for performance or other reasons. A synthetic index will not be used during source code conversion for purposes of index selection, when analyzing where clauses in 4GL query-related language statements, as this could potentially result in incorrectly converted code.
embedded 4GL preprocessor e4gl replacement Affects the preprocessing of a WebSpeed HTML file which contains embedded 4GL code. Can be used to override the global wsoptions and wsmode settings, specified in cfg/p2j.cfg.xml. Also can be used to override the default name of the 4GL source file that will be generated from the HTML input file.
user-defined key-value pair uast replacement This hint type provides a generic facility to define a key-value pair which is available to downstream conversion logic. The meaning of the information represented by this hint is user defined. It generally is used with customer-specific conversion hooks to implement custom conversion logic. Please refer to the chapter entitled Other Customization for details on how to implement such hooks.

The key must be a string, uniquely named within its file (and within all less specific directory-level hints files, unless it is intended to override a less specific value for the same key). The value supports the following data types:
     • string
     • string[]
     • long
     • double
     • boolean
The string data types are backed by java.lang.String objects and the primitive types are backed by corresponding Java primitives. Standard Java formatting conventions apply when specifying instances of this type of hint.

Table Notes:

  1. Name of the top-level XML element specified when defining a hint of this type in a hints file. See Syntax section below for a detailed description of the XML format.
  2. Specifies the override behavior of the given hint type, with respect to hints defined for the same construct at one or more precedence levels. Additive means the hint begins a list of values if a less specific hint has not created such a list, or appends to such a list if already established by a less specific hint. Replacement means any less specific hint information is replaced entirely when a more specific hint is encountered.

Syntax

Regardless of whether a hint is defined at the directory level or at the file level, the syntax of each type does not vary. The XML syntax for all supported hint types is as follows:

  • hints (root element)
    • database (element, can be 0 or more)
      • name (attribute) - the name of the database to load into the schema dictionary before parsing starts
      • load (attribute) - the default value is true / yes, but if no / false is specified, this schema/database is 'unloaded' for current file/directory. That is, the conversion acta as the database was not specified in configuration file, even if the tables/fields are fully qualified. This is mandatory to use when a source file contains references to ambiguous elements (tables/ fields) because they were initially defined in a single schema and secondary schema was added with overlapping elements.
    • alias (element, can be 0 or more)
      • name (attribute) - the name of the alias to create in the schema dictionary before parsing starts
      • database (attribute) - the name of the database to associated with the alias in the schema dictionary before parsing starts
    • variable (element, can be 0 or more)
      • name (attribute) - the name of the variable or widget to add to the variable/widget dictionary before parsing starts
      • type (attribute) - the non-negative integer token type of the variable/widget
      • classname (optional attribute) - the fully qualified name of the class of an variable that represents an object instance)
    • preprocessor (element, can be 0 or 1)
      • argument (element, can be 0 or 1)
        • name (optional attribute) - the name of the argument
        • pos (optional attribute) - the positional number of the argument, which will be used to create a name for the argument
        • one of either the name or pos attributes must be present to allow this value to be added to the arguments map
        • value (attribute) - the exact string encoding of the specific argument to be passed to the preprocessor;
      • unix-escapes (element, can be 0 or 1)
        • value (attribute, the string "true" or "false") - honors a system-wide default
      • marker (element, can be 0 or 1)
        • value (attribute) - a base-10 integer between 0 and 255 inclusive; honors a system-wide default
      • batch (element, can be 0 or 1)
        • value (attribute, the string "true" or "false") - honors a system-wide default
      • opsys (element, can be 0 or 1)
        • value (attribute) - the exact string encoding the operating system to be returned by the preprocessor's OPSYS built-in; honors a system-wide default
      • debug (element, can be 0 or 1)
        • value (attribute, the string "true" or "false") - honors a system-wide default
      • winsys (element, can be 0 or 1)
        • value (attribute) - the exact string encoding the window system to be returned by the preprocessor's WINDOW-SYSTEM built-in; honors a system-wide default
      • source-charset (element, can be 0 or 1) - this is the charset to be used for reading external procedures, classes and all include files by the preprocessor; use this in preference to setting the LANG for the Java process since it will allow the inputs to be read in the proper charset but for all other work and output to be done in UTF-8
    • propath (element, can be 0 or 1)
      • type (attribute) - must be one of the following text strings
        • replace
        • prepend
        • append
        • dynamic-prepend
        • dynamic-append
      • value (attribute, required for types replace, prepend and append, ignored otherwise) - encodes the exact string to be used as the replacement propath, to be prepended to the propath or to be appended to the propath), parameters from the project configuration can be referenced as substitutions to allow the path values to be made project-relative (use something like ${P2J_HOME}/my/src/path:)
    • schema (element, can be 0 or 1) - container for all database table hints
      • table (element, can be 1 or more) - container for table-related hints
        • name (attribute) - name of the database table; only one table element with this name should be specified in a given hints file, else conversion will likely produce incorrect results
        • drop (optional attribute) - if true, indicates current table will be dropped from converted schema
        • temp (optional attribute) - static name to be assigned to this temporary table; if current table is not a temp-table and the drop attribute is true, a temporary table is defined in lieu of the dropped persistent table; the temporary table will have the same structure as the dropped persistent table
        • field (element, can be 0 or more)
          • name (required attribute) - name of the database field
          • phrase (element, can be 0 or more)
            • match (attribute) - text to match within the field name being converted
            • replace (attribute) - text to substitute for matched text within the field name being converted
        • index (element, can be 0 or more) - container for a synthetic index definition
          • name (attribute) - the “root” name of the synthetic index to be created; this name will not go through name conversion, so it should be a legal name for the target database, however the prefix idx__{table name}_ will be prepended to this name when the index is created during database import
          • index-field (element, can be 1 or more) - specifies a field within the enclosing table to add to the synthetic index; if a multi-column index is needed, the columns are added in the order these elements appear
            • name (attribute) - Progress name of the field to be added to the index
        • phrase (element, can be 0 or more) - container for a match phrase dictionary entry which will override a global default (see the Naming section of the Other Customization chapter)
          • match (attribute) - text to match within the table/field name being converted
          • replace (attribute) - text to substitute for matched text within the field/table name being converted
          • no-inherit (optional attribute) - true to apply this match phrase to only the table name, but not the field children; if false or missing, the phrase is inherited by all fields of the table
        • association (element, can be 0 or more) - container which defines an association between two tables
          • type (attribute) - type of association between this table and another; accepted values are: one-to-one, many-to-one, or one-to-many
          • references (attribute) - name of table referenced by this association
          • foreign (optional attribute) - true if this table represents the foreign key end of a one-to-one association
          • field (element, can be 0 or more)
            • name (attribute) - name of field in this table which is used to join the tables in this association
            • references (attribute) - name of field in the referenced table which is used to join the tables in this association
    • e4gl (element, can be 0 or 1) - container to set embedded 4GL preprocessor setting overrides
      • wsoptions (element, can be 0 or 1)
        • value (attribute) - the exact string encoding all WebSpeed options to be passed to the preprocessor for this file; honors a system-wide default
      • mode (element, can be 0 or 1)
        • value (attribute) - the string name of the preprocessor compatibility mode; honors a system-wide default
      • output (element, can be 0 or 1)
        • value (attribute) - file name of the 4GL source file that will be generated from the HTML input file
    • uast (element, can be 0 or 1) - defines a general purpose, key/value hint
      • name (attribute) - the unique name of the hint which will be used as a key
      • datatype (attribute) - the name of the value's data type; can be one of the following (case is ignored):
        • string
        • string[]
        • long
        • double
        • boolean
      • value (attribute) - the exact string encoding the value of the hint, except when the datatype is string array
      • array-val (element, 1 per array entry when the type is string array, otherwise it is absent)
        • value (attribute) - the exact string encoding the value of the entry in the array

Summary

Hints are a form of configuration information for the conversion process. Some types of hints are necessary to provide missing information which is required for early phases of conversion to complete at all. Others exist to tailor conversion behavior by overriding default behavior or global settings. This chapter discussed the kinds of hints which are available, as well as how to specify them and organize them as part of your project.

Hints are one mechanism available to configure and customize conversion. A broader discussion of this topic - including when and why you might use certain types of hints in your project - is presented in the chapter entitled Other Customization.

© 2004-2017 Golden Code Development Corporation. ALL RIGHTS RESERVED.