Microsoftware Monthly 19…2 Programming Power Tools/MASO9512.ISO/smart/sm_guid2.inf

OS/2 Help File | 1995-05-16 | 80.3 KB | 2,304 lines

ΓòÉΓòÉΓòÉ 1. The SMART User's Guide ΓòÉΓòÉΓòÉ

   The SMART2 User's Guide

       Version 2.1B
       May 1995

   (C) 1991, 1994, 1995 One Up Corporation

 Notice
 Table of Contents


ΓòÉΓòÉΓòÉ 2. Notice ΓòÉΓòÉΓòÉ

** NOTICE **

This document may not, in whole or in part, be copied, reproduced, photocopied,
translated, or reproduced to any electronic medium or machine readable form
without prior written consent from One Up Corporation.

This publication could contain technical inaccuracies or typographical errors.
As changes are periodically made to the information herein; these changes may
be incorporated in new additions of the publication. One Up Corporation may
make improvements and/or changes in the product and/or the program described in
this publication at any time.

One Up Corporation is not responsible for any direct or indirect damage or loss
of business resulting from inaccuracies or omissions in this publication.  The
specifications contained in this document are subject to change without notice.

SMART - Source Migration Analysis Reporting Toolset is a trademark of One Up
Corporation. OS/2, Presentation Manager are trademarks of the International
Business Machines Corporation. IBM is a registered trademark of the
International Business Machines Corporation. Other trademarks are property of
their respective companies.

CONTENTS


ΓòÉΓòÉΓòÉ 3. Table of Contents ΓòÉΓòÉΓòÉ

 Chapter 1 - Introduction
  SMART - Concepts
  The Analysis/Migration Process
  What this Document Contains
  Where is the Remaining Documentation?
 Chapter 2 - Installation
  Before You Begin
  Installing SMART
  Setup Options
 Chapter 3 - Getting Started
  Getting Ready
  The Analysis Process
  The Migration Process
  Completing The Migration
  The SMART Viewer
  The SMART Resource Translator
  The SMART Win Help Translator
  Graphical Resource Conversion
  The SMART Editor Development Tool
 Chapter 4 - Techniques
  Preparing Your Source Code
  Reading the Analysis Summary Reports
  Reading the Analysis Display/Report
  Interpreting the Analysis
  Use of Common Functions
  Source Migration Format Considerations
  File Extension Mapping
  Source Migration Comment Code Removal
  Increased Productivity with The SMART Editor
 Chapter 5 - Reference
  Migration Formats
  Specifications and Restrictions
  SMART Files
  Technical Support

CONTINUE - Chapter 1


ΓòÉΓòÉΓòÉ 4. Chapter 1 - Introduction ΓòÉΓòÉΓòÉ

Chapter 1 - Introduction

  SMART - Concepts
  The Analysis/Migration Process
  What this Document Contains
  Where is the Remaining Documentation?

CONTINUE - SMART - Concepts
BACK - Table of Contents


ΓòÉΓòÉΓòÉ 4.1. SMART - Concepts ΓòÉΓòÉΓòÉ

SMART - Concepts

  NOTE: REFERENCES TO SOURCELINK, SMART VIEWER, MIGRATION and RESOURCE
CONVERSION are only applicable with the Analysis AND Migration version of
SMART.  If you are only licensed for the Analysis version of SMART, you may
ignore information in this and other documents to those functions that you may
not have in this product.

  SMART - Source Migration Analysis Reporting Toolset provides analysis and
source code migration assistance from one platform to another or one version to
another on a given platform.  This version of SMART executes on the OS/2
platform and is used for the migration of 'C' and C++ source code from Windows
16 bit to OS/2 32 bit or OS/2 16 bit to OS/2 32 bit or Win32 to OS/2 32 bit
depending upon the licensed, installed tables.

  The process of porting source code from one platform to another is indeed
difficult and subjective.

  In fact, exploiting the features of one platform, and using proprietary
libraries, classes, and objects may make it severely difficult to port to
another platform without a major rewrite of the source code.

  There is no pat solution or utility to port all code to a target platform,
and we dare say there most probably never will be.  However, with the proper
tools, methodology, techniques and training the effort required in the
migration of source code can be GREATLY reduced.

  The most appropriate solution for this process is to use productive computer
tools to perform tasks that are easily identified, routine, and labor intensive
and provide a knowledge base to contain information related to all occurrence
types of differences between the platforms.  The human element is most
appropriately applied where the complexity of the issue is too complicated for
the computer analysis.  It is advantageous to provide the programming
professional with powerful productivity tools to make global changes based on
the migration issues of complex nature.

  SMART is designed to assist in the analysis and migration of native source
code from one platform to another or one version of an operating environment to
another on the same platform.

  The platform dependent data is contained in the migration dictionary (table)
and the migration database files.

  This process is based on finding keywords (API calls, symbols, parameters,
typedefs, etc) that differ between the source and target platforms in the
migration. No attempt is made to analyze the intended use of the application
source code.  As such, there is no intent to evaluate platform exploitation, or
evaluate the use of the source code for application functionality such as MDI,
DDEML, communication, LAN, and etc. The base API keyword differences are
categorized into groups to represent the difficulty in migration, ranging from
a simple literal replacement to the case where the functionality does not exist
in the target platform.

  In the Analysis process, SMART will analyze source code and prepare a report
(display) providing a detailed evaluation of the migration requirements.

  Furthermore, in the migration process, SMART will process the user specified
source files and create migrated source files.  The migrated source file will
contain automatic migration changes (where possible) and in all cases will
provide in-line commented code for the developer to complete the migration.

CONTINUE - The Analysis/Migration Process
BACK - Chapter 1 - Introduction
CONTENTS


ΓòÉΓòÉΓòÉ 4.2. The Analysis/Migration Process ΓòÉΓòÉΓòÉ

The Analysis/Migration Process

  There are several key concepts regarding the operation of the SMART Toolset
including: The List-of-Files, keyword, category and hit.

  A List-of-Files is a text file that contains all of the fully qualified
filenames for the source files to be processed by SMART.  Typically this will
include all program source files (.C) and all header files (.H).  Resource
files are migrated in a separate process using the resource translator
(Windows->OS/2 Migration only).

  Keywords are items that are the basis for the definition of the interface to
a platform and may represent API (Application Programming Interface) calls,
symbols, parameters, structures, and typedefs.  Keywords are the basis for
migration with SMART.  As keywords are encountered in the SMART Analysis and/or
Migration processes SMART will look to the migration tables to indicate the
appropriate change as required.

  Category is a key concept in the SMART process of source code migration.  All
of the items to be considered for migration are identified by its migration
difficulty.  The "category" of difficulty increases in effort and consideration
and range from a category of "000" to the most difficult category of "050".

  There is one additional category of "999" indicating that the keyword has not
been defined.  This simply indicates that a keyword is identified for
migration, but the explanation for the migration has not yet been defined in
the SMART database.

  The definitions for the difficulty categories are as follows:

  000  Informational only - An exact match of the keyword exists in the target
platform but there is change in the size of type. (e.g. short to a long).

  010  Literal replacement or Automatic migration - An equivalent definition
exists in the target platform but a literal change in the keyword is required
(e.g., LPSTR to PSZ) or keywords that are automatically migrated through the
use of MiCL Commands.

  020  Replacement with parameter changes - Equivalent functionality exists in
the target platform but parameters or fields of a structure differ slightly
from the source platform definition (e.g., SetWindowPos to WinSetWindowPos).
Also  included are parameters that are not applicable or required on the target
platform (e.g., MakeProcInstance).

  030  Change with more / less API calls - Equivalent functionality exists in
the target platform but it must be implemented with  more, or sometimes less,
function calls (e.g., DlgDirList).  Also included are items which map to one of
several choices depending upon the type of parameter used (e.g., GetObject).

  040  Logic changes required - Similar functionality exists in the target
platform but the logic required to emulate the functionality must be reworked
(e.g., CreatePatternBrush).

  050  Functionality does not exist - There is no means provided to perform the
same functionality in the target platform (e.g., GetKeynameText).  Workaround
coding must be implemented, where possible.

  999  Dictionary entry not defined - The database does not currently have a
complete description for the migration of the keyword.

  A Hit is simply a term referring to a match between a keyword in your source
code and an item in the migration database indicating that a code change may be
required.

CONTINUE - What this Document Contains
BACK - SMART - Concepts
CONTENTS


ΓòÉΓòÉΓòÉ 4.3. What this Document Contains ΓòÉΓòÉΓòÉ

What this Document Contains

  This document, contains an introduction in the use of the application
development tool SMART.

  Detailed information regarding individual functions, dialog panels, controls,
parameters and options is available in the on-line documentation accessible
when SMART is running.  By pressing "F1" or accessing the on-line help through
the "Help" menu items you can obtain details regarding the specific operation
of SMART.

  Neither this document nor the SMART on-line help will attempt to cover
specific platform migration issues beyond the help found in the on-line
migration data base access through the SMART Viewer.  Migration issues are
covered in the documentation of the specific platforms and are left to the
developer to research.

  This document may make reference to utilities and functions that may be
specific to a particular platform and may not be included in your licensed copy
of SMART.

  Programming UDMD dictionaries, including programming with MiCL Commands is
fully explained in the document file "SMART2 Programming Guide" found in the
SMART2 Desktop Folder.

  The complete documentation of The SMART Editor is found in the separate
manual entitled "The SMART Editor Technical Manual".

  The chapters of this document flow in a logical order to acquaint you with
the concepts, principles and general introduction to SMART.

  Chapter 1 - Introduction

   An introduction to the SMART methodology of source code migration and the
functionality of the SMART Toolset.

  Chapter 2 - Installation

   Step-wise instructions in the installation of SMART.

  Chapter 3 - Gettiong Started

   A guided introductory tutorial for executing the analysis and migration
processes.

  Chapter 4 - Techniques

   A set of topics covering important techniques in the use of SMART.

  Chapter 5 - Reference

   A chapter related to reference topics including migration formats
specifications and technical support for this product.

CONTINUE - Where is the Remaining Documentation?
BACK - Analysis/Migration Process
CONTENTS


ΓòÉΓòÉΓòÉ 4.4. Where is the Remaining Documentation? ΓòÉΓòÉΓòÉ

Where is the Remaining Documentation?

  It's on-line and accessible as you run SMART.  We intentionally put the
details of all the parameters, options and definitions of the dialog controls
on-line.  This puts your reference material where you need it most -
contextually sensitive at the point of processing.

  While you are processing SMART press "F1" to obtain help at any menu item or
dialog panel.  You can also use the menu items under "Help" on your main menu
bar to browse through the SMART On-Line help facility.  In addition to the
index and contents panels, you can view panels on additional One-Up products,
reference material and tutorials on the Analysis or Migration processes.

