Saturday, March 08, 2008

Converting to eDeveloper V10 (the Migration Story continues)

OK, you're probably thinking: I was a convert to the Magic way of developing a long time ago: why do I need to convert? But I'm talking about a more routine kind of conversion here, the conversion utility that automates the move from eDeveloper v9.4 to eDeveloper V10.
Needless to say, (oh don't worry, I know I say needless things all the time anyway), the Conversion Utility feature does not exist in the Discovery version. The discovery version is designed for beginners and beginners only. If you already have a big application, you're not a beginner.

Getting to Know the Conversion Utility

If you've gotten very far into this, you probably already know that eDeveloper V10 provides an Application Conversion utility for converting your eDeveloper V9 application into an eDeveloper V10 project. Please remember that this utility is designed only for full applications written in eDeveloper V9.4sp7 and onwards.So, if you have to do something to get your application to eDeveloper v9.4 sp7 (or later) first, then do that before attempting the conversion utility. Be warned.
As the documentation ably illustrates, you can launch the Application Conversion Utility from the Windows Start menu > (All) Programs > eDeveloper V10.1 > Migration > V9 Migration UI.
After you launch the application conversion utility, aka V9 Migration UI, you will see its Welcome screen. When you click the Next button, the Version 9.4 Applications Screen opens, and this is where the fun begins (OK, not really fun but I am trying to make this different from the documentation in tone and style, is it working?).

Version 9.4 Applications Screen

So you may be wondering, why do I have to add everything one by one? Well, the answer is simply that you may not feel the need to convert all your applications and components, so just choose the ones you truly want ti the new world of eDeveloper V10. (After all, why convert that cool BetaMax Catalog application? So when you convert an application, each application and its component must be added to the Version 9.4 Applications screen by clicking the Add button. If your application has references to a component that has already been converted, you should still add that component to the list at this point. That's right, do it again, you are telling the convert utility to make that component available to this application in the new world of eDeveloper V10. So just do it.
Each time you click the Add button of course, the Conversion Details screen opens and you have some disambiguation to do.

So This is How You Use the Conversion Details Screen

In addition to the how, I'll try to answer the why, without simply saying "because that's the way it is." Basically, the reason for the conversion details screen is for you to communicate your intent. Do you want to convert all of the application or just part of it? Do you want to convert a new component, or has it already been converted and you just want to reference it? These are the kinds of questions you are answering in this screen. So you simply select whether you are converting an application, part of an application, a component, or keeping the reference for a previously-converted component.
For each export file there are four possibilities (the order entered is not important):
Convert an application - The utility converts the entire application to V10 (but not its components, you are adding them separately, remember?).
Convert part of an application – Now it gets a little particular here, because this option cannot be combined with other conversion types in the same process. That doesn'tmean the very next add operation cannot use one of the other selections, it just means that in a single add operation, you are either choosing part of an application, or some combination of the other three options: convert an application, convert a component or keep a component reference. So, all the other options can be added one after another and all of them will be converted in the same conversion run or process. That is why, this option can only be selected if you have not yet selected one of the other options since starting this session of the utility.
You can continue with additional V9 export files using the Add button.

Convert a component - The utility converts the application to V10, and finds all of the references to the MCF or MFF in all of the Component repositories in the conversion list (the first screen). Then, the utility changes their references to the newly created ECF.
Keep reference for previously converted component - The utility points to the references of this component to the previously converted cabinet file. By doing this, we do not have to convert the same application twice. This is useful if we have a component with models, which is used in a number of different applications.
Depending on which option you select, you then fill in the application details and/or project details.
When you convert an application and its components, the utility will take the name of the component (entered in the Component File Name field) and change any reference to that file name in the Composite Resource Repository with the V10 cabinet file (in the V10 Project Name field).
The Cabinet file location field governs where the conversion process creates the cabinet file.

When you click the Next button, the General Settings screen opens.

Salute the General Settings Screen

The General Settings screen has the following settings:
V9.4 Magic.ini File – The Magic.ini file used in the V9.4 application.
Log file directory – A path for the log file directory.
Log Level – This setting has the following options:
Full – Displays the full log.
Partial – Displays errors and changes of behavior only.
Convert empty eDeveloper handlers – This property governs whether the Record Prefix, Record Suffix, Task Prefix, and Task Suffix will be converted if they are empty. In previous versions, these built-in handlers were created automatically even if they were empty. These empty handlers are irrelevant in V10. If you select this check box, the empty handlers will be included in the converted application. If this check box is not selected, the empty handlers will be removed.
"SpecialModalToolWindow" – In previous versions, the caption of Modal windows was narrow while in V10 it is a full sized caption. Select this check box if you want the Modal window height to be increased in order to fit the contents.

But as we shall see next, you can also go to directly to the conversion executable file.

Taking Command with the Command Line Conversion

eDeveloper V10 does not support the eDeveloper V9 export file structure, however it does provide a command line conversion utility called v9converter.exe that converts eDeveloper V9.4sp7 export files to a valid V10 application.
The v9converter.exe file is located in the eDeveloper V10 installation directory.
When the export file is executed with no parameters or when you enter /?,the Conversion utility help text will appear on the screen.
When you run the utility, the conversion results are displayed on the screen.
If the conversion process fails, you should verify that the command line syntax is valid and that the application is in a valid version 9 export file format. The utility will create the .edp file in the specified project directory and the project source files in the Source subdirectory.
The conversion log file will be created according to the -LOG parameter. If this parameter is not set, the log file will be created by its default name.

So remember, if you need to migrate only a partial application, you need to use the Command Line Conversion utility.

In the final entry on the migration process to eDeveloper V10, we will take a look at what the conversion utility parameters do, try to explain how application behaviors can be changed in the conversion process, and finally, recap some of the troubleshooting issues related to your conversion. Let's hope this whole approach demystifies a lot of this for those of you who have been wondering, what is really involved? As you can see, it takes about as long to explain it all in detail as it does to perform the actual migration. So much for the blah, blah, blah.