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:
-
Editor and build descriptor preferences
-
Program properties
-
EGL build path and import statements
-
containerContextDependent property
-
EGL reserved word list
-
Placing parts in EGL files
-
Migrating with a program
-
Migrating with associated parts
- Migrating without associated parts
- Overwriting and merging files.
These techniques are explained in the following sections. There are
also some general rules that govern the migration tool.
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:
-
Use of the hyphen (-) and national language characters @, and # in part names
- The primitive data types numc and pacf
-
Defaulting the array index to 1 for single dimension arrays
- The deleteAfterUse property on use declaration for a
data table, which is the replacement for keep after use
- The SQL item property sqlDataCode
- The call statement options of externallyDefined and
noRefresh, which are the replacements for the NONCSP and NOMAPS
options
-
The transfer and show statement
externallyDefined option, which is the replacement for the NONCSP
option on DXFR and XFER statements
-
A display printForm statement is implemented the same as a print printForm
statement
- The initial value of a form field is used only when displaying a field on
the screen that has not had a value assigned to it. The preference does
not set the initial value of the field in storage.
- The handleSysLibErrors system variable, which is the
replacement for EZEREPLY
- The handleHardDliErrors system variable which is the
replacement for EZEDLERR
- The getVAGSysType system function, which provides the old VAGen
values for EZESYS
- The connectionService system function, which is the replacement
for EZECONCT
- The segmentedMode system variable, which is the replacement for
EZESEGM
- The sqlIsolationLevel system variable, which is the replacement
for EZESQISL.
- Host variables that are not in an SQL record are initialized to blanks or
zeros depending on the primitive type if the value retrieved from the database
is null. Host variables in SQL records are only initialized if the
isNullable=yes property is set for the data item.
-
Even precision for decimal fields (VAGen PACK fields) is incremented by 1
except for host variable references in SQL WHERE clauses and the EGL
prepare statement.
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.
There are two program properties that the migration tool includes for every
program:
-
includeReferencedFunctions = yes. The migration tool always
includes this program property so that functions do not have to be nested
within the program. This enables you to keep just one copy of common
functions in a separate project or package and import them, rather than
including the common functions in each program. When you use Stage 1 -
3 migration, the migration tool also includes any necessary import statements
for functions that are in a different package from the program.
-
allowUnqualifiedItemReferences = yes. The migration tool
always includes this program property so that references to data items do not
need to be qualified. The EGL rules for unqualified data items
incorporate the VAGen rules so that unqualified items resolve to the same
record, table, or map (form) as in VisualAge Generator. The migration
tool does not add qualifications.
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 projects in SubsystemA needs to include the
project that provides SubsystemA's definition of RECORDX.
-
Files for programs in SubsystemA that use RECORDX as a type declaration for a
record need to include an import statement for the package within SubsystemA
that contains the definition of RECORDX.
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:
- Set the EGL build path for each project based on the parts the project
needs to reference in other projects.
-
Includes most import package statements for each file based on the parts the
file needs to reference in other packages within the EGL build path for the
project that contains the file.
The migration tool does not add import statements for the following situations
because these are not associates in VisualAge Generator:
-
For a function that transfers to a program using a CALL, DXFR, or XFER
statement. If you are generating for Java, you must add the import
statement for the package containing the program within the file containing
the function, fully qualify the program name with the package name, or use an
entry in a linkage part to specify the name of the package where the program
is located.
-
For a data item that specifies a validatorTable or validator function.
You must add the import statement to the file containing the data item to
specify the name of the package where the validatorTable or validator function
is located.
-
For build parts in .eglbld files. VAGen control
parts, such as the generation options parts, do not list their associated
parts, so the information is not readily available to the migration
tool. In addition, due to the way EGL processes build descriptor parts,
you will likely need to do some reordering of the
nextBuildDescriptor values (VAGen /OPTIONS). This reordering
will in turn require modification of any imports the migration tool might have
done.
When you use single file migration, the migration tool functions as
follows:
-
Does not set the EGL build path because the output is always going into a
single existing project.
- Does not include the import package statements because all the files that
are created go into the same package. Thus, no import statement is
required.
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:
- The EGL build path for the project that contains FUNCTIONY must include
the project that contains the definition of RECORDX
- The file containing FUNCTIONY must include an import statement for the
package that contains RECORDX.
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 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 migration tool does not rename programs, map groups, or tables because
these parts frequently have references from non-VAGen programs or the runtime
environment (for example, a CICS PROGRAM definition).
-
The migration tool renames data items, records, maps, and functions by
prefixing the part name with a Renaming Prefix. The Renaming Prefix is
one of the VAGen Migration Syntax Preferences that you can specify for Stage 2
or single file mode migration.
-
The migration tool does not rename control parts, except for the
following:
- The migration tool removes the .BND suffix from the end of a bind
control part.
- The migration tool removes the .LKG suffix from the end of a link
edit part name.
- The migration tool changes any other dots to underscores in control part
names. The tool also changes dots to underscores in control part names
that are referenced in the /OPTIONS, /RESOURCE, and /LINKEDIT generation
options.
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.
.
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 type of part:
- Generatable part -- program, table, or map group
-
Control part -- generation options, resource associations, linkage table,
linkedit, or bind control
-
Other migratable parts -- data item, record, map, or function
-
Non-migratable parts - PSB and DL/I records are not migrated to any
file.
-
A Stage 1 preference that enables you to identify Java project or package
names that contain common parts.
Similarly, there is a Stage 1 preference for Smalltalk that enables you to
identify configuration map or application names that contain common
parts.
- Whether the part is used by some other part. The Stage 1 migration
tool determines whether a part is used based on the following:
-
A part is "used" if it appears on the VAGen associates list of any generatable
part in the migration set.
-
A part is "used" if it is in a common Java project or package or in a common
Smalltalk configuration map or application as specified in your Stage 1
preferences.
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:
-
All control parts are placed in a single file called
eglPackageName.eglbld, where eglPackageName is the name of the
corresponding EGL package.
-
Each program part is placed in a file called programName.egl, where
programName is the name of the program.
- Each table part is placed in a file called tableName.egl, where
tableName is the name of the table.
-
Each map group and all maps in the map group are placed in a file called
mapGroupName.egl, where mapGroupName is the name of the map
group. If there is no map group part, the Stage 1 migration tool
creates a dummy map group part. Because the map group and all maps in
the map group must be placed in the same file, these parts must be considered
as a group. This can result in some parts being moved to a different
EGL package or project if the parts were not originally in the same Java
package or Smalltalk application. The migration tool determines where
to place the mapGroupName.egl file as follows:
-
If the map group and all its maps are in the same Java package, the
mapGroupName.egl file is placed in the corresponding EGL
package. Similarly, if the map group and all its maps are in the same
Smalltalk application, the mapGroupName.egl file is placed in the EGL
package that corresponds to the Smalltalk application. In this
situation, the migration tool handles the mapGroupName.egl file in the
same manner as the program and table files. This is the most common
situation.
-
If the map group and its maps are spread across several Java packages
within a project, then the project name, plus a suffix is used to create
the name of a new EGL package to contain the mapGroupName.egl
file. This new EGL package is placed within the original
project.
Similarly, if the map group and its maps are spread across several Smalltalk
applications within a configuration map, the configuration map name, plus a
suffix is used to create the name of a new EGL package to contain the
mapGroupName.egl file. For both Java and Smalltalk, you can
control the suffix with a Stage 1 preference.
-
If the map group and its maps are spread across several Java
projects, then the migration set name, plus a suffix is used to create
the name of a new EGL project that contains the mapGroupName.egl
file. Similarly, if the map group and its maps are spread across
several Smalltalk configuration maps, the migration set name, plus a suffix is
used to create the name of a new EGL project that contains the
mapGroupName.egl file. For both Java and Smalltalk, you can
control the suffix with a Stage 1 preference.
- All the remaining parts are placed as follows:
-
If the part is used by only one program in the migration set, the
part is placed as follows:
-
If the part is in the same package as the program, then the part is placed in
the same file as the program. For example, the main function of a
program (ProgramA-MAIN) is placed in the same file as the program (ProgramA)
provided the function is not used in any other programs. The file is
named for the program - ProgramA.egl.
- If the part is in a different package from the program that uses it, the
part is placed as follows:
- If the part is in a common project or package, the part is placed in the
file called commonParts.egl in the part's original package.
You control the name for commonParts with a Stage 1
preference.
- If the part is not in a common project or package, the part is also placed
in the file called commonParts.egl in the part's original
package.
-
If the part is used by several programs in the migration set, then
the part is placed in the file called commonParts.egl within its
original package. For example, if ProgramA calls ProgramB and passes
RecordR, then RecordR is placed in the file called commonParts.egl in
the EGL package that corresponds to the original Java package or Smalltalk
application that contains RecordR.
- If the part is not used by any programs in the migration set,
the part is placed into a file as follows:
- If the part is in a common Java project or package, then the part is
placed in the file called commonParts.egl within the EGL package that
corresponds to the original Java package that contains the part.
Similarly, if the part is in common Smalltalk configuration map or
application, then the part is placed the file called commonParts.egl
within the EGL package that corresponds to the original Smalltalk application
that contains the part.
- If the part is not in a common Java project or package, then the part is
placed in the file called unusedParts.egl within the EGL package that
corresponds to the original Java package that contains the part.
Similarly, if the part is not in a common Smalltalk configuration map or
application, then the part is placed in the file called unusedParts.egl
within the EGL package that corresponds to the original Smalltalk application
that contains the part. You control the name for unusedParts with a
Stage 1 preference.
- There are the following special considerations:
-
Any function used as an edit routine on a map contributes to whether the
function is used or not used. However, the migration tool always places
the function with either the program or in the commonParts file. The
migration tool never places the edit function in a file that is created for
the map group.
-
Any shared item that is used in a table contributes to whether the data item
is used or not used. However, the migration tool always places the data
item with either the program or in the commonParts file. The migration
tool never places the data item in a file that is created for the
table.
- 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:
- If ProgramX calls ProgramY and passes records ProgramY-Parm and
Common-Parm, you might want ProgramY-Parm to be placed in the file with
ProgramY and Common-Parm to be placed in the commonParts file. Given
knowledge of your naming conventions, you can modify the Stage 1 migration
tool to change the file placement algorithm.
- For large packages, you might want to split the parts into separate files
by part type.
- If the same part edition appears in multiple migration set versions, but
should be placed in different EGL projects, packages, or files depending on
the migration set version, you might want to update the migration database for
the new EGL project, package, and file name for each part whenever you process
a migration set version. If you make this change, be sure to process
each migration set version completely through Stages 1 - 3 before starting to
migrate the next migration set version.
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.
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.
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:
-
Flexibility in EGL syntax. For example, a DISPLAY I/O option
is migrated without an associated map. In this case the migration tool
makes the choice of using a display statement and includes a warning message
in the migration log. Even if the migration tool guessed incorrectly,
because you use VisualAge Generator Compatibility mode, the display statement
will be accepted even if the form is a print form.
-
Intelligent guess. For example, a map variable field
specifies an edit routine, but there is no part named the same as the edit
routine in the migration set (or the External Source Format file). In
this case, the migration tool makes use of other information. The tool
looks at the following to try to determine whether to use the validatorTable
or validator property:
- Length of the edit routine name, because 8 or more characters indicate it
is a function.
- Edit routine name is EZEC10 or EZEC11, which indicate it is a
function.
-
Edit message is also specified, because the message can only be used with an
edit table or EZEC10 or EZEC11.
Any of these enable the migration tool to make an intelligent choice between
setting the validatorTable or validator property. If there is nothing
to make a definitive choice, the migration tool uses the validator property
and includes an error message in the migration log. If the migration
tool guessed incorrectly there should also be an error on the Tasks
list.
- Deliberately invalid syntax. For example, a SET map PAGE
is migrated without an associated map. In this case, the migration tool
could make the choice between using an EGL sysLib.clearScreen function
for a text form and an EGL sysLib.pageEject function for a print
form. However, both choices are equally probable. Therefore, the
migration tool creates intentionally invalid syntax and converts to
sysLib.EZE_SETPAGE. This results in an error on the Tasks list
and forces you to correct the problem.
- Direct conversion without information due to missing
associates. (The missing associates can result in problems
undetectable by the migration tools.) For example, RecordA specifies
that it is redefining the storage of RecordB. In VisualAge Generator,
the redefinition information is stored in the record definition for
RecordA. When you generate, RecordA and RecordB must be available and
the redefinition is done for the RecordA in the program. In EGL the
redefinition information is only stored in the program. If RecordA is
not available when migrating the program, the migration tool has no way to
detect that RecordA needs to include the redefines property within the
program. Without the redefines property, EGL test and generation treat
RecordA and RecordB as separate data areas. The program will not
run the same as in VisualAge Generator -- data might not be initialized
correctly and abends could occur.
This is why we strongly encourage you to generate and test your migrated
programs.
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.
- Import into workspace -- with or without Override existing files.
- Save migrated files to temporary directory.
Migrate remaining VAGen parts controls whether the migration
tool converts all parts in the migration set to EGL.
- If you do not select Migrate remaining VAGen parts, only
generatable parts and their associates are converted into EGL and stored in
the migration database. Data items, records, and functions are not
converted unless they are an associate of one or more generatable
parts. Control parts are not converted. Deselecting Migrate
remaining VAGen parts can be useful if you are migrating a subsystem
project and a common project in a single migration set. In this
situation, the following happens:
- For the subsystem project, only parts that are actually used within the
subsystem are converted.
- For the common project, any generatable parts and their associates are
converted. In addition, any data items, records, and functions that are
used by the subsystem are also converted. Other data items, records,
and functions that might be used by other subsystems but which are not used by
the current subsystem are not converted to EGL.
There are two advantages of deselecting Migrate remaining VAGen
parts:
- For the subsystem project, you have the opportunity to clean up your code
because the migration tool only converts parts that are actually used.
- For the common project, you can defer converting parts until they are
actually used by another subsystem. When you include the common project
in the migration set for another subsystem, any additional parts used by this
subsystem are converted to EGL and stored in the migration database.
This is particularly useful if your common project has associates in various
subsystems or contains parts that are associates of generatable parts in
various subsystems. Deferring the migration of the common parts until a
subsystem uses the part enables the common parts to migrate "with
associates." When you migrate the next migration set that contains the
common project, your selection for Override existing files
controls what happens to the originally migrated common parts files.
- If you select Migrate remaining VAGen parts, the generatable
parts and their associates are converted to EGL and stored in the migration
database. Then any data items, records, and functions that are not
associates of generatable parts are converted to EGL. All control parts
are also converted to EGL. There are two advantages of selecting
Migrate remaining VAGen parts:
- For the subsystem project, all the parts are converted to EGL regardless
of whether they are used or not. This is useful if you must preserve
code for historical purposes.
- For the common project, selecting Migrate remaining VAGen parts
is particularly useful if you know that the parts in the common project do not
have associates in the subsystem projects that you plan to migrate in the
future. You can convert all the common parts one time and have the EGL
stored in the migration database. Then if the common project is
included in the migration set for other subsystems, the EGL is already
converted and available to be imported into the workspace or saved into the
temporary directory with the new subsystem.
If you select Migrate remaining VAGen parts for your first
migration set version, you should continue to select Migrate remaining
VAGen parts for other migration set versions. You should also
specify Override existing files. By specifying both options
you ensure that all the parts in the migration set are included in the EGL
file.
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.
- If you are migrating multiple versions of a migration set, you can choose
which version to have imported into your workspace at the end of
migration. You can choose either the Latest version (most
recent version) or the Oldest version. The advantage of
selecting the latest version is that this is the version which you are most
likely to want to generate for additional testing. The advantage of
selecting the oldest version is that this positions you to store the EGL
projects, packages, and files that correspond to the oldest version into your
source code repository first.
- You can specify how you want to handle the situation in which an EGL file
that is being created by the current migration already exists in your
workspace.
- If you select Override existing files, the EGL file is replaced
by a new file containing only parts in the current migration
set. The migration tool does not convert VAGen part editions again if
they were already converted for a previous migration set. However, the
migration tool does include the EGL for the part editions in the file if the
parts are included in the current migration set. Select Override
existing files if you decide to change your VAGen Migration Syntax
Preferences. In this situation, you could restore your database to the
end of Stage 1 and then run Stage 2 and 3 again with your new
preferences. Specifying Override existing files enables you
to run Stage 2 and 3 without having to clean out the EGL workspace
first. Selecting Override existing files is also useful if
you specify Migrate remaining VAGen parts. In this
situation, if you migrate another version of a migration set, the EGL files
are replaced by a new file containing only those part editions that are
included in the current migration set version.
- If you do not select Override existing files, the existing EGL
file is modified to contain any additional parts that are in the current
migration set. Parts that are already in the EGL file are not
changed, even if the current migration set uses a different part
edition. Deselecting Override existing files is
useful only if you do not specify Migrate remaining VAGen parts and
you are migrating just one version of a common project, but with several
different subsystems. In this situation, you can gradually build up the
EGL files for a common project in stages as you migrate different
subsystems. Only the common parts used by the first subsystem are
initially included in the EGL file. When you migrate the second
subsystem, the migration tool adds any additional parts required for the
second subsystem into the EGL file. The migration tool does a merge of
the original file and the additional parts so that the parts continue to be
organized alphabetically within part type.
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.
There are some general rules that govern what the migration tool does when
migrating your source code. The rules are as follows:
-
Any new variables that are added to support the EZE words or other statements
must be added to the program. They cannot safely be added as local
storage in a function.
This is because a segmented converse is not supported if any function
currently in the stack has local storage, parameters, or a return
value. Because the function context is not known, there is no way to
determine whether the function would be in a function stack that leads to a
segmented converse. Therefore any new variables are added to the
program, not as function local storage. See Intermediate variables required for migration for details.
-
You might have parts from Cross System Product or older releases of VisualAge
Generator that were migrated to VisualAge Generator 4.5, but never
modified within VisualAge Generator 4.5. In some cases,
information is missing from the External Source Format or is specified in a
way that is not supported in EGL. The migration tool attempts to supply
the missing information or correct the information. This includes the
following:
- For main transactions, if the VAGen segmentation information is missing,
the migration tool defaults the EGL segmented property to
no.
-
For SQL records, if the SQL data code is missing, the migration tool converts
the item to a fixed length item.
-
For SQL functions, the migration tool attempts to create any missing required
SQL clauses based on the record specified as the I/O object.
-
Within a function, the migration tool converts all statements to
something. This preserves your IF / ELSE / END and WHILE / END
logic. However, the resulting statements might not be syntactically
correct. For example:
-
If an EZESYS value is not supported in EGL, the migration tool uses the VAGen
value. There will be a message on the Tasks list if the value is not
supported.
- EZE DL/I status words (EZEDL*) are migrated to EGL system variables even
though DL/I is not currently supported by EGL. The EGL system variables
are a "best guess" as to the possible system variable names. The
migration tool issues an error message. There will also be an error on
the Tasks list.
- The CONVERSE I/O option is always migrated to an EGL converse
statement even though it might be used with a UI record. The migration
tool does not issue a warning message. If the CONVERSE is for a UI
record, there will be an error on the Tasks list because the UI record cannot
be migrated.
- The XFER is always migrated to an EGL statement even though it might be
used with a UI record. The migration tool issues an error
message. There will also be an error on the Tasks list.
- The EZESCRPT special function word is commented out. There is no
corresponding EGL replacement. Because EZESCRPT could not be used in an
IF, WHILE, or TEST statement the structure of your function's logic is
preserved. The migration tool issues an error message. There
will not be an error on the Tasks list.
-
When trying to resolve a part reference without a program, the migration tool
looks at the parts in the migration set. Therefore it is important that
you define your migration sets to include groups of projects that are
reasonable to use together. For example:
-
Do not include projects from several subsystems that have conflicting part
names.
- Do include common Java project or common Smalltalk applications when
migrating a subsystem.
- There are some things the migration tool does not do during
migration:
-
The migration tool does not add import statements for the following situations
because these are not associates in VisualAge Generator:
-
For a function that transfers to a program using a CALL, DXFR, or XFER
statement. If you are generating for Java, you must add the import
statement for the package containing the program within the file containing
the function, fully qualify the program name with the package name, or use an
entry in a linkage part to specify the name of the package where the program
is located.
-
For a data item that specifies a validatorTable or validator function.
You must add the import statement to the file containing the data item to
specify the name of the package where the validatorTable or validator function
is located.
-
For build parts in .eglbld files. VAGen control
parts, such as the generation options parts, do not list their associated
parts, so the information is not readily available to the migration
tool. In addition, due to the way EGL processes build descriptor parts,
you will likely need to do some reordering of the
nextBuildDescriptor values (VAGen /OPTIONS). This reordering
will in turn require modification of any imports the migration tool might have
done.
-
EGL does not permit implicit items. VisualAge Generator permits
implicit items, but does not recommend them. Implicit items are items
that are used in a program, but which are not explicitly defined in a record,
table, or map used by the program.
The migration tool does not create definitions for implicit items due to the
performance impact of evaluating every unqualified data item to determine
whether it is an implicit item. You should provide definitions for
implicit items before you migrate. To resolve the problem before you
migrate, validate the program in VisualAge Generator to determine whether the
program actually used implicit items. If implicit items were used,
VAGen validation will provide a message with the correct definition of the
item. If you do not create a definition for the implicit item before
you migrate, there will be an error on the Tasks list and you can correct the
problem in WebSphere Studio.
-
The migration tool does not attempt to set the containerContextDependent
property. This is something you can add later to specific common
records or functions that have the need to reference other parts that are
provided by a subsystem. See the section containerContextDependent Property for more details of how to use this property for records and
functions.
-
The migration tool assumes that the VAGen syntax is valid and that a program
using the parts included in your migration set can be successfully validated
in VisualAge Generator. The migration tool does not attempt to repair
invalid syntax. For example:
-
If the elements of a map array have different edit characteristics or
attributes, the characteristics for the first element of the array determine
what is migrated to EGL. The migration tool does not issue a
message.
-
If the lengths of shared data items in a record have changed so that the
length of a parent item does not match the sum of the lengths of its
substructure, the migration tool does not change any item lengths and does not
issue a message. There will be an error on the Tasks list indicating
that sum of the lengths of the children does not match the length of the
parent.
-
The migration tool does not attempt to improve inefficient code even if it
results in syntax errors in EGL. For example:
- If the same record is listed twice in a program's Tables and
Additional Records list, the migration tool does not remove it and does not
issue a message. There will be an error on the Tasks list.
Similarly, if the same table is listed twice in a program's Tables and
Additional Records list, the migration tool does not remove the extra table
and does not issue a message. There will be an error on the Tasks
list.
- If a record is not used in a program, but is listed in a program's
Tables and Additional Records list, the migration tool does not remove it and
does not issue a message. There will not be an error on the Tasks
list. Similarly, if a table is not used in a program, but is listed in
the program's Tables and Additional Records list, the migration tool does
not remove the table and does not issue a message. There will not be an
error on the Tasks list.
- If a working storage record is listed in the program's Tables and
Additional Records list and the record only contains level 77 items, the
migration tool does not remove the record and does not issue a message.
There will be an error on the Tasks list indicating the record cannot be
found. This is because the only record that now exists includes your
Level77 Suffix preference as part of the record name.
-
If a VAGen program includes a map group or a help map group, an actual map
group part did not have to exist. For example, if the program never
DISPLAYs or CONVERSEs a map or if the program never uses a map as a called
parameter, an actual map group part did not have to exist. In this
situation, the migration tool includes the use statement for the formGroup,
but does not include the import statement in the program because the map group
was not an associate of the program in VisualAge Generator. The
migration tool does not issue an error message. EGL requires an actual
formGroup part. If there is no formGroup part or if the formGroup part
is not in the same package as the program, there will be an error on the Tasks
list indicating that the formGroup specified in the program's use
declarations cannot be found.
- The migration tool does not necessarily detect or provide warning messages
for the use of facilities that were not documented in VisualAge Generator,
even if there is no equivalent EGL support. For example:
- The VAGen EZEBYTES function is only documented to support items and
records. There was undocumented support for maps. The EGL
sysLib.bytes function only supports items and records. The
migration tool does not provide a warning message if you used EZEBYTES for a
map. There will be an error on the Tasks list.
- If a CALL statement specifies an unqualified item as an argument, and
there are multiple definitions for this item name within the program, the item
is assumed to be a level 77 item in the program's primary working storage
record. EGL requires that the item be qualified. The migration
tool does not add the qualification for you and does not provide a warning
message. There will be an error on the Tasks list.
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.