CONTINUE - Chapter 2 - Installation
BACK - What This Document Contains
CONTENTS


ΓòÉΓòÉΓòÉ 5. Chapter 2 - Installation ΓòÉΓòÉΓòÉ

Chapter 2 - Installation

  Before You Begin
  Installing SMART
  Setup Options

CONTINUE - Before You Begin
BACK - Where is the Remaining Documentation?
CONTENTS


ΓòÉΓòÉΓòÉ 5.1. Before You Begin ΓòÉΓòÉΓòÉ

Before You Begin

  Before you begin the installation of SMART you may wish to take a moment to
insure that you are prepared for the installation.

  You can install SMART from CD-ROM or you can install from Diskette.  If you
have this product on CD-ROM you can create diskettes for installation by
executing the command MAKADSK or MAKMDSK (Depending on whether you have the
analysis version of SMART or the Analysis and Migration).  This command file
requires that you specify the full drive and directory path of the SMART base
files on the CD-ROM.

  If you are licensed for The SMART Editor, The SMART Editor documentation
regarding installation in The SMART Editor Technical Manual.  Your installation
of SMART will consist of an Install diskette and one or more migration table
diskettes depending upon your license.

  The hard disk space requirements for the basic installation is as follows:

  SMART Source Migration:
   Win3.1 -> OS/2 2.1 -   8 megabytes
   Win32 -> OS/2 2.1 -   12 megabytes
   OS/2 16->32 bit -     3 megabytes
  The SMART Editor:       2 megabytes

  If you have received this product on CD-ROM you can perform a mini-install of
the SMART on your hard disk (requiring only 15 KBYTES) and run from the CD-ROM.

  This space only considers the installation files and does not include files
created during the run time execution of either SMART or The SMART Editor.

  Depending upon the migration formats chosen, you may experience file
requirements over five or six times the original source code space in the
source migration and The SMART Editor hyperlink data base build.

CONTINUE - Installing SMART
BACK - Chapter 2 - Installation
CONTENTS


ΓòÉΓòÉΓòÉ 5.2. Installing SMART ΓòÉΓòÉΓòÉ

Installing SMART

  The installation of SMART is simple.

 1.  Start by inserting the SMART Installation diskette into your floppy drive
    (A or B) or change directory to the CD-ROM directory containg the SMART
    files. (Depending upon the source of your SMART installation files).

 2.  From an OS/2 command line, type:  a: (or b:), then  install

 3.  A SMART installation window will appear to guide you through the
    installation.

 4.  When ready, select "Install" from the main installation menu bar.

 5.  You will be requested to specify the directory that will contain all of
    the SMART executing files and will be the root for subsequent
    sub-directories to contain sample files and migration tables.

 6.  You will also have an opportunity to select other installation parameters,
    including the Platform Tables to be installed (For Full disk installation).

 7.  Responding to all of the installation pop-up panels with an "Ok" (Enter
    key) will result in the default installation.

 8.  It is recommended that you store the SMART DLLs in the directory with the
    other SMART executables.  To do so, you must have a "." (current path) in
    the LIBPATH statement in your CONFIG.SYS file.  If not, then you must store
    the DLL in a path specified by the LIBPATH statement.

 9.  At the conclusion of the installation of SMART a desktop icon will be
    created for the SMART application and the SMART Viewer and two SMART
    Information Files.

10.  If you have not already installed The SMART Editor, please follow the
    instructions in Chapter 3 of The SMART Editor Technical Manual to properly
    install this companion application. You should install The SMART Editor
    before SMART if you are licensed for this product.

CONTINUE - Setup Options
BACK - Before You Begin
CONTENTS


ΓòÉΓòÉΓòÉ 5.3. Setup Options ΓòÉΓòÉΓòÉ

Setup Options

  After you have successfully installed SMART on your computer you may need to
modify the initial setup options in the SMART application.

 1.  Open the Setup Options dialog panel by selecting "Setup Options" under the
    "Options" main menu item.

 2.  Check to insure that your editor is specified in this panel.  If you have
    installed The SMART Editor, your editor name will be SLSTART. If you are
    using any other editor, enter the path and filename of the editor in the
    "Editor/Browser" entry field.

 3.  The next item of importance is to insure that you have specified the
    appropriate SMART Migration Table filename in the Tables Selection panel,
    under the "Tables" main menu item.

 4.  Both SMART and The SMART Editor allow you to drag-and-drop a selected font
    from the OS/2 system font palette onto the menu bar of the application in
    order to set all window fonts. After you have dropped the selected font,
    close and reopen the application to propagate the selected font throughout
    the application.

 5.  Once you have installed The SMART Editor you can register the SMART Viewer
    REXX macro (SMVIEWER.REX) under the "Macro" menu item.  To accomplish this,
    pull down the "Macro" menu list in The SMART Editor and select "Define Menu
    Item".  Choose "Add" and complete the dialog panel to register SMVIEWER.REX
    as a macro item, with your chose of accelerator key. Using this macro, you
    can mouse click on a source platform keyword and press your chosen
    accelerator key to display SMART Viewer on-line migration help.

  Within SMART Viewer you can drop your chosen font on the client area of the
application. After you have set the application font you can set the fonts for
each of the on-line display windows.

  The following chapters in this document will guide you through the basic
functionality in the Analysis and Migration processes of SMART.

CONTINUE - Chapter 3 - Getting Started
BACK - Installing SMART
CONTENTS


ΓòÉΓòÉΓòÉ 6. Chapter 3 - Getting Started ΓòÉΓòÉΓòÉ

Chapter 3 - Getting Started

  Getting Ready
  The Analysis Process
  The Migration Process
  Completing The Migration
  The SMART Viewer
  The SMART Resource Translator
  The SMART Win Help Translator
  Graphical Resource Conversion
  The SMART Editor Development Tool

CONTINUE - Getting Ready
BACK - Setup Options
CONTENTS


ΓòÉΓòÉΓòÉ 6.1. Getting Ready ΓòÉΓòÉΓòÉ

Getting Ready

  You may wish to become familiar with SMART by using the sample source code
files supplied in the installation of SMART under the "Samples" sub-directory.
You can follow along with this chapter and use the steps as a general tutorial,
or you may wish to strike out on your own and explore the SMART functionality
on your own files.

  Before you start processing, it is always a good idea to backup your original
source code. SMART Source Migration generates source code.  Sparing you the
pain of inadvertently overwriting original source code, it is well advised to
"hide" your original code during your processing.

  SMART creates analysis files in the same directory as the source code being
analyzed. If you are running from CD-ROM and using the application sample
files, you will need to copy these files to your read/write hard drive.

  It is also advised that you always use the option to generate the changed
code using the extension mapping.  This will insure that a SMART process
creates a file of similar name, having a different file extension to maintain
uniqueness.  Using this technique, you can simply rerun the process, if needed,
without losing the original source file.

  You will most probably wish to run the SMART migration process multiple times
on a sample code set with different format options to insure that you achieve
the desired results for your particular needs.

CONTINUE - The Analysis Process
BACK - Chapter 3 - Getting Started
CONTENTS


ΓòÉΓòÉΓòÉ 6.2. The Analysis Process ΓòÉΓòÉΓòÉ

The Analysis Process

  The analysis of source code for an evaluation of the migration and porting
effort is accomplished through the use of SMART Analysis Procedure.

  This procedure simply consists of creating a text file (called a
List-of-Files) with the fully qualified filenames of the files to be analyzed,
and then perform the analysis procedure.

  The results of the analysis can be viewed on-screen and printed using The
SMART Editor or a word processing application.

  First, create your analysis directories and sub-directories.

  Each separate analysis should be performed from a separate directory. The
directory will contain the "List-of-Files" file, and subsequently will contain
analysis files created by the SMART Analysis process.

  If separate analyses are to be created, each to represent a different
component of the product under analysis, an individual sub-directory should be
created to contain the analysis files.  Each "List-of-Files" for individual
analyses should have a different filename, even though they will be in a
different sub-directory for ease of identification. Sub-directories can be
created from The SMART Editor using the "Copy"  function under the "More" main
menu selection.

  Select the directory to create the new sub-directory in the "TO" section of
the "Copy" dialog panel.  Type the name of the new sub-directory in the "TO"
"File" entry panel and press "Make Dir.". Note that you will automatically be
placed in this new sub-directory.

  Copy the source files to be analyzed to a backup directory  (and appropriate
sub-directories) that will be used in this analysis. Create the "List-of-Files"
files containing the files for the  analysis.  Use the "Maintain List-of-Files"
function under the "Files" main menu item in SMART or the equivalent function
in The SMART Editor under the "Link" main menu.  The files in this list may
span multiple directories and even drives.

  Execute "Analyze Code" under the "Analysis" Menu selection. Take care to
select the proper option on the setup panel for this function.

  The standard options will have only the "Send Analysis Output to Editor"
checked (all other options unchecked).  The  "List-of-Files" filename should be
shown in the "List-of-Files" entry panel.  If you chose to create a The SMART
Editor Link Database, you will be able to hyperlink to points of change from
the report created from this analysis  procedure.

  NOTE: Multiple instances of SMART can be run at the same time if running more
than one analysis.  This may speed processing.

  At the completion of the analysis, you will be able to print the analysis
report from SMART (as displayed at the completion of the analysis).

  Select "Printer Setup" to select appropriate printer, and then choose "Job
Properties" to select "Landscape" for the printing mode. Close the printing
setup panels with "Ok".

  Select "Formatting" and set the following parameters for the printed format.
Uncheck "Date/Time..." and "Word Wrap".

  Set all page margins to 0.0.

  Press "Select Fonts".  Uncheck "Display" but leave "Printer" fonts checked.
Select the smallest "Courier" font available, "Normal" style.

  Close the "Formatting panels with "Ok". One last check before printing -
insure that "Print File" on the "Print" dialog panel is selected (instead of
"Print Select"). Press "Ok" on the "Print" dialog panel to print the analysis
report. Removal and Backup of Analysis Files.

  To save the analysis files to floppy disk, select "Pack up Analysis Files"
from the "Analysis" menu in SMART  If you are running multiple analyses, you
may wish to perform this step after each analysis.  You will need a floppy disk
with blank sufficient space to perform this function.  You will also need a
copy of the compression utility "PKZIP2.EXE" from PKWARE (not included with
this application).

  The captured data in these analysis files contains absolutely no other
information than appears in the analysis report.  The data is in text and
binary format and is used to rerun the analysis report if necessary with
different file combinations or analysis options.  The files copied to the
floppy disk are of the analysis report, a compress file containing the analysis
numerical summary data, and the text format of the List-of-Files file used for
the analysis.

  After the analysis data is copied to the floppy disk, you can remove the
