Migrating Your Source Code to OS/2 Warp
The Source Migration Analysis Reporting Toolset (SMART) is the migration toolset developed by One Up Corporation. In our last Developer Connection CD-ROM, we brought to you SMART Version 1 and the SMART Analysis and Reporting Tool, Version 2.
The last Developer Connection News provided a summary of the SMART toolset components. Extensive information on each of these components is included in the variety of SMART online documents. The SMART documentation can be found in the SMART folder after you install SMART.
This, and a series of articles to be published in subsequent volumes of The Developer Connection News, will focus on how you can extend the SMART migration tables and dictionaries to enhance the productivity of your migration process.
The Migration Process
The SMART migration process consists of five main steps:
- Source Code Analysis
- User-Defined Migration Database Development
- Source Code Migration
- Resource Analysis
- Resource Translation
This article covers Source Code Analysis only; subsequent articles will cover the rest of the steps.
Source Code Analysis
The SMART Analysis and Reporting Tool analyzes your source code and resources and provides a report on the level of difficulty required to migrate source code from Windows to OS/2 Warp.
The SMART Analysis and Reporting Tool generates three reports, which provide you the detailed analysis of your source code from different perspectives. They are the Analysis Summary Report, File Detail Report, and Keyword Detail Report.
Analysis Summary Report
The SMART analysis of a typical application provides the following Analysis Summary Report: Migration Analysis Report Summary
Total File Count 1 Total File Size (Bytes) 5,105 Total Source Lines 147 Total Code Lines 121 Total Category 000 Hits 6 Total Category 010 Hits 27 Total Category 020 Hits 10 Total Category 030 Hits 7 Total Category 040 Hits 5 Total Category 050 Hits 1 Total Migration Hits 56 Total Cat 000 010 Hits Auto Migrated 33 Total Hits MiCL Processed 0 Total Hits Processed with UDMD 0 Total Hits Excluded 0 Total Migration Keyword Instances 38 Estimated Migration Effort Without SMART 19.8 Savings from SMART Base Migration 2.3 Savings from Cat 010 Auto Migrate 5.8 Savings from Keyword Exclusions .0 ** Net Migration Effort ** 11.7 Percent Effort Reduction using SMART 40.9 %
Total File Count, Total File Size (Bytes), Total Source Lines, and Total Code specify the number of files analyzed, the total size of the files in bytes, the total lines in the source files, and the total lines of source code, respectively.
SMART identifies items or keywords that will require migration to OS/2 Warp. SMART groups them into categories, based on the level of difficulty required to migrate the items. The Total Category Hits contains the number of migration items by category. The SMART categories are as follows:
- 000 Informational only
- An exact match of the keyword exists in OS/2 Warp. There might be a change in the size or type (for example, a short to a long).
- 010 Literal replacement
- An equivalent definition exists in OS/2 Warp. A literal change in the keyword is required (for example, LPSTR to PSZ).
- 020 Replacement with parameter changes
- The equivalent function exists in OS/2 Warp, but parameters or fields of a structure differ slightly from the source platform definition. This category also includes some of the parameters that are not required in OS/2 Warp.
- 030 Change with more/less API calls
- The equivalent function exists in OS/2 Warp, but the function must be implemented with more, or sometimes less, function calls. This category also includes items that map to one of several choices depending on the type of parameter.
- 040 Logic changes required
- Similar function exists in OS/2 Warp, but the logic must be reworked.
- 050 Functionality does not exist
- The function is not available on OS/2 Warp.
- 999 Dictionary entry not defined
- The SMART database does not currently have a complete description for the migration of the keyword.
Total Migration Hits indicates the total number of items that you must migrate to OS/2 Warp to port our sample application.
Total Cat 000 010 Hits Auto Migrated indicates the number of items that SMART will migrate automatically to OS/2 Warp. For our sample, this report indicates that of the 56 Total Migration Items, SMART will automatically migrate 33, or 57%, of the items.
SMART Version 2 includes a Migration Command Language (MiCL) that lets you program the migration process for each keyword affected. Through the use of SMART MiCL commands, SMART prompts you for data, or processing options, when it detects an occurrence of a migration keyword. The SMART MiCL commands extend SMART to be more interactive and are used within the SMART User-Defined Migration Databases (UDMD).
Total Hits MiCL Processed is the number of MiCL commands processed. For this SMART Analysis Summary Report, we did not make use of a UDMD or MiCL command. Therefore, this line contains a 0 in the SMART Analysis Summary Report for our sample.
The UDMD function lets you create your own migration tables and data bases. You can analyze and migrate your source modules by specifying the use of your UDMD or a SMART table (for example, Windows 3.1 to OS/2 Warp), or by specifying the use of one or the other (for example, a UDMD or the SMART table). UDMD lets you override equivalent migration items or keyword entries in the SMART tables and expand the list of migration items or keywords SMART automatically converts. This lets you map keywords from the Windows platform to OS/2 Warp once; then you can use the UDMD for multiple instances of the keyword in your source code.
Total Hits Processed with UDMD is the number of keywords processed for which the mapping or migration is specified in the UDMD. For our sample, this value is 0 because we did not use a UDMD when creating this SMART Analysis Summary Report.
SMART uses keywords listed in an Exclude file to override the SMART table and a UDMD to omit processing of keywords. The Total Hits Excluded is the number of keywords that were not processed because they appeared in the Exclude file. Examples of items or keywords to include in this file are simple APIs that might have been implemented for OS/2 Warp on your own (for example, min and max).
Total Migration Keyword Instances indicates the total number of unique ways an item or keyword is used in the source code.
Estimated Migration Effort Without SMART is the approximate effort (in many cases, the approximate number of hours) to manually migrate the source code to OS/2 Warp.
Savings from SMART Base Migration and Savings from Cat 010 Auto Migrate are the effort saved from the category 000 and 010 items.
Savings from Keyword Exclusions is the migration effort saved by having SMART ignore the keywords or migration items in the Exclude file.
Savings from SMART Base Migration, Savings from Cat 010 Auto Migrate, and the Savings from Keyword Exclusions are subtracted from Estimated Migration Effort Without SMART to provide the ** Net Migration Effort **. The ** Net Migration Effort ** is the net approximate effort to migrate our sample application to OS/2 Warp. However, the migration effort depends on your experience with both Windows and OS/2 Warp.
For a better indication of what this number means, migrate several source code modules. Compare the effort indicated by SMART to the effort spent by you using SMART and making any manual changes required to fully migrate those modules to OS/2 Warp. This exercise will give you an indication of the Effort Modifier. The Effort Modifier can be entered at the SMART Source Code Analysis dialog box during the SMART analysis process to obtain effort numbers that are based on your Windows and OS/2 Warp programming experience. As you can guess, the migration and analysis process is iterative.
The Percent Effort Reduction using SMART takes the percentage of the total of all the savings of the SMART migration from the Estimated Migration Effort Without SMART (that is, (2.3 + 5.8)/19.8 * 100 = 40.9%). When we discuss UDMD database development, in future articles, you will see how you can improve on this number by investing some time in creating UDMDs.
File Detail Report
The File Detail Report presents a detailed analysis of each source file. Most of the information presented in the SMART File Detail Report is shown in the SMART Analysis Summary Report. The SIZE, LINES, and CODE columns indicate the file size (in bytes), the lines in the file, and actual lines of code in the file, respectively. HITS indicates the number of keywords or migration items in the source code module. PCT HITS is the percentage number of hits based on the lines of source code (CODE). INSTS is the number of unique ways the keywords or migration items have been used within the source code. EFFORT, as in the SMART Analysis Summary Report, is the approximate effort to migrate the source module to OS/2 Warp.
Keyword Detail Report
The Keyword Detail Report presents a breakdown of the keywords identified during the analysis. The analysis data is presented as follows:
- Keyword breakdown by SMART category
- Keyword breakdown by the types of the keyword
- Keyword breakdown by functional area
- Breakdown by individual keyword Hits Pct Hits Files Insts Pct Insts Effort
Categories 000 Informational only 6 10.7 1 2 5.3 .0 010 Literal replacement 27 48.2 1 16 42.1 .0
Types 010 Function 18 32.1 1 16 42.1 7.8 020 Message 5 8.9 1 4 10.5 1.5
Areas 060 Resource-Management 2 3.6 1 2 5.3 2.0 200 Message 8 14.3 1 7 18.4 2.6
Keywords MessageBeep 2 3.6 1 .3 HANDLE 2 3.6 1 .3
The SMART Keyword Detail Report helps to determine exactly the migration items SMART will automatically migrate for you. This SMART Analysis Report also helps you determine if you should write a UDMD to enhance the SMART migration.
The SMART migration process involves several steps, including the source analysis, which is a critical first step when migrating source code to OS/2 Warp. In subsequent articles, we will take you through the rest of the steps in the migration process. These articles, coupled with SMART, will get you well on your way to exploiting the power of 32-bit OS/2.
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation