Migrating Your Source Code to OS/2 Warp, Part 2

From EDM2
Revision as of 08:54, 2 January 2018 by Ak120 (Talk | contribs)

Jump to: navigation, search

by Ingrid Rodriguez

This volume of The Developer Connection for OS/2 marks a year since we began delivering SMART to your door. For those of you who have just joined us, SMART is the Source Migration Analysis Reporting Toolset, developed by One Up Corporation. SMART assists application developers in migrating 16-bit Windows and OS/2 source code and 32-bit Windows source code to OS/2 32-bit source code.

On the last Developer Connection for OS/2 CD-ROM, we brought to you SMART Version 2 Volume 7 of The Developer Connection for OS/2 brings to you an enhanced SMART Version 2.1A, including:

  • An enhanced 32-bit Windows dictionary
  • A Windows Help text conversion utility
  • Additional User-Defined Migration Databases

As mentioned in Volume 6 of The Developer Connection News, the SMART migration process consists of five main steps:

  1. Source Code Analysis
  2. User-Defined Migration Database (UDMD) Development
  3. Source Code Migration
  4. Resource Analysis
  5. Resource Translation

Volume 6 of The Developer Connection News covered the first step of the SMART migration process, Source Code Analysis. This article discusses the second step of the process User-Defined Migration Database Development. More information can be found on your accompanying Developer Connection for OS/2 CD-ROM.

SMART Keyword Detail Report

The first article of this series discussed the SMART Keyword Detail Report, which looked like this:

CATEGORIES          HITS  PCT HITS  FILES  INSTS  PCT INSTS  EFFORT
 000 Informational    6     10 7      1      2        5 3       0
     only
 010 Literal         27     48 2      1     16       42 1       0
     replacement
     calls

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-Mgmt    2      3 6      1      2        5 3     2 0
 200 Message          8     14 3      1      7       18 4     2 6

KEYWORDS (by Category and Hits)
 050 Functionality does not exist
     DLGWINDOWEXTRA   1      1 8      1                       1 6

 060 Resource-Mgmt
     WinMain          1      1 8      1                       1 0
     SetFocus         1      1 8      1                       1 0

 030 Change with more/less API calls
     SendMessage      2      3 6      1                         8
     WINDCLASS        2      1 8      1                       1 0

 020 Replacement with parameter changes
     MessageBeep      2      3 6      1                         3
     HANDLE           2      3 6      1                         3

 010 Literal replacement
     DWORD            5      8 9      1                         0
     PASCAL           3      5 4      1                         0

Figure 1. A partial representation of a SMART Keyword Detail Report

The SMART Keyword Detail Report shows that there are a few migration items that are not automatically migrated by SMART. To analyze these items we can use the SMART Viewer tool.

The SMART Viewer

You can find the SMART Viewer in the SMART folder (when you install SMART on your system from The Developer Connection for OS/2 CD-ROM, disc 1). You can start the SMART Viewer directly from that folder or from the SMART Editor through a REXX macro provided with the SMART package.

The SMART Viewer provides context-sensitive online help for the SMART migration. You can use the SMART Viewer to search on a topic name. The information on that topic will appear in a SMART Viewer window. The SMART Viewer also provides Template, Prototype, Example, and References for a migration keyword.

Let's use the SMART Viewer to look at the information provided for some of the items in category 020. Category 020 items are migration items for which an equivalent function exists in OS/2 Warp, but parameters or fields of a structure differ slightly from the Windows platform definition. This category also includes some of the parameters that are not applicable or required in OS/2 Warp. The goal of using the SMART Viewer to analyze the information provided for these items is to determine if we can expand the SMART knowledge base by writing a UDMD that will automatically migrate these items.

The SMART Viewer provides the following information for MessageBeep:

Cat 020        Type 010         Area 320

     Replace with WinAlarm   Note that there are a number of
     additional alarm values available in OS/2 

Figure 2.

The SMART Viewer also provides the following WinAlarm information for sample, prototype, and template:

SAMPLE

Windows 
   MessageBeep (MB_OK);