small summary analyses files by selecting the  "Remove Temp Analysis Files"
from the "Analysis" menu.  Insure that the proper "List-of-Files" file is used
in this process.  If multiple analyses are performed, this process must be
performed for each List-of-Files used.  This process will delete all "*.??^"
files associated with the analysis.

  The 'EFFORT' value calculated for the Analysis Report is a relative number
related to the number of hours required to complete the migration.  The is a
subjective number and varies depending upon the developers experience in the
migrating platforms, and the tools, techniques and methodologies uses in the
migration.  The One Up Corporation Porting Work Shops may greatly reduce your
porting effort through the techniques taught in these Work Shop sessions.

  It is suggested that you proceed through a complete migration of the sample
code provided in the installation of this product, or other small sample of
your source code to determine the relative difference between the reported
EFFORT from SMART and the hours required in your actual process. The EFFORT
value from the SMART Analysis should be used as a guide only and may not bear
any  correspondence to the actual time required in any porting process.

  The EFFORT value does not include any time required to prepare your code for
migration, nor the correction of any compilation errors introduced by the
migration process, or time required in learning the target or source platform
programming internals.

CONTINUE - The Migration Process
BACK - Getting Ready
CONTENTS


ΓòÉΓòÉΓòÉ 6.3. The Migration Process ΓòÉΓòÉΓòÉ

The Migration Process

  The migration process of SMART processes the specified source files and
generates migrated files with code changes and in-line comments.  The
List-of-Files file contains the fully qualified filenames to migrate (as in the
Analysis Process).

  The migrated files will be placed in the same directory as the source files
(with mapped extensions if desired).

  The Migration Configuration dialog panel provides the user with the
opportunity to select migration formats and options for each category of
difficulty.  It is highly recommended that you test various output migration
formats with a small set of sample code in order to determine the best format
for your intended purpose.

  Prior to executing the Migration Procedure, you will want to perform the
Analysis Procedure on the source code to be migrated.

  Create the "List-of-Files" files containing the files for the  analysis.  Use
the "Maintain List-of-Files" function under the "Files" main menu item in SMART
or the equivalent function in The SMART Editor under the "Link" main menu.  The
files in this list may span multiple directories and even drives.

  If you have created the List-of-Files in the Analysis procedure, you may wish
to modify the list for migrating a sub set of the original List-of-Files or
simply migrate the full code set.

  Execute "Migrate Code" under the "Migration" Menu selection. Take care to
select the proper option on the setup panel for this function.

  You will have a great latitude of options in the configuration of the
Migration process. Refer to the Migration Configuration Dialog Panel for an
explanation of these options. The typical default selections include use of
commented code (as opposed to 'ifdef' blocks).

  If you are using The SMART Editor you will want to create a link database for
hyperlinking to migrated changes, otherwise uncheck this option.  If building
The SMART Editor Database you may wish to set the DB options to link on the
migration keyword list.

  You may wish to use the files in the samples directory of the SMART
installation to try migrations with various options and see the results.

  Rerunning the Migration process with the same List-of-Files and the same file
extension mapping will overwrite the original migration files.  Recursive
migration of the same files may give unpredictable results. Note that the
migration process creates a new List-of-Files file containing the new migrated
file names which you may wish to use for a number of purposes, including The
SMART Editor Link Database build.

  You can now proceed through the migrated files to complete the migration
according to the in-line comments that have been placed in the migrated code.
Use of an editor with hyperlink source code access, like The SMART Editor will
be a valuable asset in quickly pulling up on-line help and accessing all
references to a migrated function, structure, etc.

  After you have made all changes to the migrated code, you can use the
"Remove Comments and Tagged Code" to remove migration comment, examples and
other code that has been inserted in the source files to assist you in the
migration process.

CONTINUE - Completing The Migration
BACK - The Analysis Process
CONTENTS


ΓòÉΓòÉΓòÉ 6.4. Completing the Migration ΓòÉΓòÉΓòÉ

Completing the Migration

  SMART identifies Category 000 keywords (which may require no migration at
all) and automatically makes the changes for Category 010.  This may account
for 50-70% of the changes required in the migration.  The remaining changes are
identified by the comment insertion according to the options that you have
chosen in the Migration Options Panel.

  These remaining changes, due to their categories, must be evaluated and
changed as you deem necessary.  You may wish to write a replacement function
for the API call and change the name to call this new function or you may need
to go to each change indicated and rewrite a portion of the code depending upon
the usage.  Any combination of techniques may be used.  You are the best one to
decide how you should approach this completion effort based upon productivity,
compatibility and other criteria.

  In general, you may have chosen to restate the source code for the Category
020 changes. Since, by definition, these changes may require little effort, the
original restated code is a good starting point.

  In most cases, you will want to make use of The SMART Editor to hyperlink to
each type of change and make the decided change "across the board".  You will
also find The SMART Editor useful to find all occurrences of a structure, or
function call before you make a change to a field or parameter to insure you
fully understand its use.

  You may also find The SMART Editor valuable in making global replacements for
a number of strings in all source files.

  It is highly recommended that you become familiar with The SMART Editor
before you begin your migration.  It will surely save you many hours of
searching though your source code to find and display specific keywords,
functions and other elements of your code.

  Take the time to go through the tutorial in The SMART Editor Technical
Manual.  It will only require about thirty minutes of your time and will
provide you with a general understanding of the functionality of this product.

  With the use of The SMART Editor you will have context sensitive access to
the on-line help for the IBM development help facility.

  The other productive tool in the SMART Toolset is the SMART Viewer.  Using
this on-line viewer you will be able to access the migration help of any
specified keyword.  Using these techniques, you may desire to have less comment
inserted in-line with the migrated code and prefer to use the SMART Viewer for
migration assistance for each encountered keyword.

  The comment tags at the end of each migration inserted line are coded for
identification and removal.  You can use these tags for searching (using The
SMART Editor).  You can adopt techniques of tagging each line as you complete
the migration.  There are several REXX macros provided with SMART to be used
with The SMART Editor to enable  personal tagging of the migration lines as you
proceed with your work.

  When complete, you can easily remove all tagged lines and tags using the menu
item under "Migration" entitled "Remove Tagged Code Lines...".  The dialog
panel associated with this function allows you to specify the particular lines
or tags to be removed.

CONTINUE - The SMART Viewer
BACK - The Migration Process
CONTENTS


ΓòÉΓòÉΓòÉ 6.5. The SMART Viewer ΓòÉΓòÉΓòÉ

The SMART Viewer

  The SMART Viewer provides a context sensitive on-line help to the SMART
Migration knowledge base.  By providing a topic name, you can display
information regarding the migration of the specified keyword.  The display
windows that are available in this utility are "Topic", "Template",
"Prototype",  "Example", and "References". An additional window "History"
provides a list of all topics accessed in the current session.

  The SMART Viewer is invoked from The SMART Editor through the supplied Rexx
Macro "SMVIEWER.REX".  Simply mouse click on a Source Platform keyword and
invoke the Rexx Macro with an assigned hot-key.  If you are using an editor
other than The SMART Editor, you will want to create a macro or other linking
function to spawn SMART Viewer with topic names.

  The SMART Viewer communicates externally through the proxy process
"SMARTVUE.EXE", which eliminates starting a new instance each time a request
for a new topic is desired.

  SMART View contains a search panel which allows you to enter a desired topic
(keyword) name for viewing.

  Selected text from the "Template", "Prototype", and "Example" window displays
can be copied to the clipboard buffer providing "cut" and "paste" programming
capability from the migration data base to your editor.

  Additional functionality for this utility of SMART is explained in the SMART
Viewer on-line help facility.

CONTINUE - The SMART Resource Translator
BACK - Completing The Migration
CONTENTS


ΓòÉΓòÉΓòÉ 6.6. The SMART Resource Translator ΓòÉΓòÉΓòÉ

The SMART Resource Translator

(It is necessary to use this utility only when migrating from Windows to OS/2.
Resources do not require translating when migrating from one version of OS/2 to
another.)

  The SMART Windows to OS/2 Resource Conversion utility (SMARTRC.EXE) provides
source-to-source conversion of Windows resource definition files to OS/2
resource definition files.  Support is provided for converting the following
resource definition statements:

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

SMARTRC also recognizes and processes the following preprocessor directives:

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

Additional functionality includes:

    Automatic reformatting of all Windows resource definition statements to
the equivalent OS/2 format.
    Automatic generation of alternate accelerator key sequences.
    Automatic reformatting of strings contained in RCDATA to produce
equivalent binary representation in the RES file.
    Automatic conversion of mnemonic characters.
    Automatic scaling and recalculation of OS/2 dialog units from Windows
dialog units.
    Automatic remapping of Windows dialog control styles to OS/2 dialog
control styles.
    Automatic remapping of common dialog  control identifiers to equivalent
OS/2 common dialog control identifiers.
    Automatic detection of named-resources and generation of header file to
assign integer identifiers.
    Optional dialog font mapping from Windows font name and point size to OS/2
font name and point size.
    Code page conversion of text strings from Windows code page to OS/2 code
page.

  The general philosophy of converting resource definition statements is that
SMARTRC will attempt to convert everything and anything that it understands.
For those statements which do not have an equivalent statement in OS/2 SMARTRC
will identify the file and line number on which the statement occurs.  In
addition, SMARTRC will identify any conversion which may result in slightly
different functionality in OS/2.  It is up to the developer to decide how to
proceed with any statement in error.

  If SMARTRC detects named-resources, it will generate an include file with a
.HHH extension containing integer definitions for those resources.  The user
either needs to rename this .HHH file and include it in the top .RC file or
copy its contents into an existing .H file that is already included.  It is
also a good practice for the user to start at the top-most .RC file when
migrating so just one .HHH file will be created and all of the generated ID
numbers will be sequential.

  SMARTRC is a utility that can be executed from SMART through the interface
dialog panel associated with "Translate Resources..." under the "Resources"
menu item or can be run from a command line or embedded in a batch command
file.  If the Resource Translator encounters a problem during the conversion
process, it will output information, warning or error messages.  For a detailed
explanation of these messages, select the "Help, Help Contents" menu item in
the SMART application, then go to "Utility Processes, Resource Translator
Topics, Resource Translator Messages".

  Although SMARTRC contains many run time options, simply specifying the
resource filename without options will process with the system default
parameters.

CONTINUE - Graphical Resource Conversion
BACK - The SMART Viewer
CONTENTS


ΓòÉΓòÉΓòÉ 6.7. Win Help Translation ΓòÉΓòÉΓòÉ

Win Help Translation

(It is necessary to use this utility only when migrating from Windows to OS/2.
Help files do not require translating when migrating from one version of OS/2
to another.)

  The SMART Windows to OS/2 Help Translator Conversion utility (SMARTHLP.EXE)
