View source for Easing the Windows to OS/2 Migration Path Using Common Functions

''by [[Jeff English]], One Up Corporation''

Many of you might know that the [[Source Migration Analysis Reporting Toolset]] (SMART), developed by the One Up Corporation, can be a key component of a successful migration project. The functions and knowledge-base contained in SMART are essential to both sizing your migration effort, and to performing much of the source code migration. However, the version of SMART contained on the Developer Connection for OS/2 CD-ROMs, Volumes 3 and 4, does not have all the function of the retail version of SMART. The retail version of SMART provides a vast array of capabilities for realistic migration of your source code. It also contains an extended toolset including the Windows to OS/2 Resource File Conversion Utility, Windows to OS/2 Icon and Cursor Conversion Utility, SMART Database Viewer Utility, as well as enhanced capabilities of the SMART Migration Application.

SMART migration automates many of the necessary changes to your source code. Furthermore, SMART migration identifies and provides the programmer a detailed description of several alternative implementations for the remainder of the issues ("keywords"). Our migration experience shows that you can greatly reduce the amount of effort required to complete the remainder by using, what we term, common functions. The phrase, common functions, refers to the implementation of source platform functions as their equivalent target platform functions. Because the migration of many keywords involves replacing the existing function with multiple lines of code, using common functions can reduce the amount of code and coding changes required. One Up Corporation has already implemented over 160 of the most needed common functions. Common functions produce an additional time and money savings and are available as an enhancement to the retail SMART product.

Selecting candidates for common functions is a very subjective process. You must evaluate the analysis report for your application and review the difficulty and hit counts for each of the keywords. As a rule, a keyword is a candidate if the hit count is at least twenty and the SMART difficulty category is 030 or higher. After you identify a candidate and review the use of that keyword throughout the application, you will probably gain migration speed by implementing the particular function or defining an appropriate macro.

As an example, assume the SMART analysis report for a Windows application shows that GetMenuString occurs 100 times. This is a category 030 keyword because the flag indicating how to interpret the menu identifier can specify the menu item either by command or by position.

 GetMenuString(hMenu, ID_MENU, szBuffer, sizeof(szBuffer), MF_BYCOMMAND);
 GetMenuString(hMenu, 2, szBuffer, sizeof(szBuffer, MF_BYPOSITION);

If after examining the code, you find that all of the GetMenuString calls are requesting the text by command, you could decide to just implement GetMenuString as a macro that sends the MM_QUERYITEMTEXT messages.

 #define GetMenuString(hmenu,iditem,lpsz,cchMax,fuFlags)\
         WinSendMsg (hmenu, MM_QUERYITEMTEXT,\
         MPFROM2SHORT(iditem,cchMax), MPFROMP(lpsz))

On the other hand, if you have a mix of requests by both command and position, you could decide to implement GetMenuString as a function that sends the appropriate messages based on the specified flag.

 #define MF_BYPOSITION   0x0400
 int GetMenuString (HWND hMenu, int idItem, PSZ, psz, int iMax, ULONG fuFlags)
 {
     if (fuFlags & MF_BYPOSITION)
         idItem = WinSendMsg (hMenu, MM_ITEMIDFROMPOSITION,
                  MPFROMSHORT(idItem), MPVOID);
     return (int)(WinSendMsg (hMenu, MM-QUERYITEMTEXT,
                             MPFROM2SHORT(idItem, iMax), MPFROMP(psz));
 }

The goal is to minimize the number and difficulty of those changes that must be made by the programmer. Two things are accomplished by using common functions wherever possible:

The number of physical changes that must be made to source can be significantly reduced. Debugging your implementation of the functions is minimized to a single macro or function.

Also, you should place all common functions into a single, separate source file or library. This can ease your effort during the debugging phase and let you begin abstracting function for future migrations.

The use of common functions is an extremely effective tool in migrating source code from one platform to another. The proper and judicious usage of common functions can further reduce the programmer's portion of the migration up to 40%. Seasoned programmers can create as many of these common functions as they require, or anyone could simply obtain the retail SMART product and the common functions enhancement. Either way, you're on your way to further savings of both time and money. 

{{IBM-Reprint}}
[[Category:Developer Connection News Volume 5]]