Migrating Your Source Code to OS/2 Warp, Part 3: Migration, Analysis, and Translation

From EDM2
Revision as of 01:28, 3 January 2017 by Ak120 (Talk | contribs)

Jump to: navigation, search

by Ingrid Rodriguez

SMART is the Source Migration Analysis Reporting Toolset developed by One Up Corporation. In the last edition of The Developer Connection for OS/2, we brought you SMART, Version 2.1A. SMART, as you may know, is a toolset that helps application developers migrate 16-bit Windows and OS/2 source code, and 32-bit Windows source code to OS/2 32-bit source code.

In Volumes 6 and 7 of The Developer Connection News, we went through two steps of the SMART Migration Process: Source Code Analysis and User-Defined Migration Database Development.

This last article in the series focuses on three more steps of the process:

  • Source Code Migration
  • Resource Analysis
  • Resource Translation

The Source Code Migration Process

To begin the SMART Source Code Migration, you create a List-of-Files file that contains the fully qualified file names to be migrated. (These are the same files you used during the Source Code Analysis.)

SMART migrates to OS/2 the files in the List-of-Files file, placing the migrated files in the same directory as the source files. SMART Source Code Migration can overwrite the original source file with the migrated source code or it can create a migrated file with a different file extension.

Source Code Migration should always be performed after the SMART Source Code Analysis procedure has been performed on the source code to be migrated. The List-of-Files you use to analyze your source code can be used for the migration. You can also make changes to the list.

To run the SMART Source Code Migration, select Migrate Code from the Migration menu. A Migration Configuration dialog panel appears so you can configure the source migration. All of the options on the panel have a default value. The panel lets you select migration formats and options for each category of difficulty. As you might remember from Parts 1 and 2 of this series, SMART categorizes all migration items or keywords based on their migration difficulty. You should always test several output migration formats with sample code before deciding the best migration format to use for your source code. The Migration Configuration panel also lets you create a link database for hyperlinking to migrated changes. To create the link database, select SMART Editor Database and set the DB options to link on the Migration Keyword List. SMART installs sample source files in the SAMPLES directory of the directory where you have installed SMART. You should try different options and review the results to tailor the SMART Source Code Migration to your preferences.

The SMART Source Code Migration lets you migrate your source code with in-line comments, instead of replacing the source code. SMART places comments on all migrated code. After you have made any necessary manual changes, you can select Remove Comments and Tagged Code from the Migration menu to remove migration comments, examples, and other code that were inserted in the source files to assist you in the migration process.

Category 000 keywords require no migration at all; category 010 keywords require migration to equivalent function in OS/2. SMART leaves category 000 keywords untouched and automatically makes the changes for category 010. In many cases, categories 000 and 010 may account for 50%-70% of the changes required in the migration. All other keywords are identified and comments are inserted according to the options that you selected in the SMART Migration Configuration panel.

Keywords in categories 020 and above might require manual changes. You should evaluate these keywords individually and make changes as you see necessary. You might want to write a SMART User-Defined Migration Database (UDMD) to tailor the migration of these keywords to your needs. For more information on how to create a SMART UDMD, refer to the articled titled "Migrating Your Source Code to OS/2 Warp, Part 2: User-Defined Migration Database Development," which appeared in Volume 7 of The Developer Connection News. (You can view the article on your accompanying Developer Connection CD-ROMs.) You can also refer to the SMART Programming Reference located in the SMART folder when you install SMART on your system.

Using SMART with Developer API Extensions

The Developer Application Programming Interface (API) Extensions for OS/2 expand the OS/2 Warp APIs and messages. The Developer API Extensions and messages enable application developers to maintain a common source base for 32-bit Windows and OS/2 Warp applications. With the API Extensions, the migration of procedural source code is simplified. For additional information about the Developer API Extensions, see David Reich's article "IBM Developer API Extensions" in this volume of The Developer Connection News.

We have enhanced SMART through the use of a User-Defined Migration Database specifically designed to exploit the API Extensions keyword set. You can use this special UDMD and the Developer API Extensions to enhance the migration of your Windows application to OS/2. To do so, follow these steps:

  • Refer to the article titled "Migrating Your Source Code to OS/2 Warp, Part 2: User-Defined Migration Database Development", which appeared in Volume 7 of The Developer Connection News.
  • Follow the steps to analyze your source using a UDMD and create a SMART table from the Developer API Extensions UDMD. Then use that table along with the SMART table to analyze your application source code.
  • Before migrating your source code, use the Tables menu to select both the SMART table and the Developer API Extensions UDMD.

When using the Developer API Extensions UDMD, you should expect the SMART Summary Report for your source code to show that the Percent Effort Reduction Using SMART increased. In many cases, when using the API Extensions UDMD, this percentage is somewhere between 80% and 90% (depending on how many Windows keywords your application uses and how many of the keywords are available with the Developer API Extensions).

The SMART Editor

You can use the SMART Editor to hyperlink to each type of change, and then make the changes across all source files. The SMART Editor helps you find all occurrences of a structure or function call. In many cases, you might want to do this before making a change to a field or parameter to understand its use. The SMART Editor is very valuable if you want to make global replacements of a number of strings in all source files. The SMART Editor provides context-sensitive access to the online IBM documentation.

SMART Resource Analysis and Translation

After migrating your source code with SMART, you must also migrate your Windows application resources to the OS/2 resources. However, if you're migrating OS/2 16-bit source code to OS/2 32-bit, your resources will be common for the 16-bit and 32-bit platforms and migration of resources is not needed.

As with the application source code analysis, SMART provides a Resource Analysis function. You'll want to analyze your resource code before translating it. Resource Analysis is very simple, and similar to the Source Code Analysis process. The Resource Analysis will give you an idea of the effort required to translate your Windows resources to OS/2.

To migrate your Windows application resources to OS/2 resources, use the SMART Windows to OS/2 Resource Conversion utility (SMARTRC.EXE). This tool gives you source-to-source conversion of Windows resource definition files to OS/2 resource definition files, and converts the following types of statements:

  • ACCELERATORS
  • MENU
  • BITMAP
  • MENUITEM
  • CAPTION
  • POPUP
  • CHECKBOX
  • PUSHBUTTON
  • CLASS
  • RADIOBUTTON
  • COMBOBOX
  • RCDATA
  • CONTROL
  • RTEXT
  • CTEXT
  • SCROLLBAR
  • CURSOR
  • SEPARATOR
  • DEFPUSHBUTTON
  • STRINGTABLE
  • DIALOG
  • STYLE
  • EDITTEXT
  • AUTOCHECKSTATE
  • FONT
  • AUTORADIOBUTTON
  • GROUPBOX
  • STATE3
  • ICON
  • AUTO3CHECKSTATE
  • LISTBOX
  • USERBUTTON
  • LTEXT

The SMART Resource Conversion utility also recognizes and processes the following preprocessor directives:

  • #define
  • #elseif
  • #else
  • #endif
  • #if
  • #ifdef
  • #ifndef
  • #include
  • #undef
  • rcinclude

The SMART Resource Conversion utility does the following for you:

  • Reformats all Windows resource definition statements to the equivalent OS/2 format
  • Generates alternate accelerator key sequences
  • Reformats strings contained in RCDATA to produce equivalent binary representation in the .RES file
  • Converts mnemonic characters
  • Scales and recalculates Windows dialog units to OS/2 dialog units
  • Remaps Windows dialog control styles to OS/2 dialog control styles
  • Remaps common dialog control identifiers to equivalent OS/2 common dialog control identifiers
  • Detects named resources and generates the header file to assign integer identifiers
  • Provides optional dialog font mapping from Windows font name and point size to OS/2 font name and point size
  • Performs code page conversion of text strings from Windows code page to OS/2 code page

The SMART Resource Conversion utility converts any Windows resource with equivalent function to the OS/2 resource. The utility also identifies all resource statements and points out those which may result in slightly different function in OS/2.

To start the SMART Resource Conversion utility, select Translate Resources... from the Resources menu. (It can also be invoked from a command line or embedded in a batch command file.) When the utility encounters a problem during the conversion process, it will output information, warning, or error messages. You can get a more detailed explanation of these messages from the SMART help.

The SMART Resource Conversion utility has many run-time options. But if you want, you can specify the resource file name without options to process your resource files with the system default parameters.

Graphical Resource Conversion

The SMART Windows to OS/2 Graphical Resource Conversion utility (SMARTCVT.EXE) converts your binary Windows resources, such as icon, cursor, and bitmap files, to OS/2 pointer files and bitmap files, respectively. (Icon and cursor files are referred to as pointer files in OS/2.) The graphical format of Windows icons and cursors is significantly different from OS/2 pointer files.

To start the Graphical Resource Conversion utility, select Convert Graphical Resources... from the Resources menu. (It can also be run from a command line or embedded in a batch command file.) If the utility encounters a problem during the conversion process, it will output information, warning, or error messages.

SMART Help Conversion

To complete the automatic migration of your application to OS/2, you will need to convert your Windows help files to OS/2 help files. To do this SMART has a Windows to OS/2 Help Conversion utility (SMARTHLP.EXE). You can start the Help Conversion utility from the SMART interface, from the command line, or from a command file. To convert your Windows help to an OS/2 .IPF file, specify the .HPJ file as the input file. If you start the SMART Help Conversion utility without specifying any options, your help files will be converted using default options.

The Windows .HPJ file is not much more than a list of Rich Text Format (.RTF) files and bitmap (.BMP) files. The Help Conversion utility processes the .RTF files directly and calls the conversion utility program, SMARTCVT, to process the .BMP files. All of these Windows help components are then combined to make an .IPF file, which is passed to the IPF compiler (IPFC) to produce an OS/2 help file (.HLP or .INF) that can be accessed by the OS/2 Help Manager facility.

Summary

The SMART migration process involves many steps. In this article, we looked at the SMART Source Code Migration, and Resource Analysis and Translation, as well as other supporting SMART tools, such as the SMART Editor, the Graphical Resource Conversion utility, and the SMART Help Conversion utility. We briefly described how to use SMART and the Developer API Extensions to migrate your applications to OS/2. With all these tools and the Developer API Extensions, you should now be well on your way to exploiting the power of 32-bit OS/2.

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Retrieved from "http://www.edm2.com/index.php?title=Migrating_Your_Source_Code_to_OS/2_Warp,_Part_3:_Migration,_Analysis,_and_Translation&oldid=39009"