provides conversion of Windows help files to OS/2 help files.  This utility can
be executed from SMART through the interface dialog panel associated with
"Translate Win Help..." under the "Resources" menu item or can be run from a
command line or embedded in a batch command file.

 Follow these steps to convert a Windows RTF (Rich Text Format) file to an OS/2
help file.

 1. Create an HPJ file that contains the name of the RTF file to be converted
    along with any bitmap names that are needed.  A sample HPJ file is located
    in ..SMARTAUX\SAMPLE.HPJ.

 2. To access the the Win Help Translator dialog panel, choose "Resources" from
    the SMART main dialog panel.  From the Resources pulldown choose "Translate
    Win Help".

 3. On the Win Help Translator dialog panel, enter the name (including path) of
    the HPJ file in the "Input Filename" field.

 4. Choose the rest of the options as they apply.  Generally, most of the
    options will be needed.

 5. If the output will be used by an application, choose "Output .HLP file".
    If the output will be independent, like a "users' reference", choose
    "Output .INF file".  To view the output, create an .INF file and use the
    VIEW command (in OS/2).

 6. Another useful option is "Send Error file to Editor".  Then, errors can be
    viewed.

 7. When all options have been chosen, press "ok".

 8. SMART does not display a status on the conversion process for a HELP
    document.  If the "Send Error File to Editor" option is chosen, then the
    process will be complete when the error file is displayed.  Otherwise,
    watch the OS/2 window in the backgound to ensure that the Help conversion
    process is complete.

 9. Output from the Help conversion will depend on the options chosen.  If
    nothing was entered in the "Output Filename" the file will be written to
    the same directory as the input file.

10. Unless the "Convert to IPF Only" option is chosen, the IPF file produced by
    SMART will automatically be sent to the IPF compiler.  In that case, an INF
    or HLP file will be produced (depending on the option chosen).  If the
    "Convert to IPF Only" option IS chosen, only the IPF file will be produced
    and will not be compiled.

 Note:  Error messages are explained in the online help.  To view the error
message explanations, choose HELP from the Win Help Translator dialog panel.
Then choose "Win Help Translator Topics".  After that choose "Win Help
Translator Messages".

Please note that the IPF compiler (IPFC.EXE) is required for SMART Win Help
translation. IPF (Information Processing Facility) is available from the IBM
Developers Toolkit.

WIN HELP TRANSLATION LIMITATIONS

The .RTF format can specify a more general document than the IPF's tag
language.  Because of this, some word-processing functionality available with
Windows help files cannot be translated to the PM IPF system.  The following
are the word processing functionalities that cannot be supported:

   Headers and Footers are not supported and will be ignored.

   Metafiles and Macintosh pictures are not supported and will be ignored.
You may convert these pictures to bitmaps rather than use these unsupported
formats.

   Scaling and cropping of pictures are not supported and are ignored.

   Outline, shadow, small-cap and all-cap character attributes are not
supported and are ignored.

   Revision marking, tables, side-by-side paragraphs, centered paragraphs,
right-justified paragraphs, paragraph borders, and paragraph leaders are not
supported and are ignored.

   Decimal, right, and center tabs are not supported and are ignored.

   Margins, paragraph indentations, and tabs are approximated to the nearest
character width.

   Line spacing before, within, and after paragraphs is approximated to the
nearest system font character height.

   Text does not flow around left or right-margin images, but follows
immediately below the image.

   Monochrome images appear in black and white instead of the text foreground
and background colors.

   Character attributes of bold, underline and italics work correctly in all
combinations, except for all three together.  It produces red text.

   A maximum of 64KB of keys information can be provided.

   There are cosmetic differences in the way that hypertext links are
displayed on the screen and in the mouse and keyboard interfaces to those
links.

CONTINUE - Graphical Resource Conversion
BACK - The SMART Resource Translator
CONTENTS


ΓòÉΓòÉΓòÉ 6.8. Graphical Resource Conversion ΓòÉΓòÉΓòÉ

Graphical Resource Conversion

  (It is necessary to use this utility only when migrating from Windows to
OS/2.  Resource files do not require translating when migrating from one
version of OS/2 to another.)

  The SMART Windows to OS/2 Graphical Resource Conversion utility
(SMARTCVT.EXE) provides binary conversion of Windows icon, cursor, and bitmap
files to OS/2  pointer files and bitmap files, respectively.

  Both 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.

  SMARTCVT is a utility that can be executed from SMART through the interface
dialog panel associated with "Convert Graphical Resources..." under the
"Resources" menu item or can be run from a command line or embedded in a batch
command file.  If the Graphical Resource Converter encounters a problem during
the conversion process, it will output information, warning or error messages.
For a detailed explanation of these messages, select the "Help, Help Contents"
menu item in the SMART application, then go to "Utility Processes, Graphical
Resource Converter Topics, Graphical Resource Converter Messages".

  The summary information output by SMARTCVT at the completion of file
conversion recaps the entire conversion process.  Following is an example of
the output contained in the summary information:

  Files Processed:   10
  Files Converted:   10
  Warnings:    0  Errors:    0

CONTINUE - The SMART Editor Development Tool
BACK - The SMART Win Help Translator
CONTENTS


ΓòÉΓòÉΓòÉ 6.9. The SMART Editor Development Tool ΓòÉΓòÉΓòÉ

The SMART Editor Development Tool

  The SMART Editor is a feature rich programming development tool combining
hyperlink source code access, a fully functional editor, and many file
manipulation utility functions.

  Features:

   Build hyperlinks to key elements of your source code.
   REXX Macro interface.
   Full IBM Workframe interface.
   Spawn Compiles directly from The SMART Editor and hyperlink to errors.
   Context sensitivity to all IBM development help files (if installed).
   Edit with multiple windows, any size files.
   Create functional call tree and other documentation display - all hyperlink
sensitive.
   Unsurpassed methods for navigating directories, drives and source code.
   Hyperlink capabilities make learning new code a breeze.
   Print SMART analysis and source code with format from within The SMART
Editor.
   Interface with SMART provides automatic hyperlink to all points of change.

  Please refer to The SMART Editor Technical Manual for full explanation
regarding the powerful functionality available with this tool.

CONTINUE - Chapter 4 - Techniques
BACK - Graphical Resource Conversion
CONTENTS


ΓòÉΓòÉΓòÉ 7. Chapter 4 - Techniques ΓòÉΓòÉΓòÉ

Chapter 4 - Techniques

  Preparing Your Source Code
  Reading the Analysis Display/Report
  Interpreting the Analysis
  Use of Common Functions
  Source Migration Format Considerations
  File Extension Mapping
  Source Migration Comment Code Removal
  Increased Productivity with The SMART Editor

CONTINUE - Preparing Your Source Code
BACK - The SMART Editor Development Tool
CONTENTS


ΓòÉΓòÉΓòÉ 7.1. Preparing Your Source Code ΓòÉΓòÉΓòÉ

Preparing Your Source Code

  Planning a strategy for the analysis and/or migration of your source code
will greatly pay back in the long run.

  It is essential that your original source code be backed up to insure that an
inadvertently mis-chosen option, especially in the migration process, does not
prevent you from restoring to your original code state.

  Both the Analysis and Migration processes of SMART should not be considered
one-shot processes.  You may wish to run the Analysis a number of times, with
global code changes to change the outcome.  Likewise, you may find that you
want to make global changes to your code fixing a recurring hit to reduce the
migration effort before you even apply SMART.

  For example, after a review of the initial analysis run, changing a parameter
type through your code may significantly reduce the Effort reported in the
analysis.  After looking at the reported keyword hits in your code, you may
decide to write a number of common functions that replace the source platform
API calls and make global replacements for these calls to your new functions.
You can rerun the Analysis Process and see the resulting effort changes.
Likewise for other changes that may involve macro #defines, or typedefs.

  You may be surprised at the results of these preprocessing changes and how
they might reduce your porting effort.

  Likewise, you may wish to rerun the Migration Process after analyzing the
resulting initial results.  It may be that you need different formatting
options in the Migration Process, or you find that you can make global changes
to a syntax widely used to eliminate repetitive reporting from SMART of this
migration hit.

  Essentially, anything that you can do to your code to simplify that migration
process will greatly reduce the whole porting effort.

CONTINUE - Reading the Summary Reports
BACK - Chapter 4 - Techniques
CONTENTS


ΓòÉΓòÉΓòÉ 7.2. Reading the Summary Reports ΓòÉΓòÉΓòÉ

Reading the Summary Reports

For each analysis that you run, a summary report files is created and can be
printed using the SMART 'Print Analysis Report' process.

A cover page preceeds the summary reports when they are printed with
information regarding the date and time of the report along with the user
supplied report title.

A summary report is created with the standard Migration Analysis process, and
the Resource Translation Analysis (if the Windows migration tables are
selected).

 The report lines for the cover page and their description follows:

 SMART Source Code Migration Analysis Report - Cover Report Heading.

 [Next one to three lines] - User supplied report title (first line appears on
each page of the report).

 Prepared: [Date - Time] - Date stamp of the summary report.

 Printed: [Date - Time] - Date stamp of the report printing.

 Summary: [Filename] - Filename(s) of the Summary report files.

 Report: [Filename] - Filename(s) of the Primary Analysis report file.

 The report lines for the Migration Analysis Report Summary and their
description follows:

 Total File Count - Number of files processed in the Analysis.

 Total File Size (Bytes) - Total size of files processed in the Analysis.

 Total Source Lines - Total number of lines processed.

 Total Code Lines - Total number of lines processed excluding comment lines and
null (skip) lines.

 Total Category xxx Hits - Total number of keyword encounters by category type.

 Total Migration Hits - Total number of all keyword encounters.

 Total Cat 000 and 010 Hits Auto Migrated - Total number of keyword encounters
that will be automatically migrated using SMART.

 Total Hits MiCL Processed - Total number of keyword encounters that will be
migrated using MiCL commands in either the primary Migration Database or a
UDMD.

 Total Hits Processed with UDMD - Total number of keyword encounters were
encountered from a UDMD.

 Total Hits Excluded - Total number of keyword encounters were excluded from
processing based on a user supplied exclude list.

 Total Migration Keyword Instances - Total number of keyword encounters that
represented different keywords.

 **NOTE** - The following effort estimates and productivity gains are
calculated from a number of generalized factors and assumptions.  The actual
effort that you may encounter will depend upon your individual experience and
productivity, in addition to unique difficulties that may be encountered in
your coding.  Please use these values as a comparative guideline only.

 Estimated Migration Effort Without SMART - An estimation of the total number
of migration hours required to migrate this project without any use of SMART.

 Savings from SMART Base Migration - An estimation of the total number of
migration hours saved by the base use of SMART without any productivity gains
from automatic migration.

 Savings from Cat 010 Auto Migrate - An estimation of the total number of