OS/2 
   WinAlarm (HWND_DESKTOP, WA_WARNING);

PROTOTYPE
   BOOL APIENTRY WinAlarm(HWND hwndDesktop, ULONG rgfType);

TEMPLATE
   WinAlarm (HWND_DESKTOP, );

Figure 3.

We can use the information provided by the SMART Viewer to create a UDMD which will migrate the MessageBeep call to the WinAlarm call for all instances of MessageBeep in our sample application source code. In fact, we can use the same analysis process to create a UDMD that will convert all of the category 020 items in our sample application source code to category 010 items, which SMART will then migrate automatically for us.

User-Defined Migration Database Language

UDMDs are ASCII text files that contain format tags and data SMART allows you to use one database at a time with a SMART migration database. The UDMD (text file) is converted into a SMART migration database format and tables using Tables and Create User UDMD from the SMART main menu. The ASCII text file looks like this:

 Notice   =A Copyright statement can be placed here
 Table    =This is the place to give this table a title
 Version  =Table version number
 Date     =Date the table was created

 Keyword  =010 010 200 MessageBeep
 SComment =Replace MessageBeep with WinAlarm
 LComment =Replace MessageBeep with WinAlarm   The first parameter
          =to WinAlarm can be the window handle to the desktop   The
          =second parameter to WinAlarm can usually be the first
          =parameter to the MessageBeep Windows call 
 Sample   =Windows 
          =   MessageBeep (MB_OK);
          =OS/2:
          =   WinAlarm (HWND_DESKTOP, WA_WARNING);
 Prototyp =BOOL WinAlarm (HWND hwndDeskTop, ULONG flStyle);
 Template =WinAlarm( HWND_DESKTOP, $P1 );
 Command  =/* Replace source code for MessageBeep, Cat  20 */
          =IF $P1 =  0  THEN $P1 =  WA_ERROR 
          =SmRemove( LINE )
          =SmOutputLine( $T1 )

Figure 4.

The UDMD in Figure 4 consists of format tags that start with a period in the first column. An equal sign appears in column 10. The data for each table element begins in column 11. A colon in column 11 causes SMART to ignore the record (This is useful for creating comments.) Each UDMD input file must contain the table header data at the beginning of the file. The .Notice, .Table, .Version, and .Date tags have been briefly defined in Figure 4. The .Keyword tag is a compound statement that consists of the following parameters:

  • Type Code: 3 characters, column 11-13 (example 010)
  • Category Code: 3 characters, column 15-17 (example 010)
  • Functional Area Code: 3 characters, column 19-21 (example 200)
  • Keyword Name: Column 23 (example MessageBeep)

The Type Code, Category Code, and Functional Area Code are values that must match the valid codes specified in the SMART migration database. You can obtain this information through the SMART Viewer (as shown for the MessageBeep keyword in Figure 2).

  • The .SComment tag is a one-line, short comment for the migration keyword.
  • The .LComment tag is a one-line or multiple-line comment for the migration keyword.
  • The .Sample tag is a one-line or multiple-line example source code showing how to implement the keyword.
  • The .Prototype tag is a one-line or multi-line source code specifying the function prototype for the migrated keyword.
  • The .Template tag is the specification for the code generated for the SMART migration.

SMART Migration Command Language

You can use the SMART Migration Command Language (MiCL) to create a migration command using the Template tag. The SMART MiCL predefines a number of variables, which begin with a dollar sign ($). Variables within the range $P1 - $P99 contain the argument string of an API keyword. In the Template that appears in Figure 4, $P1 stands for the first parameter to the MessageBeep API.

SMART includes several built-in functions that can start from within the SMART UDMD Command lines, such as SmRemove and SmOutputLine. The SmRemove function removes the keyword, the source code line in which the keyword is found, or the complete statement block in which the keyword is found The type of removal is indicated with the following parameter types:

  • KEYWORD
  • LINE
  • BLOCK

Figure 4 uses the LINE removal type. You can use SmRemove with the SmOutputLine function to replace source code with new output source code (as shown in Figure 4). The parameter to SmOutputLine can be a variable or a literal string In Figure 4, the value of the parameter $T1 is evaluated as the first template string.

SMART MiCL Logic

As you may have noticed in Figure 4, you can implement some amount of logic through IF/THEN/ELSE clauses in the UDMD MiCL commands.

Figure 4 states that, for each MessageBeep keyword found, the keyword (that is, MessageBeep) should be treated as a category 010 migration item during both the SMART analysis and the migration. In addition, when the keyword is migrated, the first parameter of the MessageBeep Windows API (the only parameter in this case) is to be used in place of the second parameter in the WinAlarm OS/2 Warp API. This is to be done only if the value of that first parameter ($P1) is not equal to 0, in which case the value of $P1 is set to WA_ERROR (that is, IF $P1 = 0 THEN $P1 = WA_ERROR). In either case, the original source code line containing the MessageBeep call is to be replaced with an equivalent line which replaces the MessageBeep for the WinAlarm API call.

You probably noticed that the SMART Keyword Detail Report for our sample application source code indicates that there are only two hits for the MessageBeep keyword and similar numbers of hits for the rest of the category 020 items found in that source code Larger applications with several additional lines of source code would obtain more benefit from the analysis of the MessageBeep information above. These applications also benefit from a UDMD, which would automatically migrate keywords such as MessageBeep and the rest of the category 020 items found in the source code. The amount of time spent in expanding the SMART knowledge base with UDMDs can actually be an investment and savings for additional migration efforts for a large application For additional details on developing SMART UDMDs and MiCL commands, please refer to the online SMART Programming Guide (located in the SMART folder when you install SMART on your system).

For our sample application source code, we spent approximately 2 hours creating a UDMD, and we were able to increase the Percent Effort Reduction Using SMART to 75 5%. The following SMART Migration Analysis Report Summary was produced after adding the use of the UDMD to the SMART migration:

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                                47
    Total Category 040 Hits                                 2
    Total Category 050 Hits                                 1
    Total Migration Hits                                   56

    Total Cat 000 010 Hits Auto Migrated                   53
    Total Hits MiCL Processed                              21
    Total Hits Processed with UDMD                         22
    Total Hits Excluded                                     0
    Total Migration Keyword Instances                      38

    Estimated Migration Effort Without SMART             14 7
    Savings from SMART Base Migration                     2 3
    Savings from Cat 010 Auto Migrate                     8 8
    Savings from Keyword Exclusions                         0

    ** Net Migration Effort **                            3 6
    Percent Effort Reduction Using SMART                 75 5 %

Figure 5.

Notice that the lines Total Hits MiCL Processed and Total Hits Processed with UDMD now indicate that there were hits or migration items processed with MiCL commands and UDMDs. The Net Migration Effort was also reduced to 3.6, or approximately 3.6 hours (The Estimated Migration Effort Without SMART and the Net Migration Effort are approximate numbers and, in many cases, these numbers indicate number of hours.) Notice also that the Total Category 010 Hits increased from 27 to 47 and that there are now no category 020 items reported. That is because we created a UDMD that converted all category 020 items to category 010 items. The UDMD we created also converted all of the category 030 items and three of the category 040 items to category 010 items. Remember that all of the category 010 items are automatically migrated by SMART.

Summary

The SMART migration process involves several steps. We covered the first step of this process, Source Code Analysis, in Volume 6 of The Developer Connection News (which you can read on your accompanying Developer Connection for OS/2 CD-ROM). In this article we discussed the second step - User-Defined Migration Database Development, to help expand your SMART knowledge base SMART uses UDMDs and MiCLs to automatically migrate keywords that would not normally be automatically migrated By developing SMART UDMDs and MiCLs, you can reduce the net migration effort required to migrate your source code to OS/2 Warp.

In subsequent articles we will take you through the rest of the steps in the SMART migration process Source Code Migration, Resource Analysis, and Resource Translation.

We hope that you are now well on your way to exploiting the power of 32-bit OS/2.

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