VisualAge Generator to Enterprise Generation Language Migration Guide

There are a number of techniques that the migration tool uses to determine the corresponding EGL syntax and to preserve the VisualAge Generator behavior. These techniques are as follows:

These techniques are explained in the following sections. There are also some general rules that govern the migration tool.

Editor and build descriptor preferences

Before you start Stage 2 of migration, you should turn on the VisualAge Generator Compatibility preference for your WebSphere Studio workspace. The VisualAge Generator Compatibility preference provides support for the following VAGen behaviors:

The VAGen migration tool automatically adds the vagCompatibility="YES" option to every VAGen generation option part that it migrates to an EGL build descriptor. The vagCompatibility build option directs preprocessing and generation to provide the same support as the VisualAge Generator Compatibility preference.

Program properties

There are two program properties that the migration tool includes for every program:

EGL build path and import statements

EGL enables you to have multiple definitions for a part in the workspace at the same time. The EGL build path for a project limits which other projects will be considered when looking for a part name. The import statement in a file determines which packages, other than the current package, and which parts within the EGL build path will be considered when looking for a part name.

In most situations, the EGL build path and import statements are sufficient to resolve any part references. For example, the EGL build path and import statements for a program are sufficient to resolve a record name if you use the record as a type definition in a record declaration in a program. The EGL build path and import statements are also sufficient to resolve data item references if you only have one definition of the item that can be used with a record definition, function local storage or function parameter list.

For example, you might be working on SubsystemA and SubsystemB which have two different definitions of RECORDX. All programs in SubsystemA need to use the SubsystemA definition of RECORDX. This can be achieved as follows:

The EGL build path property for the SubsystemA projects limits the projects that will be searched to just the projects within SubsystemA and the common projects. The import statements in the files within SubsystemA limit which packages within the EGL build path will be considered. Even if RECORDX uses shared data item ITEM1 and the two subsystems have different definitions of ITEM1, the EGL build path and import statements are sufficient to resolve the references to ITEM1. The project that contains RECORDX in each subsystem must specify an EGL build path property that includes the subsystem project that contains that corresponding subsystem definition of ITEM1. The file containing RECORDX in each subsystem must have an import statement that specifies the subsystem package that contains the corresponding subsystem definition of ITEM1.

When you use Stage 1 - 3 migration, the migration tools do the following:

When you use single file migration, the migration tool functions as follows:

containerContextDependent Property

As described in "EGL build path and import statements", the EGL build path and import statements are generally sufficient to provide the part name resolution that you need. However, EGL expects to resolve all part name references whenever you save a file. EGL adds an error message to the Tasks list if it cannot resolve the part name. Depending on your architecture, you might also need to use the containerContextDependent property for records or functions.

Consider the situation where RECORDX is used as the type definition for a function parameter in FUNCTIONY. Assuming that RECORDX and FUNCTIONY are in different projects and packages, EGL expects the following:

If all subsystems have the same definition of RECORDX, then the EGL build path and import statements are sufficient, and EGL can resolve the part reference for RECORDX whenever you save the file containing FUNCTIONY.

However, consider the situation in which SubsystemA and SubsystemB both use FUNCTIONY, but have different definitions of RECORDX. In this situation, the EGL build path and import statements cannot point to both subsystems at the same time. EGL supports the containerContextDependent property for functions. In this situation, you can specify containerContextDependent=yes for FUNCTIONY. This specifies that the part name references for the function parameters and local storage are not to be resolved until FUNCTIONY is used within a program. When you test or generate a program that uses FUNCTIONY, the EGL build path of the project containing the program and the import statements of the file containing the program determine where to find the definition of RECORDX. Using containerContextDependent=yes enables you to achieve the same flexibility provided by VisualAge Generator for the function. The EGL build path for each project in the subsystem and the import statement for any files containing programs in the subsystem point to that subsystem's definition of RECORDX.

The containerContextDependent property is also supported for records. For example, SubsystemA and SubsystemB might both use the same definition of RECORDZ. However, RECORDZ uses shared data item ITEM1 and the subsystems have different definitions of ITEM1. In this case, you can specify containerContextDependent=yes for RECORDZ so that EGL validation will not attempt to resolve ITEM1 until RECORDZ is used in a program. The EGL build path of the project containing the program and the import statements of the file containing the program determine where to find the definition for ITEM1.

The migration tool does not attempt to set the containerContextDependent property for you. This is because the migration tool does not require that you migrate all you subsystems at the same time and does not do a complete analysis of all definitions of all parts to determine when there are duplicate part definitions. You can add the containerContextDependent property as necessary if you determine that there are duplicate part names that need to be resolved at test and generation time (as in VisualAge Generator) rather than at definition time (as in EGL).

EGL reserved word list

EGL has a reserved word list. Parts cannot be named the same as any EGL reserved word. In addition, EGL does not permit the use of the # symbol as the first character of an EGL part name. The # symbol is permitted as the first character of an EGL build part name. If a VAGen part is named the same as an EGL reserved word, or if a VAGen part starts with the # symbol, the migration tool does the following based on the part type:

The Stage 1 migration tools provide a list of the program, map group, table, and control part names that conflict with the EGL reserved word list. If you do not rename these parts before you migrate, the Stage 2 migration tool (or single file mode) will also issue an error message. There will be an error on the WebSphere Studio Tasks list. You can also correct the problem in WebSphere Studio by renaming the part and optionally using the EGL alias property. .