migration hours saved by the automatic migration from SMART.

 Savings from Keyword Exclusions - An estimation of the total number of
migration hours not required due to exclusion from the user specified keyword
exclude list.

 ** Net Migration Effort ** - An estimation of the total number of migration
hours remaining to complete the project after processing with SMART.

 Percent Effort Reduction using SMART - A calculation of the net estimated
migration effort as a percentage of the total estimated effort without the use
of SMART.

 The report lines for the Resource Translation Analysis Report Summary
(provided with Windows migration Analysis only) and their description follows:

 Total Resource File Count - Number of files processed in the Resource
Analysis.

 Total Resource File Size (Bytes) - Size of files processed in the Resource
Analysis.

 Total Dialog Templates - Number of Dialogs encountered in the Analysis.

 Total Dialog Code Lines - Number of lines of code for the Dialogs.

 Ave Code Lines Per Dialog - Indicates the code lines size of the average
dialog.

 Total Menu Template Code Lines - Number of coding lines in the Menus.

 Total StringTable Code Lines - Number of coding lines in the String Tables.

 Total Accelerator Table Code Lines - Number of coding lines in the Accelerator
Tables.

 **NOTE** - The following effort estimates and productivity gains are
calculated from a number of generalized factors and assumptions.  The actual
effort that you may encounter will depend upon your individual experience and
productivity, in addition to unique difficulties that may be encountered in
your coding.  Please use these values as a comparative guideline only.

 Estimated Translation Effort Without SMART - Estimated migration hours to
convert the resource files without the use of SMART.

 Savings from SMART Resource Translator - Estimated migration hours saved in
the effort to convert the resource files with the use of SMART automation.

 ** Net Translation Effort ** - An estimation of the total number of migration
hours required to translate the resource files with SMART.

 Percent Effort Reduction using SMART - A calculation of the net estimated
translation effort as a percentage of the total estimated effort without the
use of SMART.

CONTINUE - Reading the Analysis Display/Report
BACK - Preparing Your Source Code
CONTENTS


ΓòÉΓòÉΓòÉ 7.3. Reading the Analysis Display/Report ΓòÉΓòÉΓòÉ

Reading the Analysis Display/Report

  Each keyword is categorized by the level of difficulty required to migrate to
the target platform.  These categories can also be viewed as the amount of
programmer interaction and expertise required for the migration. The currently
defined categories and their description are as follows:

  000  Informational only - An exact match of the keyword exists in the target
platform but there is change in the size of type. (e.g. short to a long).

  010  Literal replacement - An equivalent definition exists in the target
platform but a literal change in the keyword is required (e.g., LPSTR to PSZ).

  020  Replacement with parameter changes - Equivalent functionality exists in
the target platform but parameters or fields of a structure differ slightly
from the source platform definition (e.g., SetWindowPos to WinSetWindowPos).
Also  included are parameters that are not applicable or required on the target
platform (e.g., MakeProcInstance).

  030  Change with more / less API calls - Equivalent functionality exists in
the target platform but it must be implemented with  more, or sometimes less,
function calls (e.g., DlgDirList).  Also included are items which map to one of
several choices depending upon the type of parameter used (e.g., GetObject).

  040  Logic changes required - Similar functionality exists in the target
platform but the logic required to emulate the functionality must be reworked
(e.g., CreatePatternBrush).

  050  Functionality does not exist - There is no means provided to perform the
same functionality in the target platform (e.g., GetKeynameText).  Workaround
coding must be implemented, where possible.

  999  Dictionary entry not defined - The database does not currently have a
complete description for the migration of the keyword.

  Throughout the analysis report there are several column and section  headings
used to display counts of various pieces of information.

  These column and section headings are defined as follows:

File Detail Report:

 PATH/FILENAME - Full path specification of the file(s)
 SIZE - File size in bytes
 LINES - Number of lines in the file
 CODE - Number of lines containing code in the file
 HITS - Number of times a keyword was identified
 PCT HITS - Percentage of hits per line of code (i.e., HITS / CODE)
 INSTS - Number of unique keywords that were identified
 PCT INST - Percentage of unique keywords per line of code (i.e., INSTS / CODE)
 EFFORT - Calculation of the relative amount of work required to migrate the
code in the file
 CAT xxx - Number of hits in each category

Keyword Detail Report:

 CATEGORIES - Breakdown by category of the keywords found
 TYPES - Breakdown by type of the keywords found (function calls, messages,
symbol definitions, and typedef statements)
 AREAS - Breakdown by functional area of the keywords found
 KEYWORDS - Breakdown by individual keyword.  Ordered by category and from the
most number of occurrences to the least number of occurrences.
 HITS - Number of times a keyword for the specified item was identified.
 PCT HITS - Percentage of all hits identified (i.e., HITS / section total HITS)
 FILES - Number of files that a keyword for the specified item was found
 INSTS - Number of unique keywords that were identified for the specified item
 PCT INST - Percentage of all unique keywords identified (i.e., INSTS / section
total INSTS)
 EFFORT - Calculation of the relative amount of work required to migrate the
code for the specified item

CONTINUE - Interpreting the Analysis
BACK - Reading the Summary Reports
CONTENTS


ΓòÉΓòÉΓòÉ 7.4. Interpreting the Analysis ΓòÉΓòÉΓòÉ

Interpreting the Analysis

  The analysis portion of SMART actually generates two related reports.  Each
report presents the detailed analysis from a different perspective.  The two
reports together should give you a thorough understanding of the amount of code
that requires migration and the amount of effort that will be involved.  A
brief overview of the contents of the analysis report is relevant here before
discussing how to interpret the data contained in the  report.

  The file detail report presents a detailed analysis of each source file. This
includes all of the items previously defined for the file detail report.

  The keyword detail report presents a more thorough breakdown of the keywords
identified during the analysis.  The analysis data is broken down four
different ways.  The first is a breakdown by category showing the counts of the
keywords as identified by their respective category. The second is a breakdown
by the types of the keywords.  The third is a breakdown of the identified
keywords by the various functional areas that a keyword is classified.  The
fourth is a breakdown by the individual keywords.  This last breakdown shows
each and every keyword that was identified and the number of occurrences.

  The analysis report contains a lot of valuable information about your source
code.  Once you understand how to interpret the data you will be able to more
accurately size and evaluate the migration effort.  In addition you can rerun
the analysis program on your code during the migration process to give you
accurate progress statistics.  We begin the interpretation with the file detail
portion of the analysis report.

  The first thing to be learned from the file detail report is simply how many
lines of code are in each file and in the entire the application. This forms
the basis for determining the relative distribution of the keywords in the
code.

  The total number of hits, shown at the bottom of this part of the report,
tells you how many changes must be made to the code.  The percentage of hits
times the number of lines of code tells you how many lines of code must be
changed.  Don't get overly excited at this  point if this number is rather
large.  Until we examine the keyword detail report you don't know how many of
these will be automatically migrated by  SMART.

  Next look at the total number of instances.  This is the number of unique
keywords that must be migrated.  What this really tells you is  approximately
how many individual keywords the programmer(s) will have to be familiar with in
order to make various decisions during the migration. Since many migration
issues and changes related to a specific keyword are the same or similar for
all occurrences of that keyword the actual effort is reduced to deciding what
needs to be changed and simply repeating the change for each occurrence.
Again, many of these changes may be  automatically migrated by SMART.

  At this point the effort number that is shown for each file has very little
significance unless you have migrated source before.  The effort calculation is
based on the relative difficulty of  migrating a keyword -- category 030 items
are more difficult to migrate than category 020 items.  Since the actual time
to migrate a section of code also depends on the experience and knowledge of
the programmer and on the tools being used the amount of actual time that the
effort number translates to will be different for each person.

  In order to translate the effort number to actual time it is necessary to
migrate several source files containing a mix of keywords in each of the
difficulty categories.  Using the actual time and the effort calculations for
those migrated files you get an approximate time value for each effort unit.

  The last portion of the file detail report is the breakdown of the hits by
their respective categories.  These numbers can assist you in assigning groups
of files to programmers with different levels of expertise.  A file that is
mostly composed of category 020 items can be assigned to someone with little
experience on the target platform since most of the keywords are relatively
simply to migrate.

  In fact, the changes required for almost all of the category 020 items is
exactly a one-to-one change as detailed in the migration database.  Files that
contain category 040 and 050 items can be assigned to your more experienced
programmers since these items require a more in-depth knowledge of what the
code is attempting to do on the source platform and how the logic can be
restructured to implement the same functionality on the target platform.

  In general, the file detail section provides a quantitative analysis of the
source code showing how much must be changed.  On the other hand, the keyword
detail section provides more of a qualitative analysis of those changes.  In
the keyword detail report we get to the real nitty-gritty of what is contained
in the source code.

  The first section, CATEGORIES, presents the first indication of how the
migration breaks down by difficulty.  Collectively the six columns of data can
tell you a lot about how much effort will be involved and  where that effort
will be concentrated.

  The HITS, PCT HITS, and FILES columns tell you the volume of physical changes
that have to be made. Even minor changes can require a great deal of time if
the item occurs thousands of times or exists in hundreds of files.  Time is
required to open files, locate and enter changes, and save the files.

  Review the INSTS and PCT INSTS columns to identify the number of unique items
that have to be migrated at each difficulty category.  There are two things
that may be learned from this information.  First, while there may be a large
number of HITS in a particular category it may be that they are isolated to a
few particular keywords.  This would actually indicate that less work is
required compared to the situation where a large number of instances occur with
a large number of hits.

  When we look at the KEYWORDS section it will be more evident if that is the
case, but this section can give use a good indication of where the effort is
concentrated.  Second, look at the distribution of the hits and instances among
the various categories.  Most likely the majority of the hits as well as the
instances are in categories 020 or less. The desired trend is for the numbers
to decrease significantly from  category 020 to category 050.  Obviously the
fewer category 040 and 050 items the less difficult the migration.  The last
column, EFFORT, is a good indicator of where you will spend most of the time
during the migration. Depending on the number of instances of category 030 and
040 items it is possible that the effort for these categories can be greatly
reduced.

  The next section, TYPES, is mostly for information purposes only. A couple of
useful things about your migration effort can still be learned from it.
Function and message items typically require the most effort since  program
logic can be affected.  Symbol items require the least effort since most of the
time it requires a simple change to a bit flag or a #define statement.  The
typedef items typically require modifications  to structure field references
and aren't significantly difficult items.

  The next section, AREAS, is again mostly for information purposes only.  This
section can help in staffing the migration and assigning programmers to work on
individual areas of the project.  By analyzing the various functional areas
that require migration and the numbers associated with each you can decide what
expertise on both the source and target platform is required.  For example, if
large portions of the migration are in the bitmap, color-palette, and
drawing-tool areas you will want to make sure you assign a programmer with
graphics expertise to the project.

  The last section, KEYWORDS, shows exactly what keywords were identified in
the source and their frequency of occurrence.  Since the keywords are organized
by category and listed in decreasing order of occurrence it is very easy to see
what needs to be changed.  It is also here that you can see if you have an even
distribution of hits on each keyword or if there are a lot of hits on
relatively few keywords.

  For example, if you have 800 hits in category 030 but 450 of them are
SendMessage and 250 are SelectObject then the amount of effort can be reduced.
This is because the programmer will have only to look at these two items,
decide the general migration changes to be applied, and make the changes (thus
eliminating 700 of the 800 hits).

  On the other hand, if the hits are fairly evenly distributed in a category it
will require more time since many more decisions on migration changes will have
to be performed. This is especially important when looking at the category 040
and 050 items since these items may require significant logic changes to the
application.

  One additional thing to note is the relationship of the  various keywords in
a category. If you see several keywords which relate  to the same functionality
it may be possible that all of those keywords  will be migrated by a change to
a single portion of the code.  For  example, if you encounter a set of mouse
related messages in category 040 then all of these will most likely be resolved
in the same manner or with a single change to the code.

  There are a few items that warrant special consideration when evaluating the
SMART analysis report.  The current knowledge-base technology may
over-categorize a keyword resulting in a higher relative effort than is
actually required.  There are many functions and messages which  have a
one-to-many mapping to the target platform.  In these cases the actual
migration depends upon the intention of the function or the value of one or
more parameters (e.g., a flag set in a variable).

  When more than one choice exists for the migration SMART will use the higher
category level for the analysis report so as not to significantly underestimate
the effort.  For example, the Windows RegisterClass function is categorized as
category 040.  If the class uses the default cursor and icon then it actually
is a category 020 item.  Yet, if a class specific cursor, icon, or background
brush is used it is a category 040 since this would require logic changes.
Category 040 would be used by SMART since it would depend on the values in the
WNDCLASS structure.  Be aware that you may have some keywords that are
overclassified.

  One of the suggested techniques to significantly increase the speed of the
migration is to use macros or to implement functions for category 030 and 040
items that have high hit counts.  This eliminates larger, redundant blocks of
migrated code that implement the intended functionality and also localizes the
debugging effort to a single function. If this technique is applied to your
migration effort then you should take into consideration that the keywords
implemented in this manner are actually category 020 items instead of category
030 or 040.

CONTINUE - Use of Common Functions
BACK - Reading the Analysis Display/Report
CONTENTS


ΓòÉΓòÉΓòÉ 7.5. Use of Common Functions ΓòÉΓòÉΓòÉ

Use of Common Functions

  Significant improvements in your migration effort may be achieved through the
use of common functions.  Common functions refers to the implementation of
source platform functions as their equivalent target platform functions.  Since
the migration of many keywords involves replacing the existing function call
with multiple lines of code, using common functions can reduce the amount of
code and coding changes required.

  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 general rule a
keyword is a candidate if the hit count is at least twenty (20)  and the
difficulty category is 030 or higher.  Once a candidate is identified you must
review the use of that keyword throughout the application.  If the keyword is
used in generally the same context throughout the application then you will
probably gain migration speed by implementing the particular function or
defining an appropriate macro.

  As an example, assume that the analysis report for a Windows application
shows that GetMenuString occurs 100 times.  This is a category 030 keyword
since the flag may specify the menu item either by command or by position.  If
we examine the code and find that all of the calls are requested by command
then we could decide to just implement GetMenuString as a macro which sends the
MM_QUERYITEMTEXT messages.  On the other hand if we have a mix of requests by
both command and position we could decide to implement GetMenuString as a
function which sent the appropriate messages based on the specified flag.

  It is recommended that you place all common functions into a single,
separate source file or library.  Doing so can ease your effort during the
debugging phase and allows you to begin abstracting functionality for future
migrations.

CONTINUE - Source Migration Format Considerations
BACK - Interpreting the Analysis
CONTENTS


ΓòÉΓòÉΓòÉ 7.6. Source Migration Format Considerations ΓòÉΓòÉΓòÉ

Source Migration Format Considerations

  Each Category of the Migration Process offers a popup dialog panel to select
the format of the inserted comments in the migrated code.  These options
include: Long, short or no comment, template, prototype, example code, restate
original code and ignore migration.

  It may appear convenient to insert all of the above items in-line with your
source code. However, in general, the more you put in your code the more
difficult it is to read.  It is better to insert less in your code and use the
SMART Viewer to display information pertaining to the keywords as necessary.
You also have the option to clip and paste from the SMART Viewer display panels
to your code.

  After you have reviewed the Analysis report and made any necessary code
changes, you may wish to ignore the Category 000 hits.

  Restatement of the original code has been offered as an option particularly
for the Windows to OS/2 migration.  This uncommented restatement allows you to
rerun the Analysis Process during your process of completing the migration to
determine the amount of code left to complete.  Simply remove this code
restatement as you make the necessary changes.

  You may also use this restatement as a starting point for code modification.

  In any case it is recommended that you try various options on the sample code
or a small set of you source code to determine what works best for you.

CONTINUE - File Extension Mapping
BACK - Use of Common Functions
CONTENTS


ΓòÉΓòÉΓòÉ 7.7. File Extension Mappings ΓòÉΓòÉΓòÉ

File Extension Mapping

  File extension mapping allows you to control the name of the generated source
file in the Migration process for source migration, the process for commenting
out #ifdef code and the process for removing tagged code.

  In all cases where SMART generates new source files the files are placed in
the same directory as the original, with the file extension changed.  The
alternative to this process is to request that the original file be
overwritten.  For obvious reasons this is not recommended.

  You can control the extension mapping by specifying the map for each file
extension encountered in your processing.  The data for this mapping is
contained in the test file MAPEXT.DAT in the main SMART directory.

  You can maintain this data from the popup dialog selected in the processes
that offer extension mapping such as the Migration Process.

  The mapping data simply contains the original extension and then the
extension for the map.

  The mapping data will not accept wildcards, but is explicitly defined.  You
will note that several layers of mapping is defined in the default data.  For
example ".C" is mapped to ".C__X", and ".C__X" is mapped to ".C__Y".  This
allows you to perform multiple mapping processes while saving each set of files
in the processes.

  Please note that the mapping data is case sensitive.  If your files are in
lower case, the mapping data must be specified in lower case.

  You will be notified if SMART encounters a file that cannot be mapped, due to
missing mapping data, during the process requiring the map.

  The SMART Resource Translator accepts wildcards and does not use this mapping
data.

CONTINUE - Source Migration Comment Code Removal
BACK - Source Migration Format Considerations
CONTENTS


ΓòÉΓòÉΓòÉ 7.8. Source Migration Comment Code Removal ΓòÉΓòÉΓòÉ

Source Migration Comment Code Removal

  You can automatically remove comment tagged code with SMART.  Comment tagged
code is defined by having a short unique set of identification characters.

  All of the migration insertion code has tags identified by "SM$:".  The
dialog selection panel shown above specifies that codes that are used by SMART.
Using this panel you can select the commented code that you wish to remove at
any point in your migration process.

  The four fields entitled "Other Tagged Lines" allows you to remove code that
may have been tagged by you for your own identification purposes.

  This process also allows you to just remove the tags without removing the
code on the lines.  In this case the tags are removed at the end of the line,
leaving the remaining code. To fit into this class of tagging, the tags must be
at the end of the line and proceeded by a double slash ("//") and a space.

  You may wish to explore the functionality of this process with a file form
the sample code that has been migrated.

CONTINUE - Increased Productivity with The SMART Editor
BACK - File Extension Mapping
CONTENTS


ΓòÉΓòÉΓòÉ 7.9. Increased Productivity with The SMART Editor ΓòÉΓòÉΓòÉ

Increased Productivity with The SMART Editor

  The SMART Editor is provided, and has been specifically designed, to increase
your productivity through the speed and ease of source code navigation and the
integration of file manipulation\utilities.

  The single most unique feature of The SMART Editor is hyperlink access to
your source code. Once you have built a hyperlink data base for your code set,
you can mouse click to any function definition or popup a list of all
references to a function, symbol or other key element of your code.

  You can request that this database be created as a result of the SMART
Analysis or Migration Process, or you can create the link data base within The
SMART Editor application.

  In your migration process, if you wish to look at all the places where a
function is used, simply double click with the right mouse button on the
function in question, and The SMART Editor will create a display of all
references.

  Since The SMART Editor displays are both hyperlink sensitive and editable,
you may double click (left mouse button) on the filename-line number for any of
the displayed references and The SMART Editor will immediately open the file at
the point of reference.

  Another powerful feature of The SMART Editor is the ability to perform
multiple file, string searches and provide a hyperlink display file of all
strings found for your immediate access. You can use your "List-of-Files" from
the SMART Analysis or Migration as the input file specification to this search
process.

  In addition to the powerful source code access function The SMART Editor
allows you to spawn compiles and hyperlink to the point of error.

  The SMART Editor has been specifically designed to assist you in productively
maintaining your code.  The integration of the features and the powerful
navigation functionality will greatly reduce your time and effort in porting
your code.

CONTINUE - Chapter 5 - Reference
BACK - Source Migration Comment Code Removal
CONTENTS


ΓòÉΓòÉΓòÉ 8. Chapter 5 - Reference ΓòÉΓòÉΓòÉ

Chapter 5 - Reference

  Migration Formats
  SMART Files
  Specifications and Restrictions
  Technical Support

CONTINUE - Migration Formats
BACK - Increased Productivity with The SMART Editor
CONTENTS


ΓòÉΓòÉΓòÉ 8.1. Migration Formats ΓòÉΓòÉΓòÉ

Migrated code formats are user configurable.  A number of options relating to
the migrated code are available.

The Format References include the following formats:

   Original source code (before migration)
   Format - 'ifdef' and '/*...*/' comments
   Format - 'ifdef' and '//' comments
   Format - NO 'ifdef' and '/*...*/' comments
   Format - NO 'ifdef' and '//' comments
   Format - '//' comments and NO Tags
   Format - '//', Short comments and Prototypes
   Format - '/*...*/', Long comments, Prototypes and Examples
   Format - Source code with migration comments removed

CONTINUE - Original source code (before migration)
BACK - Chapter 5 - Reference
CONTENTS


ΓòÉΓòÉΓòÉ 8.1.1. Original source code (before migration) ΓòÉΓòÉΓòÉ

Original Source Code

  /* Open the file with the OF_PARSE flag to obtain the fully qualified
   * pathname in the OFSTRUCT structure.
   */
  wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);

  _lclose (wFileTemp);

  LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));