Placing parts in EGL files

When you migrate using Stage 1 - 3 migration, each Java package or Smalltalk application migrates to the corresponding EGL package based on your Stage 1 renaming rules. The VAGen parts within the original Java package or Smalltalk application are placed in one or more EGL files within the corresponding EGL package based on the following:

The Stage 1 migration tool determines the placement of all parts. The Stage 1 migration tool places VAGen parts within a single Java package or Smalltalk application into EGL files within the corresponding EGL package as follows:

Note:
If you migrate multiple migration sets or migration set versions without clearing out the migration database, the first migration set version processed in Stage 1 that contains a part edition controls the project, package and file name for the EGL part. To ensure that parts are placed according to the definition of each migration set version, you should clear out the migration database between versions.

The Stage 1 migration tools for Java and Smalltalk are provided as sample code. You can modify the Stage 1 migration tools to place parts differently based on your own library management philosophy. For example:

Migrating with a program

Normally when you migrate, you specify a migration set that identifies all the Java projects or Smalltalk configuration maps that should be migrated as a group. Using the migration set, the migration tool migrates programs and their associates first. This enables the tool to use the context of a specific program to assist in resolving situations where the EGL language is more precise or more restrictive than VisualAge Generator. The first program to migrate, together with its associates, determines the EGL syntax for any ambiguous situation within that program or its associates. A different program might result in a different resolution for the same ambiguous situation in a shared data item, common record, map, table or function. Because a part version is only migrated once, the first program that uses the common part controls the resolution of any ambiguous situation for its associates.

Consider the example in which ProgramA is a main transaction program using display maps and ProgramB is a main batch program using printer maps. The programs share common functions that display the HEADER and DETAIL maps. The common functions also use the SET map PAGE statement to clear the screen or force a page eject. In this case, if ProgramA migrates first, the migration tool creates the EGL source for the functions to use the display statement and clearScreen system library function. If ProgramB migrates first, the migration tool creates the EGL source to use the print statement and the pageEject system library function.

Whenever you migrate programs and their associates, the first program that uses a shared data item, common record, map, table, or function controls the resulting EGL code. In most cases, because the programs use the common code in the same way, this technique provides the most appropriate migration of your VAGen source. However, as you can see from this example, the specifics of what you intended the common code to accomplish might not be reflected in the resulting EGL source. In this example, regardless of which program migrates first, you will not be able to test or generate the program that migrates second. In VisualAge Generator Compatibility mode, you can use the display statement to resolve the problem with the I/O statement. However, to resolve the problem with the choice of clearScreen or pageEject might require adding a new variable, TEXT-OR-PRINT, that each program initializes and which the common function tests to determine whether to execute the clearScreen or pageEject system library function.

Migrating with associated parts

If a program and its associates are not available, the migration tool makes use of all the parts that are available in the migration set (or in the External Source Format file if you are migrating in single file mode). In this case, if the additional part that is needed for cross-part migration is available, the migration tool can make a decision with a high probability that it is the correct choice.

Consider the example in which a map variable field specifies an edit routine. If a VAGen table that is named the same as the edit routine is available in the same migration set (or the External Source Format file), then the migration tool assumes that this is the table that would always be used and migrates to the validatorTable property. If there is a function that is named the same as the edit routine, then the migration tool migrates to the validator property. In either case, because there is a part with the same name as the edit routine, the migration tool has a high probability that it made the correct choice. If a table or function with the same name as the edit routine is not available, then the migration tool processes the map variable as though it was migrating without associated parts.

In many cases, migration with associated parts can provide very similar migration to what you would achieve when you migrate programs with their associates. The disadvantage of migrating without the program is that you can quickly shift from migrating with associated parts to migrating without associated parts even within a single function based on the specific statement that is being migrated and the other parts that are included in the file.

Migrating without associated parts

Sometimes even when a program is available, not all of its associates are included in the migration set. Or you might be migrating some common parts that were used in the past by a subsystem, but which are not currently in use. In this case, the associates of a part that is being migrated might not be available. The migration tool still converts the part using one of the following techniques:

Overwriting and merging files

The Stage 2 and 3 migration wizards provide several related preferences that control processing for multiple versions of the same migration set. These preferences are as follows:

Migrate remaining VAGen parts controls whether the migration tool converts all parts in the migration set to EGL.

Import into workspace controls whether the migration tool builds the EGL projects, packages, and files in your workspace. If you select Import into workspace, there are additional options that you can select.

You can select Import into workspace when you are migrating multiple versions of a migration set. However, the better technique is to deselect Import into workspace and instead select Save migrated files to temporary directory. Using the temporary directory enables the migration tool to create all the migration set versions.

Save migrated files to temporary directory enables you to migrate multiple versions of a migration set and store all the versions outside the workspace. This option requires the use of multiple simultaneous instances of WebSphere Studio. Therefore, due to the large amount of memory resource required, it is recommended only for batch mode. When you select Save migrated files to temporary directory, you must also specify a high level directory. The migration tool creates a subdirectory for each migration set version within this high level directory. Save migrated files to temporary directory works particularly well if you also specify Migrate remaining VAGen parts. In this situation, each subdirectory corresponding to a migration set version contains all the parts from the VAGen project versions that are included in the migration set version.

General rules

There are some general rules that govern what the migration tool does when migrating your source code. The rules are as follows:


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]