CONTINUE - Format - 'ifdef' and '/*...*/' comments
BACK - Migration Formats
CONTENTS


ΓòÉΓòÉΓòÉ 8.1.2. Format - 'ifdef' and '/*...*/' comments ΓòÉΓòÉΓòÉ

Format - 'ifdef' and '/*...*/' comments

/* SM$:FO  C:\TEST\TEST.C - 03/28/94 14:25:07                */
  /* Open the file with the OF_PARSE flag to obtain the fully qualified
   * pathname in the OFSTRUCT structure.
   */
#ifndef OS221
  wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);/* SM$:O */
#else
  wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  /* SM$:M3 */
  DosOpen (,,,,,,,)                          /* SM$:M3 */
  DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              /* SM$:M2 */
  /*                                   SM$:C
   * OpenFile Cat:030 Type:010 Area:130                  SM$:K
   * Replace with DosOpen, DosDelete, or DosQueryPathInfo         SM$:S
   *                                   SM$:C
   * LPSTR replaced with PSZ - Cat:010 Type:030 Area:990         SM$:1
   *                                   SM$:C
   * OF_PARSE Cat:020 Type:030 Area:130                  SM$:K
   * Use DosQueryPathInfo to replace OpenFile function call        SM$:S
   */                                 /* SM$:C */
#endif

#ifndef OS221
  _lclose (wFileTemp);                         /* SM$:O */
#else
  DosClose (wFileTemp);                        /* SM$:M1 */
  /*                                   SM$:C
   * _lclose replaced with DosClose - Cat:010 Type:010 Area:130      SM$:1
   */                                 /* SM$:C */
#endif

#ifndef OS221
  LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           /* SM$:O */
#else
  LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           /* SM$:R */
  WinLoadString (,,,,);                         /* SM$:M2 */
  /*                                    SM$:C
  * LoadString Cat:020 Type:010 Area:060                 SM$:K
  * Replace with WinLoadString                      SM$:S
  */                                  /* SM$:C */
#endif

CONTINUE - Format - 'ifdef' and '//' comments
BACK - Original source code (before migration)
Migration Formats
CONTENTS


ΓòÉΓòÉΓòÉ 8.1.3. Format - 'ifdef' and '//' comments ΓòÉΓòÉΓòÉ

Format - 'ifdef' and '//' comments

// SM$:FO  C:\TEST\TEST.C - 03/28/94 14:30:22
  /* Open the file with the OF_PARSE flag to obtain the fully qualified
   * pathname in the OFSTRUCT structure.
   */
#ifndef OS221
  wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);// SM$:O
#else
  wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  // SM$:M3
  DosOpen (,,,,,,,)                          // SM$:M3
  DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              // SM$:M2
  // OpenFile Cat:030 Type:010 Area:130                  SM$:K
  // Replace with DosOpen, DosDelete, or DosQueryPathInfo         SM$:S
  //                                   SM$:C
  // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990         SM$:1
  //                                   SM$:C
  // OF_PARSE Cat:020 Type:030 Area:130                  SM$:K
  // Use DosQueryPathInfo to replace OpenFile function call        SM$:S
#endif

#ifndef OS221
  _lclose (wFileTemp);                         // SM$:O
#else
  DosClose (wFileTemp);                        // SM$:M1
  // _lclose replaced with DosClose - Cat:010 Type:010 Area:130      SM$:1
#endif

#ifndef OS221
  LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           // SM$:O
#else
  LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           // SM$:R
  WinLoadString (,,,,);                         // SM$:M2
  // LoadString Cat:020 Type:010 Area:060                 SM$:K
  // Replace with WinLoadString                      SM$:S
#endif

CONTINUE - Format - NO 'ifdef' and '/*...*/' comments
BACK - Format - 'ifdef' and '/*...*/' comments
Migration Formats
CONTENTS


ΓòÉΓòÉΓòÉ 8.1.4. Format - NO 'ifdef' and '/*...*/' comments ΓòÉΓòÉΓòÉ

Format - NO 'ifdef' and '/*...*/' comments

/* SM$:FO  C:\TEST\TEST.C - 03/28/94 14:32:18                */
  /* Open the file with the OF_PARSE flag to obtain the fully qualified
   * pathname in the OFSTRUCT structure.
   */
  /* wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE); SM$:O */
  wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  /* SM$:M3 */
  DosOpen (,,,,,,,)                          /* SM$:M3 */
  DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              /* SM$:M2 */
  /*                                   SM$:C
   * OpenFile Cat:030 Type:010 Area:130                  SM$:K
   * Replace with DosOpen, DosDelete, or DosQueryPathInfo         SM$:S
   *                                   SM$:C
   * LPSTR replaced with PSZ - Cat:010 Type:030 Area:990         SM$:1
   *                                   SM$:C
   * OF_PARSE Cat:020 Type:030 Area:130                  SM$:K
   * Use DosQueryPathInfo to replace OpenFile function call        SM$:S
   */                                 /* SM$:C */

  /* _lclose (wFileTemp);                         SM$:O */
  DosClose (wFileTemp);                        /* SM$:M1 */
  /*                                   SM$:C
   * _lclose replaced with DosClose - Cat:010 Type:010 Area:130      SM$:1
   */                                 /* SM$:C */

  /* LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           SM$:O */
  LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           /* SM$:R */
  WinLoadString (,,,,);                         /* SM$:M2 */
  /*                                    SM$:C
  * LoadString Cat:020 Type:010 Area:060                 SM$:K
  * Replace with WinLoadString                      SM$:S
  */                                  /* SM$:C */

CONTINUE - Format - NO 'ifdef' and '//' comments
BACK - Format - 'ifdef' and '//' comments
Migration Formats
CONTENTS


ΓòÉΓòÉΓòÉ 8.1.5. Format - NO 'ifdef' and '//' comments ΓòÉΓòÉΓòÉ

Format - NO 'ifdef' and '//' comments

// SM$:FO  C:\TEST\TEST.C - 03/28/94 14:33:45
  /* Open the file with the OF_PARSE flag to obtain the fully qualified
   * pathname in the OFSTRUCT structure.
   */
  // wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);SM$:O
  wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  // SM$:M3
  DosOpen (,,,,,,,)                          // SM$:M3
  DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              // SM$:M2
  // OpenFile Cat:030 Type:010 Area:130                  SM$:K
  // Replace with DosOpen, DosDelete, or DosQueryPathInfo         SM$:S
  //                                   SM$:C
  // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990         SM$:1
  //                                   SM$:C
  // OF_PARSE Cat:020 Type:030 Area:130                  SM$:K
  // Use DosQueryPathInfo to replace OpenFile function call        SM$:S

  // _lclose (wFileTemp);                         SM$:O
  DosClose (wFileTemp);                        // SM$:M1
  // _lclose replaced with DosClose - Cat:010 Type:010 Area:130      SM$:1

  // LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           SM$:O
  LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           // SM$:R
  WinLoadString (,,,,);                         // SM$:M2
  // LoadString Cat:020 Type:010 Area:060                 SM$:K
  // Replace with WinLoadString                      SM$:S

CONTINUE - Format - '//' comments and NO Tags
BACK - Format - NO 'ifdef' and '/*...*/' comments
Migration Formats
CONTENTS


ΓòÉΓòÉΓòÉ 8.1.6. Format - '//' comments and NO Tags ΓòÉΓòÉΓòÉ

Format - '//' comments and NO Tags

Note:   Option chosen to insert Short comment and Prototype only. Elimination
of tags on commented lines prevents automatic removal of inserted code!

// SM$:FO  C:\TEST\TEST.C - 03/28/94 14:34:59
  /* Open the file with the OF_PARSE flag to obtain the fully qualified
   * pathname in the OFSTRUCT structure.
   */
  // wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);
  wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);
  DosOpen (,,,,,,,)
  DosQueryPathInfo (, FIL_QUERYFULLNAME,,);
  // OpenFile Cat:030 Type:010 Area:130
  // Replace with DosOpen, DosDelete, or DosQueryPathInfo
  //
  // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990
  //
  // OF_PARSE Cat:020 Type:030 Area:130
  // Use DosQueryPathInfo to replace OpenFile function call

  // _lclose (wFileTemp);
  DosClose (wFileTemp);
  // _lclose replaced with DosClose - Cat:010 Type:010 Area:130

  // LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));
  LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));
  WinLoadString (,,,,);
  // LoadString Cat:020 Type:010 Area:060
  // Replace with WinLoadString

CONTINUE - Format - '//', Short comments and Prototypes
BACK - Format - NO 'ifdef' and '//' comments
Migration Formats
CONTENTS


ΓòÉΓòÉΓòÉ 8.1.7. Format - '//', Short comments and Prototypes ΓòÉΓòÉΓòÉ

Format - '//', Short comments and Prototypes

// SM$:FO  C:\TEST\TEST.C - 03/28/94 14:37:08
  /* Open the file with the OF_PARSE flag to obtain the fully qualified
   * pathname in the OFSTRUCT structure.
   */
  // wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);SM$:O
  wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  // SM$:M3
  DosOpen (,,,,,,,)                          // SM$:M3
  DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              // SM$:M2
  // OpenFile Cat:030 Type:010 Area:130                  SM$:K
  // Replace with DosOpen, DosDelete, or DosQueryPathInfo         SM$:S
  //                                   SM$:C
  // APIRET APIENTRY DosOpen(PSZ pszFileName, PHFILE pHf,         SM$:P
  //  PULONG pulAction, ULONG  cbFile, ULONG  ulAttribute,        SM$:P
  //  ULONG  fsOpenFlags, ULONG  fsOpenMode, PEAOP2 peaop2);       SM$:P
  // APIRET APIENTRY DosQueryPathInfo(PSZ pszPathName,          SM$:P
  //  ULONG ulInfoLevel, PVOID pInfoBuf, ULONG cbInfoBuf);        SM$:P
  // APIRET APIENTRY DosSearchPath(ULONG flag, PSZ pszPathOrName,     SM$:P
  //  PSZ pszFilename, PBYTE pBuf, ULONG cbBuf);             SM$:P
  // APIRET APIENTRY DosDelete(PSZ pszFile);               SM$:P
  //                                   SM$:C
  // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990         SM$:1
  //                                   SM$:C
  // OF_PARSE Cat:020 Type:030 Area:130                  SM$:K
  // Use DosQueryPathInfo to replace OpenFile function call        SM$:S
  //                                   SM$:C
  // APIRET APIENTRY DosQueryPathInfo(PSZ pszPathName,          SM$:P
  //  ULONG ulInfoLevel, PVOID pInfoBuf, ULONG cbInfoBuf);        SM$:P

  // _lclose (wFileTemp);                         SM$:O
  DosClose (wFileTemp);                        // SM$:M1
  // _lclose replaced with DosClose - Cat:010 Type:010 Area:130      SM$:1

  // LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           SM$:O
  LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           // SM$:R
  WinLoadString (,,,,);                         // SM$:M2
  // LoadString Cat:020 Type:010 Area:060                 SM$:K
  // Replace with WinLoadString                      SM$:S
  //                                    SM$:C
  // LONG APIENTRY WinLoadString (HAB hab, HMODULE hModResource,      SM$:P
  //  ULONG idString, LONG lBufferMax, PSZ pszBuffer);          SM$:P

See Also:

CONTINUE - Format - '/*...*/', Long comments, Prototypes and Examples
BACK - Format - '//' comments and NO Tags
Migration Formats
CONTENTS


ΓòÉΓòÉΓòÉ 8.1.8. Format - '/*...*/', Long comments, Prototypes and Examples ΓòÉΓòÉΓòÉ

Format - '/*...*/', Long comments, Prototypes and Examples

// SM$:FO  C:\TEST\TEST.C - 03/28/94 14:38:42
  /* Open the file with the OF_PARSE flag to obtain the fully qualified
   * pathname in the OFSTRUCT structure.
   */
  // wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);SM$:O
  wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  // SM$:M3
  DosOpen (,,,,,,,)                          // SM$:M3
  DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              // SM$:M2
  // OpenFile Cat:030 Type:010 Area:130                  SM$:K
  // Replace with DosOpen to open a file.  Use DosQueryPathInfo      SM$:L
  // specifying FIL_QUERYFULLNAME to parse the file name.  Use      SM$:L
  // DosSearchPath to query the fully qualified path name of a      SM$:L
  // file.  Use DosDelete to delete a file.                SM$:L
  //                                   SM$:C
  // APIRET APIENTRY DosOpen(PSZ pszFileName, PHFILE pHf,         SM$:P
  //  PULONG pulAction, ULONG  cbFile, ULONG  ulAttribute,        SM$:P
  //  ULONG  fsOpenFlags, ULONG  fsOpenMode, PEAOP2 peaop2);       SM$:P
  // APIRET APIENTRY DosQueryPathInfo(PSZ pszPathName,          SM$:P
  //  ULONG ulInfoLevel, PVOID pInfoBuf, ULONG cbInfoBuf);        SM$:P
  // APIRET APIENTRY DosSearchPath(ULONG flag, PSZ pszPathOrName,     SM$:P
  //  PSZ pszFilename, PBYTE pBuf, ULONG cbBuf);             SM$:P
  // APIRET APIENTRY DosDelete(PSZ pszFile);               SM$:P
  //                                   SM$:C
  // Windows:                               SM$:X
  //  OFSTRUCT OFStruct;                         SM$:X
  //  HFILE hFile = OpenFile ("TEST.DAT", &OFStruct,           SM$:X
  //          OF_CREATE);                    SM$:X
  // OS/2:                                SM$:X
  //  HFILE hFile;                            SM$:X
  //  ULONG ulAction;                          SM$:X
  //  DosOpen ("TEST.DAT", &hFile, &ulAction, FILE_NORMAL,        SM$:X
  //   OPEN_ACTION_CREATE_IF_NEW |                   SM$:X
  //   OPEN_ACTION_REPLACE_IF_EXISTS, OPEN_ACCESS_READWRITE |      SM$:X
  //   OPEN_SHARE_DENYNONE, NULL);                   SM$:X
  //                                   SM$:C
  // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990         SM$:1
  //                                   SM$:C
  // OF_PARSE Cat:020 Type:030 Area:130                  SM$:K
  // Use DosQueryPathInfo specifying FIL_QUERYFULLNAME to         SM$:L
  // query the full path of a file.  This replaces the OpenFile      SM$:L
  // function call.                            SM$:L
  //                                   SM$:C
  // APIRET APIENTRY DosQueryPathInfo(PSZ pszPathName,          SM$:P
  //  ULONG ulInfoLevel, PVOID pInfoBuf, ULONG cbInfoBuf);        SM$:P

  // _lclose (wFileTemp);                         SM$:O
  DosClose (wFileTemp);                        // SM$:M1
  // _lclose replaced with DosClose - Cat:010 Type:010 Area:130      SM$:1

  // LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           SM$:O
  LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           // SM$:R
  WinLoadString (,,,,);                         // SM$:M2
  // LoadString Cat:020 Type:010 Area:060                 SM$:K
  // Replace with WinLoadString                      SM$:L
  //                                    SM$:C
  // LONG APIENTRY WinLoadString (HAB hab, HMODULE hModResource,      SM$:P
  //  ULONG idString, LONG lBufferMax, PSZ pszBuffer);          SM$:P
  //                                    SM$:C
  // Windows:                               SM$:X
  //  int iLen = LoadString (hInst, 1, szBuf, sizeof(szBuf));       SM$:X
  // OS/2:                                 SM$:X
  //  LONG lLen = WinLoadString (hAB, hMod, 1, sizeof(szBuf),       SM$:X
  //          szBuf);                       SM$:X

CONTINUE - Format - Source code with migration comments removed
BACK - Format - '//', Short comments and Prototypes
Migration Formats
CONTENTS


ΓòÉΓòÉΓòÉ 8.1.9. Format - Source code with migration comments removed ΓòÉΓòÉΓòÉ

Format - Source code with migration comments removed

  /* Open the file with the OF_PARSE flag to obtain the fully qualified
   * pathname in the OFSTRUCT structure.
   */
  wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  // SM$:M3
  DosOpen (,,,,,,,)                          // SM$:M3
  DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              // SM$:M2
  DosClose (wFileTemp);                        // SM$:M1
  WinLoadString (,,,,);                        // SM$:M2

CONTINUE - SMART Files
BACK - Format - '/*...*/', Long comments, Prototypes and Examples
Migration Formats
CONTENTS


ΓòÉΓòÉΓòÉ 8.2. SMART Files ΓòÉΓòÉΓòÉ

The SMART generates a number of files related to Analysis and Migration. Also,
a set of files may be created as a result of The SMART Editor creating a
hyperlink database for the source files processed by SMART.

These files are listed below:

  SMART Dictionary and Migration Database files (one set per directory)
   XXXXXXXX.TBL - Dictionary
   SMART1DB.D1 - Database
   SMART1DB.D2 - Database
   SMART1DB.D3 - Database
   SMART1DB.D4 - Database
   SMART1DB.K1 - Database

  Analysis and Migration files (in List-of-Files Directory)
   XXXXXXXX.LST - List-of-Files
   (List-of-Files).RPT - Analysis report
   (List-of-Files).LOG - Logfile from The SMART Editor (SLBUILD)
   (List-of-Files).RSP - Response File for The SMART Editor (SLBUILD)
   (List-of-Files).LNK - Analysis Keyword List
   (List-of-FileX).LOG - Logfile from The SMART Editor (SLBUILD) (Migrated
files)
   (List-of-FileX).RSP - Response File for The SMART Editor (SLBUILD)
(Migrated files)
   (List-of-FileX).LNK - Migration Keyword List

  Analysis and Migration Files (in directories with original source files)
   XXXXXXXXX.X_X - Migrated Source file with mapped extension
   (source file)_^ - Binary analysis data file (one for each source file)

  The SMART Editor Database Link files and report displays (from DB Build)
  (in directory with List-of-Files)
   SLINK2DB.D1 - The SMART Editor Link Database file
   SLINK2DB.D2 - The SMART Editor Link Database file
   SLINK2DB.K1 - The SMART Editor Link Database file
   SLINK2DB.K2 - The SMART Editor Link Database file
   SLINK2DB.K3 - The SMART Editor Link Database file
   SL_CALL.RPT - The SMART Editor Call Tree display report
   SL_DLGBOX.RPT - The SMART Editor Dialog Template display report
   SL_FUNCT.RPT - The SMART Editor Functions List display report
   SL_GLOB.RPT - The SMART Editor Globals display report
   SL_MODS.RPT - The SMART Editor Files display report
   SL_UNREF.RPT - The SMART Editor Unreferenced Functions display report
   SL_USER.RPT - The SMART Editor User Links display report
   (contains keywords found in Migration or Analysis from SMART processes)

  SMART Resource Translator
   resourcefilename.ERR - Default error filename
   resourcefilename.HHH - Default generated header filename
   resourcefilename.SUM - Default summary filename
   resourcefilename.RCX - Default translated resource filename

  Other SMART Files
   MAPEXT.DAT - File extension mapping data (SMART directory).

CONTINUE - Specifications and Restrictions
BACK - Format - Source code with migration comments removed
CONTENTS


ΓòÉΓòÉΓòÉ 8.3. Specifications and Restrictions ΓòÉΓòÉΓòÉ

Specifications and Restrictions

   Maximum path and file length   255
   Maximum Migration Database Path length   47
   Maximum directory levels    10
   Maximum ifdef name length   40
   Maximum "List-of-Files" data   64K
   (unless created by an editor)
   Maximum lines of code in any one file  32767
   Maximum code line length    512
   Supported preprocessor statements:
   #if, #ifdef, # if defined, #else, #elseif, #endif

   Analysis and Migration- syntax not supported:

   - Keywords within quotation marks
   - Keywords within macro define statements
   - Fields of a structure are not identified for migration
   - Context of a parameter within a call

   Resource Translator (Windows Only) restrictions:

   - Macros cannot be used for any of the reserved resource
     definition keywords.
   - Preprocessor conditional statements must begin and end
     within a single file.
   - Preprocessor conditional statements within a DIALOG
     resource definition template are properly evaluated but
     are not output to the converted resource file.
   - #include and rcinclude statements are not recognized within
     any multiline resource statements.
   - #define statements are not recognized within any multiline
     resource statements.
   - Macro definitions which contain parameter substitutions are
     currently  not processed.
   - Can either replace the existing files with the converted files
     or save the converted file with a different file extension.
   - When converting dialog units as outlined in the Dialog
     Conversion  section the conversion is relative to the
     system font for the current display resolution.

CONTINUE - Technical Support
BACK - SMART Files
CONTENTS


ΓòÉΓòÉΓòÉ 8.4. Technical Support ΓòÉΓòÉΓòÉ

Technical Support

  Internet:
     Send questions or comments to [e-mail]

  CompuServe:
     Obtain access to the IBM OS/2 Developer Forum 2.
     To obtain access to the Developer Connection section, please
     send a note to CompuServe userid 73423,2767.
     To access the forum, type GO OS2DF2 at the ! prompt; then
     select the Developer Connection section.

  OS/2 BBS:
     The DEVCON CFORUM, under TalkLink, is a feature under the
     IBMLink Commercial Services.  Customers in the U.S. can call
     1-800-547-1283; customers outside of the U.S. should contact
     their local IBM Marketing Representative.

BACK - Specifications and Restrictions
CONTENTS