home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / smart21b.zip / SM_GUID2.INF (.txt) < prev    next >
OS/2 Help File  |  1995-09-15  |  82KB  |  2,329 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. The SMART User's Guide ΓòÉΓòÉΓòÉ
  3.  
  4.    The SMART2 User's Guide
  5.  
  6.        Version 2.1B
  7.       September 1995
  8.  
  9.    (C) 1991, 1994, 1995 One Up Corporation
  10.  
  11.        Notice 
  12.        Table of Contents 
  13.  
  14.  
  15. ΓòÉΓòÉΓòÉ 2. Notice ΓòÉΓòÉΓòÉ
  16.  
  17. ** NOTICE ** 
  18.  
  19. This document may not, in whole or in part, be copied, reproduced, photocopied, 
  20. translated, or reproduced to any electronic medium or machine readable form 
  21. without prior written consent from One Up Corporation. 
  22.  
  23. This publication could contain technical inaccuracies or typographical errors. 
  24. As changes are periodically made to the information herein; these changes may 
  25. be incorporated in new additions of the publication. One Up Corporation may 
  26. make improvements and/or changes in the product and/or the program described in 
  27. this publication at any time. 
  28.  
  29. One Up Corporation is not responsible for any direct or indirect damage or loss 
  30. of business resulting from inaccuracies or omissions in this publication.  The 
  31. specifications contained in this document are subject to change without notice. 
  32.  
  33. SMART - Source Migration Analysis Reporting Toolset is a trademark of One Up 
  34. Corporation. OS/2, Presentation Manager are trademarks of the International 
  35. Business Machines Corporation. IBM is a registered trademark of the 
  36. International Business Machines Corporation. Other trademarks are property of 
  37. their respective companies. 
  38.  
  39.       CONTENTS 
  40.  
  41.  
  42. ΓòÉΓòÉΓòÉ 3. Table of Contents ΓòÉΓòÉΓòÉ
  43.  
  44.        Chapter 1 - Introduction 
  45.         SMART - Concepts 
  46.         The Analysis/Migration Process 
  47.         What this Document Contains 
  48.         Where is the Remaining Documentation? 
  49.        Chapter 2 - Installation 
  50.         Before You Begin 
  51.         Installing SMART 
  52.         Setup Options 
  53.        Chapter 3 - Getting Started 
  54.         Getting Ready 
  55.         The Analysis Process 
  56.         The Migration Process 
  57.         Completing The Migration 
  58.         The SMART Viewer 
  59.         The SMART Resource Translator 
  60.         The SMART Win Help Translator 
  61.         Graphical Resource Conversion 
  62.         The SMART Editor Development Tool 
  63.        Chapter 4 - Techniques 
  64.         Preparing Your Source Code 
  65.         Reading the Analysis Summary Reports 
  66.         Reading the Analysis Display/Report 
  67.         Interpreting the Analysis 
  68.         Use of Common Functions 
  69.         Source Migration Format Considerations 
  70.         File Extension Mapping 
  71.         Source Migration Comment Code Removal 
  72.         Increased Productivity with The SMART Editor 
  73.        Chapter 5 - Reference 
  74.         Migration Formats 
  75.         Specifications and Restrictions 
  76.         SMART Files 
  77.         Technical Support 
  78.  
  79.       CONTINUE - Chapter 1 
  80.  
  81.  
  82. ΓòÉΓòÉΓòÉ 4. Chapter 1 - Introduction ΓòÉΓòÉΓòÉ
  83.  
  84. Chapter 1 - Introduction 
  85.  
  86.         SMART - Concepts 
  87.         The Analysis/Migration Process 
  88.         What this Document Contains 
  89.         Where is the Remaining Documentation? 
  90.  
  91.       CONTINUE - SMART - Concepts 
  92.       BACK - Table of Contents 
  93.  
  94.  
  95. ΓòÉΓòÉΓòÉ 4.1. SMART - Concepts ΓòÉΓòÉΓòÉ
  96.  
  97. SMART - Concepts 
  98.  
  99.   NOTE: REFERENCES TO SOURCELINK, SMART VIEWER, MIGRATION and RESOURCE 
  100. CONVERSION are only applicable with the Analysis AND Migration version of 
  101. SMART.  If you are only licensed for the Analysis version of SMART, you may 
  102. ignore information in this and other documents to those functions that you may 
  103. not have in this product. 
  104.  
  105.   SMART - Source Migration Analysis Reporting Toolset provides analysis and 
  106. source code migration assistance from one platform to another or one version to 
  107. another on a given platform.  This version of SMART executes on the OS/2 
  108. platform and is used for the migration of 'C' and C++ source code from Windows 
  109. 16 bit to OS/2 32 bit or OS/2 16 bit to OS/2 32 bit or Win32 to OS/2 32 bit 
  110. depending upon the licensed, installed tables. 
  111.  
  112.   The process of porting source code from one platform to another is indeed 
  113. difficult and subjective. 
  114.  
  115.   In fact, exploiting the features of one platform, and using proprietary 
  116. libraries, classes, and objects may make it severely difficult to port to 
  117. another platform without a major rewrite of the source code. 
  118.  
  119.   There is no pat solution or utility to port all code to a target platform, 
  120. and we dare say there most probably never will be.  However, with the proper 
  121. tools, methodology, techniques and training the effort required in the 
  122. migration of source code can be GREATLY reduced. 
  123.  
  124.   The most appropriate solution for this process is to use productive computer 
  125. tools to perform tasks that are easily identified, routine, and labor intensive 
  126. and provide a knowledge base to contain information related to all occurrence 
  127. types of differences between the platforms.  The human element is most 
  128. appropriately applied where the complexity of the issue is too complicated for 
  129. the computer analysis.  It is advantageous to provide the programming 
  130. professional with powerful productivity tools to make global changes based on 
  131. the migration issues of complex nature. 
  132.  
  133.   SMART is designed to assist in the analysis and migration of native source 
  134. code from one platform to another or one version of an operating environment to 
  135. another on the same platform. 
  136.  
  137.   The platform dependent data is contained in the migration dictionary (table) 
  138. and the migration database files. 
  139.  
  140.   This process is based on finding keywords (API calls, symbols, parameters, 
  141. typedefs, etc) that differ between the source and target platforms in the 
  142. migration. No attempt is made to analyze the intended use of the application 
  143. source code.  As such, there is no intent to evaluate platform exploitation, or 
  144. evaluate the use of the source code for application functionality such as MDI, 
  145. DDEML, communication, LAN, and etc. The base API keyword differences are 
  146. categorized into groups to represent the difficulty in migration, ranging from 
  147. a simple literal replacement to the case where the functionality does not exist 
  148. in the target platform. 
  149.  
  150.   In the Analysis process, SMART will analyze source code and prepare a report 
  151. (display) providing a detailed evaluation of the migration requirements. 
  152.  
  153.   Furthermore, in the migration process, SMART will process the user specified 
  154. source files and create migrated source files.  The migrated source file will 
  155. contain automatic migration changes (where possible) and in all cases will 
  156. provide in-line commented code for the developer to complete the migration. 
  157.  
  158.       CONTINUE - The Analysis/Migration Process 
  159.       BACK - Chapter 1 - Introduction 
  160.       CONTENTS 
  161.  
  162.  
  163. ΓòÉΓòÉΓòÉ 4.2. The Analysis/Migration Process ΓòÉΓòÉΓòÉ
  164.  
  165. The Analysis/Migration Process 
  166.  
  167.   There are several key concepts regarding the operation of the SMART Toolset 
  168. including: The List-of-Files, keyword, category and hit. 
  169.  
  170.   A List-of-Files is a text file that contains all of the fully qualified 
  171. filenames for the source files to be processed by SMART.  Typically this will 
  172. include all program source files (.C) and all header files (.H).  Resource 
  173. files are migrated in a separate process using the resource translator 
  174. (Windows->OS/2 Migration only). 
  175.  
  176.   Keywords are items that are the basis for the definition of the interface to 
  177. a platform and may represent API (Application Programming Interface) calls, 
  178. symbols, parameters, structures, and typedefs.  Keywords are the basis for 
  179. migration with SMART.  As keywords are encountered in the SMART Analysis and/or 
  180. Migration processes SMART will look to the migration tables to indicate the 
  181. appropriate change as required. 
  182.  
  183.   Category is a key concept in the SMART process of source code migration.  All 
  184. of the items to be considered for migration are identified by its migration 
  185. difficulty.  The "category" of difficulty increases in effort and consideration 
  186. and range from a category of "000" to the most difficult category of "050". 
  187.  
  188.   There is one additional category of "999" indicating that the keyword has not 
  189. been defined.  This simply indicates that a keyword is identified for 
  190. migration, but the explanation for the migration has not yet been defined in 
  191. the SMART database. 
  192.  
  193.   The definitions for the difficulty categories are as follows: 
  194.  
  195.         000  Informational only - An exact match of the keyword exists in the 
  196.       target platform but there is change in the size of type. (e.g. short to a 
  197.       long). 
  198.  
  199.         010  Literal replacement or Automatic migration - An equivalent 
  200.       definition exists in the target platform but a literal change in the 
  201.       keyword is required (e.g., LPSTR to PSZ) or keywords that are 
  202.       automatically migrated through the use of MiCL Commands. 
  203.  
  204.         020  Replacement with parameter changes - Equivalent functionality 
  205.       exists in the target platform but parameters or fields of a structure 
  206.       differ slightly from the source platform definition (e.g., SetWindowPos 
  207.       to WinSetWindowPos).  Also  included are parameters that are not 
  208.       applicable or required on the target platform (e.g., MakeProcInstance). 
  209.  
  210.         030  Change with more / less API calls - Equivalent functionality 
  211.       exists in the target platform but it must be implemented with  more, or 
  212.       sometimes less, function calls (e.g., DlgDirList).  Also included are 
  213.       items which map to one of several choices depending upon the type of 
  214.       parameter used (e.g., GetObject). 
  215.  
  216.         040  Logic changes required - Similar functionality exists in the 
  217.       target platform but the logic required to emulate the functionality must 
  218.       be reworked (e.g., CreatePatternBrush). 
  219.  
  220.         050  Functionality does not exist - There is no means provided to 
  221.       perform the same functionality in the target platform (e.g., 
  222.       GetKeynameText).  Workaround coding must be implemented, where possible. 
  223.  
  224.         999  Dictionary entry not defined - The database does not currently 
  225.       have a complete description for the migration of the keyword. 
  226.  
  227.    A Hit is simply a term referring to a match between a keyword in your source 
  228.  code and an item in the migration database indicating that a code change may 
  229.  be required. 
  230.  
  231.       CONTINUE - What this Document Contains 
  232.       BACK - SMART - Concepts 
  233.       CONTENTS 
  234.  
  235.  
  236. ΓòÉΓòÉΓòÉ 4.3. What this Document Contains ΓòÉΓòÉΓòÉ
  237.  
  238. What this Document Contains 
  239.  
  240.   This document, contains an introduction in the use of the application 
  241. development tool SMART. 
  242.  
  243.   Detailed information regarding individual functions, dialog panels, controls, 
  244. parameters and options is available in the on-line documentation accessible 
  245. when SMART is running.  By pressing "F1" or accessing the on-line help through 
  246. the "Help" menu items you can obtain details regarding the specific operation 
  247. of SMART. 
  248.  
  249.   Neither this document nor the SMART on-line help will attempt to cover 
  250. specific platform migration issues beyond the help found in the on-line 
  251. migration data base access through the SMART Viewer.  Migration issues are 
  252. covered in the documentation of the specific platforms and are left to the 
  253. developer to research. 
  254.  
  255.   This document may make reference to utilities and functions that may be 
  256. specific to a particular platform and may not be included in your licensed copy 
  257. of SMART. 
  258.  
  259.   Programming UDMD dictionaries, including programming with MiCL Commands is 
  260. fully explained in the document file "SMART2 Programming Guide" found in the 
  261. SMART2 Desktop Folder. 
  262.  
  263.   The complete documentation of The SMART Editor is found in the separate 
  264. manual entitled "The SMART Editor Technical Manual". 
  265.  
  266.   The chapters of this document flow in a logical order to acquaint you with 
  267. the concepts, principles and general introduction to SMART. 
  268.  
  269.   Chapter 1 - Introduction 
  270.  
  271.    An introduction to the SMART methodology of source code migration and the 
  272. functionality of the SMART Toolset. 
  273.  
  274.   Chapter 2 - Installation 
  275.  
  276.    Step-wise instructions in the installation of SMART. 
  277.  
  278.   Chapter 3 - Gettiong Started 
  279.  
  280.    A guided introductory tutorial for executing the analysis and migration 
  281. processes. 
  282.  
  283.   Chapter 4 - Techniques 
  284.  
  285.    A set of topics covering important techniques in the use of SMART. 
  286.  
  287.   Chapter 5 - Reference 
  288.  
  289.    A chapter related to reference topics including migration formats 
  290. specifications and technical support for this product. 
  291.  
  292.       CONTINUE - Where is the Remaining Documentation? 
  293.       BACK - Analysis/Migration Process 
  294.       CONTENTS 
  295.  
  296.  
  297. ΓòÉΓòÉΓòÉ 4.4. Where is the Remaining Documentation? ΓòÉΓòÉΓòÉ
  298.  
  299. Where is the Remaining Documentation? 
  300.  
  301.   It's on-line and accessible as you run SMART.  We intentionally put the 
  302. details of all the parameters, options and definitions of the dialog controls 
  303. on-line.  This puts your reference material where you need it most - 
  304. contextually sensitive at the point of processing. 
  305.  
  306.   While you are processing SMART press "F1" to obtain help at any menu item or 
  307. dialog panel.  You can also use the menu items under "Help" on your main menu 
  308. bar to browse through the SMART On-Line help facility.  In addition to the 
  309. index and contents panels, you can view panels on additional One-Up products, 
  310. reference material and tutorials on the Analysis or Migration processes. 
  311.  
  312.       CONTINUE - Chapter 2 - Installation 
  313.       BACK - What This Document Contains 
  314.       CONTENTS 
  315.  
  316.  
  317. ΓòÉΓòÉΓòÉ 5. Chapter 2 - Installation ΓòÉΓòÉΓòÉ
  318.  
  319. Chapter 2 - Installation 
  320.  
  321.         Before You Begin 
  322.         Installing SMART 
  323.         Setup Options 
  324.  
  325.       CONTINUE - Before You Begin 
  326.       BACK - Where is the Remaining Documentation? 
  327.       CONTENTS 
  328.  
  329.  
  330. ΓòÉΓòÉΓòÉ 5.1. Before You Begin ΓòÉΓòÉΓòÉ
  331.  
  332. Before You Begin 
  333.  
  334.   Before you begin the installation of SMART you may wish to take a moment to 
  335. insure that you are prepared for the installation. 
  336.  
  337.   You can install SMART from CD-ROM or you can install from Diskette.  If you 
  338. have this product on CD-ROM you can create diskettes for installation by 
  339. executing the command MAKADSK or MAKMDSK (Depending on whether you have the 
  340. analysis version of SMART or the Analysis and Migration).  This command file 
  341. requires that you specify the full drive and directory path of the SMART base 
  342. files on the CD-ROM. 
  343.  
  344.   If you are licensed for The SMART Editor, The SMART Editor documentation 
  345. regarding installation in The SMART Editor Technical Manual.  Your installation 
  346. of SMART will consist of an Install diskette and one or more migration table 
  347. diskettes depending upon your license. 
  348.  
  349.   The hard disk space requirements for the basic installation is as follows: 
  350.  
  351.   SMART Source Migration:
  352.    Win3.1 -> OS/2 2.1 -   8 megabytes
  353.    Win32 -> OS/2 2.1 -   12 megabytes
  354.    OS/2 16->32 bit -     3 megabytes
  355.   The SMART Editor:       2 megabytes
  356.  
  357.   If you have received this product on CD-ROM you can perform a mini-install of 
  358. the SMART on your hard disk (requiring only 15 KBYTES) and run from the CD-ROM. 
  359.  
  360.   This space only considers the installation files and does not include files 
  361. created during the run time execution of either SMART or The SMART Editor. 
  362.  
  363.   Depending upon the migration formats chosen, you may experience file 
  364. requirements over five or six times the original source code space in the 
  365. source migration and The SMART Editor hyperlink data base build. 
  366.  
  367.       CONTINUE - Installing SMART 
  368.       BACK - Chapter 2 - Installation 
  369.       CONTENTS 
  370.  
  371.  
  372. ΓòÉΓòÉΓòÉ 5.2. Installing SMART ΓòÉΓòÉΓòÉ
  373.  
  374. Installing SMART 
  375.  
  376.   The installation of SMART is simple. 
  377.  
  378.    1.  Start by inserting the SMART Installation diskette into your floppy 
  379.       drive (A or B) or change directory to the CD-ROM directory containg the 
  380.       SMART files. (Depending upon the source of your SMART installation 
  381.       files). 
  382.  
  383.    2.  From an OS/2 command line, type:  a: (or b:), then  install 
  384.  
  385.    3.  A SMART installation window will appear to guide you through the 
  386.       installation. 
  387.  
  388.    4.  When ready, select "Install" from the main installation menu bar. 
  389.  
  390.    5.  You will be requested to specify the directory that will contain all of 
  391.       the SMART executing files and will be the root for subsequent 
  392.       sub-directories to contain sample files and migration tables. 
  393.  
  394.    6.  You will also have an opportunity to select other installation 
  395.       parameters, including the Platform Tables to be installed (For Full disk 
  396.       installation). 
  397.  
  398.    7.  Responding to all of the installation pop-up panels with an "Ok" (Enter 
  399.       key) will result in the default installation. 
  400.  
  401.    8.  It is recommended that you store the SMART DLLs in the directory with 
  402.       the other SMART executables.  To do so, you must have a "." (current 
  403.       path) in the LIBPATH statement in your CONFIG.SYS file.  If not, then you 
  404.       must store the DLL in a path specified by the LIBPATH statement. 
  405.  
  406.    9.  At the conclusion of the installation of SMART a desktop icon will be 
  407.       created for the SMART application and the SMART Viewer and two SMART 
  408.       Information Files. 
  409.  
  410.   10.  If you have not already installed The SMART Editor, please follow the 
  411.       instructions in Chapter 3 of The SMART Editor Technical Manual to 
  412.       properly install this companion application. You should install The SMART 
  413.       Editor before SMART if you are licensed for this product. 
  414.  
  415.       CONTINUE - Setup Options 
  416.       BACK - Before You Begin 
  417.       CONTENTS 
  418.  
  419.  
  420. ΓòÉΓòÉΓòÉ 5.3. Setup Options ΓòÉΓòÉΓòÉ
  421.  
  422. Setup Options 
  423.  
  424.   After you have successfully installed SMART on your computer you may need to 
  425. modify the initial setup options in the SMART application. 
  426.  
  427.    1.  Open the Setup Options dialog panel by selecting "Setup Options" under 
  428.       the "Options" main menu item. 
  429.  
  430.    2.  Check to insure that your editor is specified in this panel.  If you 
  431.       have installed The SMART Editor, your editor name will be SLSTART. If you 
  432.       are using any other editor, enter the path and filename of the editor in 
  433.       the "Editor/Browser" entry field. 
  434.  
  435.    3.  The next item of importance is to insure that you have specified the 
  436.       appropriate SMART Migration Table filename in the Tables Selection panel, 
  437.       under the "Tables" main menu item. 
  438.  
  439.    4.  Both SMART and The SMART Editor allow you to drag-and-drop a selected 
  440.       font from the OS/2 system font palette onto the menu bar of the 
  441.       application in order to set all window fonts. After you have dropped the 
  442.       selected font, close and reopen the application to propagate the selected 
  443.       font throughout the application. 
  444.  
  445.    5.  Once you have installed The SMART Editor you can register the SMART 
  446.       Viewer REXX macro (SMVIEWER.REX) under the "Macro" menu item.  To 
  447.       accomplish this, pull down the "Macro" menu list in The SMART Editor and 
  448.       select "Define Menu Item".  Choose "Add" and complete the dialog panel to 
  449.       register SMVIEWER.REX as a macro item, with your chose of accelerator 
  450.       key. Using this macro, you can mouse click on a source platform keyword 
  451.       and press your chosen accelerator key to display SMART Viewer on-line 
  452.       migration help. 
  453.  
  454.    Within SMART Viewer you can drop your chosen font on the client area of the 
  455.  application. After you have set the application font you can set the fonts for 
  456.  each of the on-line display windows. 
  457.  
  458.    The following chapters in this document will guide you through the basic 
  459.  functionality in the Analysis and Migration processes of SMART. 
  460.  
  461.       CONTINUE - Chapter 3 - Getting Started 
  462.       BACK - Installing SMART 
  463.       CONTENTS 
  464.  
  465.  
  466. ΓòÉΓòÉΓòÉ 6. Chapter 3 - Getting Started ΓòÉΓòÉΓòÉ
  467.  
  468. Chapter 3 - Getting Started 
  469.  
  470.         Getting Ready 
  471.         The Analysis Process 
  472.         The Migration Process 
  473.         Completing The Migration 
  474.         The SMART Viewer 
  475.         The SMART Resource Translator 
  476.         The SMART Win Help Translator 
  477.         Graphical Resource Conversion 
  478.         The SMART Editor Development Tool 
  479.  
  480.       CONTINUE - Getting Ready 
  481.       BACK - Setup Options 
  482.       CONTENTS 
  483.  
  484.  
  485. ΓòÉΓòÉΓòÉ 6.1. Getting Ready ΓòÉΓòÉΓòÉ
  486.  
  487. Getting Ready 
  488.  
  489.   You may wish to become familiar with SMART by using the sample source code 
  490. files supplied in the installation of SMART under the "Samples" sub-directory. 
  491. You can follow along with this chapter and use the steps as a general tutorial, 
  492. or you may wish to strike out on your own and explore the SMART functionality 
  493. on your own files. 
  494.  
  495.   Before you start processing, it is always a good idea to backup your original 
  496. source code. SMART Source Migration generates source code.  Sparing you the 
  497. pain of inadvertently overwriting original source code, it is well advised to 
  498. "hide" your original code during your processing. 
  499.  
  500.   SMART creates analysis files in the same directory as the source code being 
  501. analyzed. If you are running from CD-ROM and using the application sample 
  502. files, you will need to copy these files to your read/write hard drive. 
  503.  
  504.   It is also advised that you always use the option to generate the changed 
  505. code using the extension mapping.  This will insure that a SMART process 
  506. creates a file of similar name, having a different file extension to maintain 
  507. uniqueness.  Using this technique, you can simply rerun the process, if needed, 
  508. without losing the original source file. 
  509.  
  510.   You will most probably wish to run the SMART migration process multiple times 
  511. on a sample code set with different format options to insure that you achieve 
  512. the desired results for your particular needs. 
  513.  
  514.       CONTINUE - The Analysis Process 
  515.       BACK - Chapter 3 - Getting Started 
  516.       CONTENTS 
  517.  
  518.  
  519. ΓòÉΓòÉΓòÉ 6.2. The Analysis Process ΓòÉΓòÉΓòÉ
  520.  
  521. The Analysis Process 
  522.  
  523.   The analysis of source code for an evaluation of the migration and porting 
  524. effort is accomplished through the use of SMART Analysis Procedure. 
  525.  
  526.   This procedure simply consists of creating a text file (called a 
  527. List-of-Files) with the fully qualified filenames of the files to be analyzed, 
  528. and then perform the analysis procedure. 
  529.  
  530.   The results of the analysis can be viewed on-screen and printed using The 
  531. SMART Editor or a word processing application. 
  532.  
  533.   First, create your analysis directories and sub-directories. 
  534.  
  535.   Each separate analysis should be performed from a separate directory. The 
  536. directory will contain the "List-of-Files" file, and subsequently will contain 
  537. analysis files created by the SMART Analysis process. 
  538.  
  539.   If separate analyses are to be created, each to represent a different 
  540. component of the product under analysis, an individual sub-directory should be 
  541. created to contain the analysis files.  Each "List-of-Files" for individual 
  542. analyses should have a different filename, even though they will be in a 
  543. different sub-directory for ease of identification. Sub-directories can be 
  544. created from The SMART Editor using the "Copy"  function under the "More" main 
  545. menu selection. 
  546.  
  547.   Select the directory to create the new sub-directory in the "TO" section of 
  548. the "Copy" dialog panel.  Type the name of the new sub-directory in the "TO" 
  549. "File" entry panel and press "Make Dir.". Note that you will automatically be 
  550. placed in this new sub-directory. 
  551.  
  552.   Copy the source files to be analyzed to a backup directory  (and appropriate 
  553. sub-directories) that will be used in this analysis. Create the "List-of-Files" 
  554. files containing the files for the  analysis.  Use the "Maintain List-of-Files" 
  555. function under the "Files" main menu item in SMART or the equivalent function 
  556. in The SMART Editor under the "Link" main menu.  The files in this list may 
  557. span multiple directories and even drives. 
  558.  
  559.   Execute "Analyze Code" under the "Analysis" Menu selection. Take care to 
  560. select the proper option on the setup panel for this function. 
  561.  
  562.   The standard options will have only the "Send Analysis Output to Editor" 
  563. checked (all other options unchecked).  The  "List-of-Files" filename should be 
  564. shown in the "List-of-Files" entry panel.  If you chose to create a The SMART 
  565. Editor Link Database, you will be able to hyperlink to points of change from 
  566. the report created from this analysis  procedure. 
  567.  
  568.   NOTE: Multiple instances of SMART can be run at the same time if running more 
  569. than one analysis.  This may speed processing. 
  570.  
  571.   At the completion of the analysis, you will be able to print the analysis 
  572. report from SMART (as displayed at the completion of the analysis). 
  573.  
  574.   Select "Printer Setup" to select appropriate printer, and then choose "Job 
  575. Properties" to select "Landscape" for the printing mode. Close the printing 
  576. setup panels with "Ok". 
  577.  
  578.   Select "Formatting" and set the following parameters for the printed format. 
  579. Uncheck "Date/Time..." and "Word Wrap". 
  580.  
  581.   Set all page margins to 0.0. 
  582.  
  583.   Press "Select Fonts".  Uncheck "Display" but leave "Printer" fonts checked. 
  584. Select the smallest "Courier" font available, "Normal" style. 
  585.  
  586.   Close the "Formatting panels with "Ok". One last check before printing - 
  587. insure that "Print File" on the "Print" dialog panel is selected (instead of 
  588. "Print Select"). Press "Ok" on the "Print" dialog panel to print the analysis 
  589. report. Removal and Backup of Analysis Files. 
  590.  
  591.   To save the analysis files to floppy disk, select "Pack up Analysis Files" 
  592. from the "Analysis" menu in SMART  If you are running multiple analyses, you 
  593. may wish to perform this step after each analysis.  You will need a floppy disk 
  594. with blank sufficient space to perform this function.  You will also need a 
  595. copy of the compression utility "PKZIP2.EXE" from PKWARE (not included with 
  596. this application). 
  597.  
  598.   The captured data in these analysis files contains absolutely no other 
  599. information than appears in the analysis report.  The data is in text and 
  600. binary format and is used to rerun the analysis report if necessary with 
  601. different file combinations or analysis options.  The files copied to the 
  602. floppy disk are of the analysis report, a compress file containing the analysis 
  603. numerical summary data, and the text format of the List-of-Files file used for 
  604. the analysis. 
  605.  
  606.   After the analysis data is copied to the floppy disk, you can remove the 
  607. small summary analyses files by selecting the  "Remove Temp Analysis Files" 
  608. from the "Analysis" menu.  Insure that the proper "List-of-Files" file is used 
  609. in this process.  If multiple analyses are performed, this process must be 
  610. performed for each List-of-Files used.  This process will delete all "*.??^" 
  611. files associated with the analysis. 
  612.  
  613.   The 'EFFORT' value calculated for the Analysis Report is a relative number 
  614. related to the number of hours required to complete the migration.  The is a 
  615. subjective number and varies depending upon the developers experience in the 
  616. migrating platforms, and the tools, techniques and methodologies uses in the 
  617. migration.  The One Up Corporation Porting Work Shops may greatly reduce your 
  618. porting effort through the techniques taught in these Work Shop sessions. 
  619.  
  620.   It is suggested that you proceed through a complete migration of the sample 
  621. code provided in the installation of this product, or other small sample of 
  622. your source code to determine the relative difference between the reported 
  623. EFFORT from SMART and the hours required in your actual process. The EFFORT 
  624. value from the SMART Analysis should be used as a guide only and may not bear 
  625. any  correspondence to the actual time required in any porting process. 
  626.  
  627.   The EFFORT value does not include any time required to prepare your code for 
  628. migration, nor the correction of any compilation errors introduced by the 
  629. migration process, or time required in learning the target or source platform 
  630. programming internals. 
  631.  
  632.       CONTINUE - The Migration Process 
  633.       BACK - Getting Ready 
  634.       CONTENTS 
  635.  
  636.  
  637. ΓòÉΓòÉΓòÉ 6.3. The Migration Process ΓòÉΓòÉΓòÉ
  638.  
  639. The Migration Process 
  640.  
  641.   The migration process of SMART processes the specified source files and 
  642. generates migrated files with code changes and in-line comments.  The 
  643. List-of-Files file contains the fully qualified filenames to migrate (as in the 
  644. Analysis Process). 
  645.  
  646.   The migrated files will be placed in the same directory as the source files 
  647. (with mapped extensions if desired). 
  648.  
  649.   The Migration Configuration dialog panel provides the user with the 
  650. opportunity to select migration formats and options for each category of 
  651. difficulty.  It is highly recommended that you test various output migration 
  652. formats with a small set of sample code in order to determine the best format 
  653. for your intended purpose. 
  654.  
  655.   Prior to executing the Migration Procedure, you will want to perform the 
  656. Analysis Procedure on the source code to be migrated. 
  657.  
  658.   Create the "List-of-Files" files containing the files for the  analysis.  Use 
  659. the "Maintain List-of-Files" function under the "Files" main menu item in SMART 
  660. or the equivalent function in The SMART Editor under the "Link" main menu.  The 
  661. files in this list may span multiple directories and even drives. 
  662.  
  663.   If you have created the List-of-Files in the Analysis procedure, you may wish 
  664. to modify the list for migrating a sub set of the original List-of-Files or 
  665. simply migrate the full code set. 
  666.  
  667.   Execute "Migrate Code" under the "Migration" Menu selection. Take care to 
  668. select the proper option on the setup panel for this function. 
  669.  
  670.   You will have a great latitude of options in the configuration of the 
  671. Migration process. Refer to the Migration Configuration Dialog Panel for an 
  672. explanation of these options. The typical default selections include use of 
  673. commented code (as opposed to 'ifdef' blocks). 
  674.  
  675.   If you are using The SMART Editor you will want to create a link database for 
  676. hyperlinking to migrated changes, otherwise uncheck this option.  If building 
  677. The SMART Editor Database you may wish to set the DB options to link on the 
  678. migration keyword list. 
  679.  
  680.   You may wish to use the files in the samples directory of the SMART 
  681. installation to try migrations with various options and see the results. 
  682.  
  683.   Rerunning the Migration process with the same List-of-Files and the same file 
  684. extension mapping will overwrite the original migration files.  Recursive 
  685. migration of the same files may give unpredictable results. Note that the 
  686. migration process creates a new List-of-Files file containing the new migrated 
  687. file names which you may wish to use for a number of purposes, including The 
  688. SMART Editor Link Database build. 
  689.  
  690.   You can now proceed through the migrated files to complete the migration 
  691. according to the in-line comments that have been placed in the migrated code. 
  692. Use of an editor with hyperlink source code access, like The SMART Editor will 
  693. be a valuable asset in quickly pulling up on-line help and accessing all 
  694. references to a migrated function, structure, etc. 
  695.  
  696.   After you have made all changes to the migrated code, you can use the 
  697. "Remove Comments and Tagged Code" to remove migration comment, examples and 
  698. other code that has been inserted in the source files to assist you in the 
  699. migration process. 
  700.  
  701.       CONTINUE - Completing The Migration 
  702.       BACK - The Analysis Process 
  703.       CONTENTS 
  704.  
  705.  
  706. ΓòÉΓòÉΓòÉ 6.4. Completing the Migration ΓòÉΓòÉΓòÉ
  707.  
  708. Completing the Migration 
  709.  
  710.   SMART identifies Category 000 keywords (which may require no migration at 
  711. all) and automatically makes the changes for Category 010.  This may account 
  712. for 50-70% of the changes required in the migration.  The remaining changes are 
  713. identified by the comment insertion according to the options that you have 
  714. chosen in the Migration Options Panel. 
  715.  
  716.   These remaining changes, due to their categories, must be evaluated and 
  717. changed as you deem necessary.  You may wish to write a replacement function 
  718. for the API call and change the name to call this new function or you may need 
  719. to go to each change indicated and rewrite a portion of the code depending upon 
  720. the usage.  Any combination of techniques may be used.  You are the best one to 
  721. decide how you should approach this completion effort based upon productivity, 
  722. compatibility and other criteria. 
  723.  
  724.   In general, you may have chosen to restate the source code for the Category 
  725. 020 changes. Since, by definition, these changes may require little effort, the 
  726. original restated code is a good starting point. 
  727.  
  728.   In most cases, you will want to make use of The SMART Editor to hyperlink to 
  729. each type of change and make the decided change "across the board".  You will 
  730. also find The SMART Editor useful to find all occurrences of a structure, or 
  731. function call before you make a change to a field or parameter to insure you 
  732. fully understand its use. 
  733.  
  734.   You may also find The SMART Editor valuable in making global replacements for 
  735. a number of strings in all source files. 
  736.  
  737.   It is highly recommended that you become familiar with The SMART Editor 
  738. before you begin your migration.  It will surely save you many hours of 
  739. searching though your source code to find and display specific keywords, 
  740. functions and other elements of your code. 
  741.  
  742.   Take the time to go through the tutorial in The SMART Editor Technical 
  743. Manual.  It will only require about thirty minutes of your time and will 
  744. provide you with a general understanding of the functionality of this product. 
  745.  
  746.   With the use of The SMART Editor you will have context sensitive access to 
  747. the on-line help for the IBM development help facility. 
  748.  
  749.   The other productive tool in the SMART Toolset is the SMART Viewer.  Using 
  750. this on-line viewer you will be able to access the migration help of any 
  751. specified keyword.  Using these techniques, you may desire to have less comment 
  752. inserted in-line with the migrated code and prefer to use the SMART Viewer for 
  753. migration assistance for each encountered keyword. 
  754.  
  755.   The comment tags at the end of each migration inserted line are coded for 
  756. identification and removal.  You can use these tags for searching (using The 
  757. SMART Editor).  You can adopt techniques of tagging each line as you complete 
  758. the migration.  There are several REXX macros provided with SMART to be used 
  759. with The SMART Editor to enable  personal tagging of the migration lines as you 
  760. proceed with your work. 
  761.  
  762.   When complete, you can easily remove all tagged lines and tags using the menu 
  763. item under "Migration" entitled "Remove Tagged Code Lines...".  The dialog 
  764. panel associated with this function allows you to specify the particular lines 
  765. or tags to be removed. 
  766.  
  767.       CONTINUE - The SMART Viewer 
  768.       BACK - The Migration Process 
  769.       CONTENTS 
  770.  
  771.  
  772. ΓòÉΓòÉΓòÉ 6.5. The SMART Viewer ΓòÉΓòÉΓòÉ
  773.  
  774. The SMART Viewer 
  775.  
  776.   The SMART Viewer provides a context sensitive on-line help to the SMART 
  777. Migration knowledge base.  By providing a topic name, you can display 
  778. information regarding the migration of the specified keyword.  The display 
  779. windows that are available in this utility are "Topic", "Template", 
  780. "Prototype",  "Example", and "References". An additional window "History" 
  781. provides a list of all topics accessed in the current session. 
  782.  
  783.   The SMART Viewer is invoked from The SMART Editor through the supplied Rexx 
  784. Macro "SMVIEWER.REX".  Simply mouse click on a Source Platform keyword and 
  785. invoke the Rexx Macro with an assigned hot-key.  If you are using an editor 
  786. other than The SMART Editor, you will want to create a macro or other linking 
  787. function to spawn SMART Viewer with topic names. 
  788.  
  789.   The SMART Viewer communicates externally through the proxy process 
  790. "SMARTVUE.EXE", which eliminates starting a new instance each time a request 
  791. for a new topic is desired. 
  792.  
  793.   SMART View contains a search panel which allows you to enter a desired topic 
  794. (keyword) name for viewing. 
  795.  
  796.   Selected text from the "Template", "Prototype", and "Example" window displays 
  797. can be copied to the clipboard buffer providing "cut" and "paste" programming 
  798. capability from the migration data base to your editor. 
  799.  
  800.   Additional functionality for this utility of SMART is explained in the SMART 
  801. Viewer on-line help facility. 
  802.  
  803.       CONTINUE - The SMART Resource Translator 
  804.       BACK - Completing The Migration 
  805.       CONTENTS 
  806.  
  807.  
  808. ΓòÉΓòÉΓòÉ 6.6. The SMART Resource Translator ΓòÉΓòÉΓòÉ
  809.  
  810. The SMART Resource Translator 
  811.  
  812. (It is necessary to use this utility only when migrating from Windows to OS/2. 
  813. Resources do not require translating when migrating from one version of OS/2 to 
  814. another.) 
  815.  
  816.   The SMART Windows to OS/2 Resource Conversion utility (SMARTRC.EXE) provides 
  817. source-to-source conversion of Windows resource definition files to OS/2 
  818. resource definition files.  Support is provided for converting the following 
  819. resource definition statements: 
  820.  
  821.        - ACCELERATORS 
  822.        - AUTO3CHECKSTATE 
  823.        - AUTOCHECKSTATE 
  824.        - AUTORADIOBUTTON 
  825.        - BITMAP 
  826.        - CAPTION 
  827.        - CHECKBOX 
  828.        - CLASS 
  829.        - COMBOBOX 
  830.        - CONTROL 
  831.        - CTEXT 
  832.        - CURSOR 
  833.        - DEFPUSHBUTTON 
  834.        - DIALOG 
  835.        - EDITTEXT 
  836.        - FONT 
  837.        - GROUPBOX 
  838.        - ICON 
  839.        - LISTBOX 
  840.        - LTEXT 
  841.        - MENU 
  842.        - MENUITEM 
  843.        - POPUP 
  844.        - PUSHBUTTON 
  845.        - RADIOBUTTON 
  846.        - RCDATA 
  847.        - RTEXT 
  848.        - SCROLLBAR 
  849.        - SEPARATOR 
  850.        - STATE3 
  851.        - STRINGTABLE 
  852.        - STYLE 
  853.        - USERBUTTON 
  854.  
  855.  SMARTRC also recognizes and processes the following preprocessor directives: 
  856.  
  857.        - #define 
  858.        - #elseif 
  859.        - #else 
  860.        - #endif 
  861.        - #if 
  862.        - #ifdef 
  863.        - #ifndef 
  864.        - #include 
  865.        - #undef 
  866.        - rcinclude 
  867.  
  868.  Additional functionality includes: 
  869.  
  870.           Automatic reformatting of all Windows resource definition statements 
  871.       to the equivalent OS/2 format. 
  872.           Automatic generation of alternate accelerator key sequences. 
  873.           Automatic reformatting of strings contained in RCDATA to produce 
  874.       equivalent binary representation in the RES file. 
  875.           Automatic conversion of mnemonic characters. 
  876.           Automatic scaling and recalculation of OS/2 dialog units from 
  877.       Windows dialog units. 
  878.           Automatic remapping of Windows dialog control styles to OS/2 dialog 
  879.       control styles. 
  880.           Automatic remapping of common dialog  control identifiers to 
  881.       equivalent OS/2 common dialog control identifiers. 
  882.           Automatic detection of named-resources and generation of header file 
  883.       to assign integer identifiers. 
  884.           Optional dialog font mapping from Windows font name and point size 
  885.       to OS/2 font name and point size. 
  886.           Code page conversion of text strings from Windows code page to OS/2 
  887.       code page. 
  888.  
  889.    The general philosophy of converting resource definition statements is that 
  890.  SMARTRC will attempt to convert everything and anything that it understands. 
  891.  For those statements which do not have an equivalent statement in OS/2 SMARTRC 
  892.  will identify the file and line number on which the statement occurs.  In 
  893.  addition, SMARTRC will identify any conversion which may result in slightly 
  894.  different functionality in OS/2.  It is up to the developer to decide how to 
  895.  proceed with any statement in error. 
  896.  
  897.    If SMARTRC detects named-resources, it will generate an include file with a 
  898.  .HHH extension containing integer definitions for those resources.  The user 
  899.  either needs to rename this .HHH file and include it in the top .RC file or 
  900.  copy its contents into an existing .H file that is already included.  It is 
  901.  also a good practice for the user to start at the top-most .RC file when 
  902.  migrating so just one .HHH file will be created and all of the generated ID 
  903.  numbers will be sequential. 
  904.  
  905.    SMARTRC is a utility that can be executed from SMART through the interface 
  906.  dialog panel associated with "Translate Resources..." under the "Resources" 
  907.  menu item or can be run from a command line or embedded in a batch command 
  908.  file.  If the Resource Translator encounters a problem during the conversion 
  909.  process, it will output information, warning or error messages.  For a 
  910.  detailed explanation of these messages, select the "Help, Help Contents" menu 
  911.  item in the SMART application, then go to "Utility Processes, Resource 
  912.  Translator Topics, Resource Translator Messages". 
  913.  
  914.    Although SMARTRC contains many run time options, simply specifying the 
  915.  resource filename without options will process with the system default 
  916.  parameters. 
  917.  
  918.       CONTINUE - Graphical Resource Conversion 
  919.       BACK - The SMART Viewer 
  920.       CONTENTS 
  921.  
  922.  
  923. ΓòÉΓòÉΓòÉ 6.7. Win Help Translation ΓòÉΓòÉΓòÉ
  924.  
  925. Win Help Translation 
  926.  
  927. (It is necessary to use this utility only when migrating from Windows to OS/2. 
  928. Help files do not require translating when migrating from one version of OS/2 
  929. to another.) 
  930.  
  931.   The SMART Windows to OS/2 Help Translator Conversion utility (SMARTHLP.EXE) 
  932. provides conversion of Windows help files to OS/2 help files.  This utility can 
  933. be executed from SMART through the interface dialog panel associated with 
  934. "Translate Win Help..." under the "Resources" menu item or can be run from a 
  935. command line or embedded in a batch command file. 
  936.  
  937.  Follow these steps to convert a Windows RTF (Rich Text Format) file to an OS/2 
  938. help file. 
  939.  
  940.    1. Create an HPJ file that contains the name of the RTF file to be converted 
  941.       along with any bitmap names that are needed.  A sample HPJ file is 
  942.       located in ..SMARTAUX\SAMPLE.HPJ. 
  943.  
  944.    2. To access the the Win Help Translator dialog panel, choose "Resources" 
  945.       from the SMART main dialog panel.  From the Resources pulldown choose 
  946.       "Translate Win Help". 
  947.  
  948.    3. On the Win Help Translator dialog panel, enter the name (including path) 
  949.       of the HPJ file in the "Input Filename" field. 
  950.  
  951.    4. Choose the rest of the options as they apply.  Generally, most of the 
  952.       options will be needed. 
  953.  
  954.    5. If the output will be used by an application, choose "Output .HLP file". 
  955.       If the output will be independent, like a "users' reference", choose 
  956.       "Output .INF file".  To view the output, create an .INF file and use the 
  957.       VIEW command (in OS/2). 
  958.  
  959.    6. Another useful option is "Send Error file to Editor".  Then, errors can 
  960.       be viewed. 
  961.  
  962.    7. When all options have been chosen, press "ok". 
  963.  
  964.    8. SMART does not display a status on the conversion process for a HELP 
  965.       document.  If the "Send Error File to Editor" option is chosen, then the 
  966.       process will be complete when the error file is displayed.  Otherwise, 
  967.       watch the OS/2 window in the backgound to ensure that the Help conversion 
  968.       process is complete. 
  969.  
  970.    9. Output from the Help conversion will depend on the options chosen.  If 
  971.       nothing was entered in the "Output Filename" the file will be written to 
  972.       the same directory as the input file. 
  973.  
  974.   10. Unless the "Convert to IPF Only" option is chosen, the IPF file produced 
  975.       by SMART will automatically be sent to the IPF compiler.  In that case, 
  976.       an INF or HLP file will be produced (depending on the option chosen).  If 
  977.       the "Convert to IPF Only" option IS chosen, only the IPF file will be 
  978.       produced and will not be compiled. 
  979.  
  980.   Note:  Error messages are explained in the online help.  To view the error 
  981.  message explanations, choose HELP from the Win Help Translator dialog panel. 
  982.  Then choose "Win Help Translator Topics".  After that choose "Win Help 
  983.  Translator Messages". 
  984.  
  985.  Please note that the IPF compiler (IPFC.EXE) is required for SMART Win Help 
  986.  translation. IPF (Information Processing Facility) is available from the IBM 
  987.  Developers Toolkit. 
  988.  
  989.  WIN HELP TRANSLATION LIMITATIONS 
  990.  
  991.  The .RTF format can specify a more general document than the IPF's tag 
  992.  language.  Because of this, some word-processing functionality available with 
  993.  Windows help files cannot be translated to the PM IPF system.  The following 
  994.  are the word processing functionalities that cannot be supported: 
  995.  
  996.     Headers and Footers are not supported and will be ignored. 
  997.  
  998.     Metafiles and Macintosh pictures are not supported and will be ignored. 
  999.  You may convert these pictures to bitmaps rather than use these unsupported 
  1000.  formats. 
  1001.  
  1002.     Scaling and cropping of pictures are not supported and are ignored. 
  1003.  
  1004.     Outline, shadow, small-cap and all-cap character attributes are not 
  1005.  supported and are ignored. 
  1006.  
  1007.     Revision marking, tables, side-by-side paragraphs, centered paragraphs, 
  1008.  right-justified paragraphs, paragraph borders, and paragraph leaders are not 
  1009.  supported and are ignored. 
  1010.  
  1011.     Decimal, right, and center tabs are not supported and are ignored. 
  1012.  
  1013.     Margins, paragraph indentations, and tabs are approximated to the nearest 
  1014.  character width. 
  1015.  
  1016.     Line spacing before, within, and after paragraphs is approximated to the 
  1017.  nearest system font character height. 
  1018.  
  1019.     Text does not flow around left or right-margin images, but follows 
  1020.  immediately below the image. 
  1021.  
  1022.     Monochrome images appear in black and white instead of the text foreground 
  1023.  and background colors. 
  1024.  
  1025.     Character attributes of bold, underline and italics work correctly in all 
  1026.  combinations, except for all three together.  It produces red text. 
  1027.  
  1028.     A maximum of 64KB of keys information can be provided. 
  1029.  
  1030.     There are cosmetic differences in the way that hypertext links are 
  1031.  displayed on the screen and in the mouse and keyboard interfaces to those 
  1032.  links. 
  1033.  
  1034.       CONTINUE - Graphical Resource Conversion 
  1035.       BACK - The SMART Resource Translator 
  1036.       CONTENTS 
  1037.  
  1038.  
  1039. ΓòÉΓòÉΓòÉ 6.8. Graphical Resource Conversion ΓòÉΓòÉΓòÉ
  1040.  
  1041. Graphical Resource Conversion 
  1042.  
  1043.   (It is necessary to use this utility only when migrating from Windows to 
  1044. OS/2.  Resource files do not require translating when migrating from one 
  1045. version of OS/2 to another.) 
  1046.  
  1047.   The SMART Windows to OS/2 Graphical Resource Conversion utility 
  1048. (SMARTCVT.EXE) provides binary conversion of Windows icon, cursor, and bitmap 
  1049. files to OS/2  pointer files and bitmap files, respectively. 
  1050.  
  1051.   Both icon and cursor files are referred to as pointer files in OS/2.  The 
  1052. graphical format of Windows icons and cursors is significantly different from 
  1053. OS/2 pointer files. 
  1054.  
  1055.   SMARTCVT is a utility that can be executed from SMART through the interface 
  1056. dialog panel associated with "Convert Graphical Resources..." under the 
  1057. "Resources" menu item or can be run from a command line or embedded in a batch 
  1058. command file.  If the Graphical Resource Converter encounters a problem during 
  1059. the conversion process, it will output information, warning or error messages. 
  1060. For a detailed explanation of these messages, select the "Help, Help Contents" 
  1061. menu item in the SMART application, then go to "Utility Processes, Graphical 
  1062. Resource Converter Topics, Graphical Resource Converter Messages". 
  1063.  
  1064.   The summary information output by SMARTCVT at the completion of file 
  1065. conversion recaps the entire conversion process.  Following is an example of 
  1066. the output contained in the summary information: 
  1067.  
  1068.   Files Processed:   10
  1069.   Files Converted:   10
  1070.   Warnings:    0  Errors:    0
  1071.  
  1072.       CONTINUE - The SMART Editor Development Tool 
  1073.       BACK - The SMART Win Help Translator 
  1074.       CONTENTS 
  1075.  
  1076.  
  1077. ΓòÉΓòÉΓòÉ 6.9. The SMART Editor Development Tool ΓòÉΓòÉΓòÉ
  1078.  
  1079. The SMART Editor Development Tool 
  1080.  
  1081.   The SMART Editor is a feature rich programming development tool combining 
  1082. hyperlink source code access, a fully functional editor, and many file 
  1083. manipulation utility functions. 
  1084.  
  1085.   Features: 
  1086.  
  1087.          Build hyperlinks to key elements of your source code. 
  1088.          REXX Macro interface. 
  1089.          Full IBM Workframe interface. 
  1090.          Spawn Compiles directly from The SMART Editor and hyperlink to 
  1091.       errors. 
  1092.          Context sensitivity to all IBM development help files (if installed). 
  1093.          Edit with multiple windows, any size files. 
  1094.          Create functional call tree and other documentation display - all 
  1095.       hyperlink sensitive. 
  1096.          Unsurpassed methods for navigating directories, drives and source 
  1097.       code. 
  1098.          Hyperlink capabilities make learning new code a breeze. 
  1099.          Print SMART analysis and source code with format from within The 
  1100.       SMART Editor. 
  1101.          Interface with SMART provides automatic hyperlink to all points of 
  1102.       change. 
  1103.  
  1104.    Please refer to The SMART Editor Technical Manual for full explanation 
  1105.  regarding the powerful functionality available with this tool. 
  1106.  
  1107.       CONTINUE - Chapter 4 - Techniques 
  1108.       BACK - Graphical Resource Conversion 
  1109.       CONTENTS 
  1110.  
  1111.  
  1112. ΓòÉΓòÉΓòÉ 7. Chapter 4 - Techniques ΓòÉΓòÉΓòÉ
  1113.  
  1114. Chapter 4 - Techniques 
  1115.  
  1116.         Preparing Your Source Code 
  1117.         Reading the Analysis Display/Report 
  1118.         Interpreting the Analysis 
  1119.         Use of Common Functions 
  1120.         Source Migration Format Considerations 
  1121.         File Extension Mapping 
  1122.         Source Migration Comment Code Removal 
  1123.         Increased Productivity with The SMART Editor 
  1124.  
  1125.       CONTINUE - Preparing Your Source Code 
  1126.       BACK - The SMART Editor Development Tool 
  1127.       CONTENTS 
  1128.  
  1129.  
  1130. ΓòÉΓòÉΓòÉ 7.1. Preparing Your Source Code ΓòÉΓòÉΓòÉ
  1131.  
  1132. Preparing Your Source Code 
  1133.  
  1134.   Planning a strategy for the analysis and/or migration of your source code 
  1135. will greatly pay back in the long run. 
  1136.  
  1137.   It is essential that your original source code be backed up to insure that an 
  1138. inadvertently mis-chosen option, especially in the migration process, does not 
  1139. prevent you from restoring to your original code state. 
  1140.  
  1141.   Both the Analysis and Migration processes of SMART should not be considered 
  1142. one-shot processes.  You may wish to run the Analysis a number of times, with 
  1143. global code changes to change the outcome.  Likewise, you may find that you 
  1144. want to make global changes to your code fixing a recurring hit to reduce the 
  1145. migration effort before you even apply SMART. 
  1146.  
  1147.   For example, after a review of the initial analysis run, changing a parameter 
  1148. type through your code may significantly reduce the Effort reported in the 
  1149. analysis.  After looking at the reported keyword hits in your code, you may 
  1150. decide to write a number of common functions that replace the source platform 
  1151. API calls and make global replacements for these calls to your new functions. 
  1152. You can rerun the Analysis Process and see the resulting effort changes. 
  1153. Likewise for other changes that may involve macro #defines, or typedefs. 
  1154.  
  1155.   You may be surprised at the results of these preprocessing changes and how 
  1156. they might reduce your porting effort. 
  1157.  
  1158.   Likewise, you may wish to rerun the Migration Process after analyzing the 
  1159. resulting initial results.  It may be that you need different formatting 
  1160. options in the Migration Process, or you find that you can make global changes 
  1161. to a syntax widely used to eliminate repetitive reporting from SMART of this 
  1162. migration hit. 
  1163.  
  1164.   Essentially, anything that you can do to your code to simplify that migration 
  1165. process will greatly reduce the whole porting effort. 
  1166.  
  1167.       CONTINUE - Reading the Summary Reports 
  1168.       BACK - Chapter 4 - Techniques 
  1169.       CONTENTS 
  1170.  
  1171.  
  1172. ΓòÉΓòÉΓòÉ 7.2. Reading the Summary Reports ΓòÉΓòÉΓòÉ
  1173.  
  1174. Reading the Summary Reports 
  1175.  
  1176. For each analysis that you run, a summary report files is created and can be 
  1177. printed using the SMART 'Print Analysis Report' process. 
  1178.  
  1179. A cover page preceeds the summary reports when they are printed with 
  1180. information regarding the date and time of the report along with the user 
  1181. supplied report title. 
  1182.  
  1183. A summary report is created with the standard Migration Analysis process, and 
  1184. the Resource Translation Analysis (if the Windows migration tables are 
  1185. selected). 
  1186.  
  1187.  The report lines for the cover page and their description follows: 
  1188.  
  1189.        SMART Source Code Migration Analysis Report - Cover Report Heading. 
  1190.  
  1191.        [Next one to three lines] - User supplied report title (first line 
  1192.       appears on each page of the report). 
  1193.  
  1194.        Prepared: [Date - Time] - Date stamp of the summary report. 
  1195.  
  1196.        Printed: [Date - Time] - Date stamp of the report printing. 
  1197.  
  1198.        Summary: [Filename] - Filename(s) of the Summary report files. 
  1199.  
  1200.        Report: [Filename] - Filename(s) of the Primary Analysis report file. 
  1201.  
  1202.   The report lines for the Migration Analysis Report Summary and their 
  1203.  description follows: 
  1204.  
  1205.        Total File Count - Number of files processed in the Analysis. 
  1206.  
  1207.        Total File Size (Bytes) - Total size of files processed in the Analysis. 
  1208.  
  1209.        Total Source Lines - Total number of lines processed. 
  1210.  
  1211.        Total Code Lines - Total number of lines processed excluding comment 
  1212.       lines and null (skip) lines. 
  1213.  
  1214.        Total Category xxx Hits - Total number of keyword encounters by category 
  1215.       type. 
  1216.  
  1217.        Total Migration Hits - Total number of all keyword encounters. 
  1218.  
  1219.        Total Cat 000 and 010 Hits Auto Migrated - Total number of keyword 
  1220.       encounters that will be automatically migrated using SMART. 
  1221.  
  1222.        Total Hits MiCL Processed - Total number of keyword encounters that will 
  1223.       be migrated using MiCL commands in either the primary Migration Database 
  1224.       or a UDMD. 
  1225.  
  1226.        Total Hits Processed with UDMD - Total number of keyword encounters were 
  1227.       encountered from a UDMD. 
  1228.  
  1229.        Total Hits Excluded - Total number of keyword encounters were excluded 
  1230.       from processing based on a user supplied exclude list. 
  1231.  
  1232.        Total Migration Keyword Instances - Total number of keyword encounters 
  1233.       that represented different keywords. 
  1234.  
  1235.        **NOTE** - The following effort estimates and productivity gains are 
  1236.       calculated from a number of generalized factors and assumptions.  The 
  1237.       actual effort that you may encounter will depend upon your individual 
  1238.       experience and productivity, in addition to unique difficulties that may 
  1239.       be encountered in your coding.  Please use these values as a comparative 
  1240.       guideline only. 
  1241.  
  1242.        Estimated Migration Effort Without SMART - An estimation of the total 
  1243.       number of migration hours required to migrate this project without any 
  1244.       use of SMART. 
  1245.  
  1246.        Savings from SMART Base Migration - An estimation of the total number of 
  1247.       migration hours saved by the base use of SMART without any productivity 
  1248.       gains from automatic migration. 
  1249.  
  1250.        Savings from Cat 010 Auto Migrate - An estimation of the total number of 
  1251.       migration hours saved by the automatic migration from SMART. 
  1252.  
  1253.        Savings from Keyword Exclusions - An estimation of the total number of 
  1254.       migration hours not required due to exclusion from the user specified 
  1255.       keyword exclude list. 
  1256.  
  1257.        ** Net Migration Effort ** - An estimation of the total number of 
  1258.       migration hours remaining to complete the project after processing with 
  1259.       SMART. 
  1260.  
  1261.        Percent Effort Reduction using SMART - A calculation of the net 
  1262.       estimated migration effort as a percentage of the total estimated effort 
  1263.       without the use of SMART. 
  1264.  
  1265.   The report lines for the Resource Translation Analysis Report Summary 
  1266.  (provided with Windows migration Analysis only) and their description follows: 
  1267.  
  1268.        Total Resource File Count - Number of files processed in the Resource 
  1269.       Analysis. 
  1270.  
  1271.        Total Resource File Size (Bytes) - Size of files processed in the 
  1272.       Resource Analysis. 
  1273.  
  1274.        Total Dialog Templates - Number of Dialogs encountered in the Analysis. 
  1275.  
  1276.        Total Dialog Code Lines - Number of lines of code for the Dialogs. 
  1277.  
  1278.        Ave Code Lines Per Dialog - Indicates the code lines size of the average 
  1279.       dialog. 
  1280.  
  1281.        Total Menu Template Code Lines - Number of coding lines in the Menus. 
  1282.  
  1283.        Total StringTable Code Lines - Number of coding lines in the String 
  1284.       Tables. 
  1285.  
  1286.        Total Accelerator Table Code Lines - Number of coding lines in the 
  1287.       Accelerator Tables. 
  1288.  
  1289.        **NOTE** - The following effort estimates and productivity gains are 
  1290.       calculated from a number of generalized factors and assumptions.  The 
  1291.       actual effort that you may encounter will depend upon your individual 
  1292.       experience and productivity, in addition to unique difficulties that may 
  1293.       be encountered in your coding.  Please use these values as a comparative 
  1294.       guideline only. 
  1295.  
  1296.        Estimated Translation Effort Without SMART - Estimated migration hours 
  1297.       to convert the resource files without the use of SMART. 
  1298.  
  1299.        Savings from SMART Resource Translator - Estimated migration hours saved 
  1300.       in the effort to convert the resource files with the use of SMART 
  1301.       automation. 
  1302.  
  1303.        ** Net Translation Effort ** - An estimation of the total number of 
  1304.       migration hours required to translate the resource files with SMART. 
  1305.  
  1306.        Percent Effort Reduction using SMART - A calculation of the net 
  1307.       estimated translation effort as a percentage of the total estimated 
  1308.       effort without the use of SMART. 
  1309.  
  1310.       CONTINUE - Reading the Analysis Display/Report 
  1311.       BACK - Preparing Your Source Code 
  1312.       CONTENTS 
  1313.  
  1314.  
  1315. ΓòÉΓòÉΓòÉ 7.3. Reading the Analysis Display/Report ΓòÉΓòÉΓòÉ
  1316.  
  1317. Reading the Analysis Display/Report 
  1318.  
  1319.   Each keyword is categorized by the level of difficulty required to migrate to 
  1320. the target platform.  These categories can also be viewed as the amount of 
  1321. programmer interaction and expertise required for the migration. The currently 
  1322. defined categories and their description are as follows: 
  1323.  
  1324.         000  Informational only - An exact match of the keyword exists in the 
  1325.       target platform but there is change in the size of type. (e.g. short to a 
  1326.       long). 
  1327.  
  1328.         010  Literal replacement - An equivalent definition exists in the 
  1329.       target platform but a literal change in the keyword is required (e.g., 
  1330.       LPSTR to PSZ). 
  1331.  
  1332.         020  Replacement with parameter changes - Equivalent functionality 
  1333.       exists in the target platform but parameters or fields of a structure 
  1334.       differ slightly from the source platform definition (e.g., SetWindowPos 
  1335.       to WinSetWindowPos).  Also  included are parameters that are not 
  1336.       applicable or required on the target platform (e.g., MakeProcInstance). 
  1337.  
  1338.         030  Change with more / less API calls - Equivalent functionality 
  1339.       exists in the target platform but it must be implemented with  more, or 
  1340.       sometimes less, function calls (e.g., DlgDirList).  Also included are 
  1341.       items which map to one of several choices depending upon the type of 
  1342.       parameter used (e.g., GetObject). 
  1343.  
  1344.         040  Logic changes required - Similar functionality exists in the 
  1345.       target platform but the logic required to emulate the functionality must 
  1346.       be reworked (e.g., CreatePatternBrush). 
  1347.  
  1348.         050  Functionality does not exist - There is no means provided to 
  1349.       perform the same functionality in the target platform (e.g., 
  1350.       GetKeynameText).  Workaround coding must be implemented, where possible. 
  1351.  
  1352.         999  Dictionary entry not defined - The database does not currently 
  1353.       have a complete description for the migration of the keyword. 
  1354.  
  1355.    Throughout the analysis report there are several column and section 
  1356.  headings used to display counts of various pieces of information. 
  1357.  
  1358.    These column and section headings are defined as follows: 
  1359.  
  1360.  File Detail Report: 
  1361.  
  1362.        PATH/FILENAME - Full path specification of the file(s) 
  1363.        SIZE - File size in bytes 
  1364.        LINES - Number of lines in the file 
  1365.        CODE - Number of lines containing code in the file 
  1366.        HITS - Number of times a keyword was identified 
  1367.        PCT HITS - Percentage of hits per line of code (i.e., HITS / CODE) 
  1368.        INSTS - Number of unique keywords that were identified 
  1369.        PCT INST - Percentage of unique keywords per line of code (i.e., INSTS / 
  1370.       CODE) 
  1371.        EFFORT - Calculation of the relative amount of work required to migrate 
  1372.       the code in the file 
  1373.        CAT xxx - Number of hits in each category 
  1374.  
  1375.  Keyword Detail Report: 
  1376.  
  1377.        CATEGORIES - Breakdown by category of the keywords found 
  1378.        TYPES - Breakdown by type of the keywords found (function calls, 
  1379.       messages, symbol definitions, and typedef statements) 
  1380.        AREAS - Breakdown by functional area of the keywords found 
  1381.        KEYWORDS - Breakdown by individual keyword.  Ordered by category and 
  1382.       from the most number of occurrences to the least number of occurrences. 
  1383.        HITS - Number of times a keyword for the specified item was identified. 
  1384.        PCT HITS - Percentage of all hits identified (i.e., HITS / section total 
  1385.       HITS) 
  1386.        FILES - Number of files that a keyword for the specified item was found 
  1387.        INSTS - Number of unique keywords that were identified for the specified 
  1388.       item 
  1389.        PCT INST - Percentage of all unique keywords identified (i.e., INSTS / 
  1390.       section total INSTS) 
  1391.        EFFORT - Calculation of the relative amount of work required to migrate 
  1392.       the code for the specified item 
  1393.  
  1394.       CONTINUE - Interpreting the Analysis 
  1395.       BACK - Reading the Summary Reports 
  1396.       CONTENTS 
  1397.  
  1398.  
  1399. ΓòÉΓòÉΓòÉ 7.4. Interpreting the Analysis ΓòÉΓòÉΓòÉ
  1400.  
  1401. Interpreting the Analysis 
  1402.  
  1403.   The analysis portion of SMART actually generates two related reports.  Each 
  1404. report presents the detailed analysis from a different perspective.  The two 
  1405. reports together should give you a thorough understanding of the amount of code 
  1406. that requires migration and the amount of effort that will be involved.  A 
  1407. brief overview of the contents of the analysis report is relevant here before 
  1408. discussing how to interpret the data contained in the  report. 
  1409.  
  1410.   The file detail report presents a detailed analysis of each source file. This 
  1411. includes all of the items previously defined for the file detail report. 
  1412.  
  1413.   The keyword detail report presents a more thorough breakdown of the keywords 
  1414. identified during the analysis.  The analysis data is broken down four 
  1415. different ways.  The first is a breakdown by category showing the counts of the 
  1416. keywords as identified by their respective category. The second is a breakdown 
  1417. by the types of the keywords.  The third is a breakdown of the identified 
  1418. keywords by the various functional areas that a keyword is classified.  The 
  1419. fourth is a breakdown by the individual keywords.  This last breakdown shows 
  1420. each and every keyword that was identified and the number of occurrences. 
  1421.  
  1422.   The analysis report contains a lot of valuable information about your source 
  1423. code.  Once you understand how to interpret the data you will be able to more 
  1424. accurately size and evaluate the migration effort.  In addition you can rerun 
  1425. the analysis program on your code during the migration process to give you 
  1426. accurate progress statistics.  We begin the interpretation with the file detail 
  1427. portion of the analysis report. 
  1428.  
  1429.   The first thing to be learned from the file detail report is simply how many 
  1430. lines of code are in each file and in the entire the application. This forms 
  1431. the basis for determining the relative distribution of the keywords in the 
  1432. code. 
  1433.  
  1434.   The total number of hits, shown at the bottom of this part of the report, 
  1435. tells you how many changes must be made to the code.  The percentage of hits 
  1436. times the number of lines of code tells you how many lines of code must be 
  1437. changed.  Don't get overly excited at this  point if this number is rather 
  1438. large.  Until we examine the keyword detail report you don't know how many of 
  1439. these will be automatically migrated by  SMART. 
  1440.  
  1441.   Next look at the total number of instances.  This is the number of unique 
  1442. keywords that must be migrated.  What this really tells you is  approximately 
  1443. how many individual keywords the programmer(s) will have to be familiar with in 
  1444. order to make various decisions during the migration. Since many migration 
  1445. issues and changes related to a specific keyword are the same or similar for 
  1446. all occurrences of that keyword the actual effort is reduced to deciding what 
  1447. needs to be changed and simply repeating the change for each occurrence. 
  1448. Again, many of these changes may be  automatically migrated by SMART. 
  1449.  
  1450.   At this point the effort number that is shown for each file has very little 
  1451. significance unless you have migrated source before.  The effort calculation is 
  1452. based on the relative difficulty of  migrating a keyword -- category 030 items 
  1453. are more difficult to migrate than category 020 items.  Since the actual time 
  1454. to migrate a section of code also depends on the experience and knowledge of 
  1455. the programmer and on the tools being used the amount of actual time that the 
  1456. effort number translates to will be different for each person. 
  1457.  
  1458.   In order to translate the effort number to actual time it is necessary to 
  1459. migrate several source files containing a mix of keywords in each of the 
  1460. difficulty categories.  Using the actual time and the effort calculations for 
  1461. those migrated files you get an approximate time value for each effort unit. 
  1462.  
  1463.   The last portion of the file detail report is the breakdown of the hits by 
  1464. their respective categories.  These numbers can assist you in assigning groups 
  1465. of files to programmers with different levels of expertise.  A file that is 
  1466. mostly composed of category 020 items can be assigned to someone with little 
  1467. experience on the target platform since most of the keywords are relatively 
  1468. simply to migrate. 
  1469.  
  1470.   In fact, the changes required for almost all of the category 020 items is 
  1471. exactly a one-to-one change as detailed in the migration database.  Files that 
  1472. contain category 040 and 050 items can be assigned to your more experienced 
  1473. programmers since these items require a more in-depth knowledge of what the 
  1474. code is attempting to do on the source platform and how the logic can be 
  1475. restructured to implement the same functionality on the target platform. 
  1476.  
  1477.   In general, the file detail section provides a quantitative analysis of the 
  1478. source code showing how much must be changed.  On the other hand, the keyword 
  1479. detail section provides more of a qualitative analysis of those changes.  In 
  1480. the keyword detail report we get to the real nitty-gritty of what is contained 
  1481. in the source code. 
  1482.  
  1483.   The first section, CATEGORIES, presents the first indication of how the 
  1484. migration breaks down by difficulty.  Collectively the six columns of data can 
  1485. tell you a lot about how much effort will be involved and  where that effort 
  1486. will be concentrated. 
  1487.  
  1488.   The HITS, PCT HITS, and FILES columns tell you the volume of physical changes 
  1489. that have to be made. Even minor changes can require a great deal of time if 
  1490. the item occurs thousands of times or exists in hundreds of files.  Time is 
  1491. required to open files, locate and enter changes, and save the files. 
  1492.  
  1493.   Review the INSTS and PCT INSTS columns to identify the number of unique items 
  1494. that have to be migrated at each difficulty category.  There are two things 
  1495. that may be learned from this information.  First, while there may be a large 
  1496. number of HITS in a particular category it may be that they are isolated to a 
  1497. few particular keywords.  This would actually indicate that less work is 
  1498. required compared to the situation where a large number of instances occur with 
  1499. a large number of hits. 
  1500.  
  1501.   When we look at the KEYWORDS section it will be more evident if that is the 
  1502. case, but this section can give use a good indication of where the effort is 
  1503. concentrated.  Second, look at the distribution of the hits and instances among 
  1504. the various categories.  Most likely the majority of the hits as well as the 
  1505. instances are in categories 020 or less. The desired trend is for the numbers 
  1506. to decrease significantly from  category 020 to category 050.  Obviously the 
  1507. fewer category 040 and 050 items the less difficult the migration.  The last 
  1508. column, EFFORT, is a good indicator of where you will spend most of the time 
  1509. during the migration. Depending on the number of instances of category 030 and 
  1510. 040 items it is possible that the effort for these categories can be greatly 
  1511. reduced. 
  1512.  
  1513.   The next section, TYPES, is mostly for information purposes only. A couple of 
  1514. useful things about your migration effort can still be learned from it. 
  1515. Function and message items typically require the most effort since  program 
  1516. logic can be affected.  Symbol items require the least effort since most of the 
  1517. time it requires a simple change to a bit flag or a #define statement.  The 
  1518. typedef items typically require modifications  to structure field references 
  1519. and aren't significantly difficult items. 
  1520.  
  1521.   The next section, AREAS, is again mostly for information purposes only.  This 
  1522. section can help in staffing the migration and assigning programmers to work on 
  1523. individual areas of the project.  By analyzing the various functional areas 
  1524. that require migration and the numbers associated with each you can decide what 
  1525. expertise on both the source and target platform is required.  For example, if 
  1526. large portions of the migration are in the bitmap, color-palette, and 
  1527. drawing-tool areas you will want to make sure you assign a programmer with 
  1528. graphics expertise to the project. 
  1529.  
  1530.   The last section, KEYWORDS, shows exactly what keywords were identified in 
  1531. the source and their frequency of occurrence.  Since the keywords are organized 
  1532. by category and listed in decreasing order of occurrence it is very easy to see 
  1533. what needs to be changed.  It is also here that you can see if you have an even 
  1534. distribution of hits on each keyword or if there are a lot of hits on 
  1535. relatively few keywords. 
  1536.  
  1537.   For example, if you have 800 hits in category 030 but 450 of them are 
  1538. SendMessage and 250 are SelectObject then the amount of effort can be reduced. 
  1539. This is because the programmer will have only to look at these two items, 
  1540. decide the general migration changes to be applied, and make the changes (thus 
  1541. eliminating 700 of the 800 hits). 
  1542.  
  1543.   On the other hand, if the hits are fairly evenly distributed in a category it 
  1544. will require more time since many more decisions on migration changes will have 
  1545. to be performed. This is especially important when looking at the category 040 
  1546. and 050 items since these items may require significant logic changes to the 
  1547. application. 
  1548.  
  1549.   One additional thing to note is the relationship of the  various keywords in 
  1550. a category. If you see several keywords which relate  to the same functionality 
  1551. it may be possible that all of those keywords  will be migrated by a change to 
  1552. a single portion of the code.  For  example, if you encounter a set of mouse 
  1553. related messages in category 040 then all of these will most likely be resolved 
  1554. in the same manner or with a single change to the code. 
  1555.  
  1556.   There are a few items that warrant special consideration when evaluating the 
  1557. SMART analysis report.  The current knowledge-base technology may 
  1558. over-categorize a keyword resulting in a higher relative effort than is 
  1559. actually required.  There are many functions and messages which  have a 
  1560. one-to-many mapping to the target platform.  In these cases the actual 
  1561. migration depends upon the intention of the function or the value of one or 
  1562. more parameters (e.g., a flag set in a variable). 
  1563.  
  1564.   When more than one choice exists for the migration SMART will use the higher 
  1565. category level for the analysis report so as not to significantly underestimate 
  1566. the effort.  For example, the Windows RegisterClass function is categorized as 
  1567. category 040.  If the class uses the default cursor and icon then it actually 
  1568. is a category 020 item.  Yet, if a class specific cursor, icon, or background 
  1569. brush is used it is a category 040 since this would require logic changes. 
  1570. Category 040 would be used by SMART since it would depend on the values in the 
  1571. WNDCLASS structure.  Be aware that you may have some keywords that are 
  1572. overclassified. 
  1573.  
  1574.   One of the suggested techniques to significantly increase the speed of the 
  1575. migration is to use macros or to implement functions for category 030 and 040 
  1576. items that have high hit counts.  This eliminates larger, redundant blocks of 
  1577. migrated code that implement the intended functionality and also localizes the 
  1578. debugging effort to a single function. If this technique is applied to your 
  1579. migration effort then you should take into consideration that the keywords 
  1580. implemented in this manner are actually category 020 items instead of category 
  1581. 030 or 040. 
  1582.  
  1583.       CONTINUE - Use of Common Functions 
  1584.       BACK - Reading the Analysis Display/Report 
  1585.       CONTENTS 
  1586.  
  1587.  
  1588. ΓòÉΓòÉΓòÉ 7.5. Use of Common Functions ΓòÉΓòÉΓòÉ
  1589.  
  1590. Use of Common Functions 
  1591.  
  1592.   Significant improvements in your migration effort may be achieved through the 
  1593. use of common functions.  Common functions refers to the implementation of 
  1594. source platform functions as their equivalent target platform functions.  Since 
  1595. the migration of many keywords involves replacing the existing function call 
  1596. with multiple lines of code, using common functions can reduce the amount of 
  1597. code and coding changes required. 
  1598.  
  1599.   Selecting candidates for common functions is a very subjective process. You 
  1600. must evaluate the analysis report for your application and review the 
  1601. difficulty and hit counts for each of the keywords.  As a general rule a 
  1602. keyword is a candidate if the hit count is at least twenty (20)  and the 
  1603. difficulty category is 030 or higher.  Once a candidate is identified you must 
  1604. review the use of that keyword throughout the application.  If the keyword is 
  1605. used in generally the same context throughout the application then you will 
  1606. probably gain migration speed by implementing the particular function or 
  1607. defining an appropriate macro. 
  1608.  
  1609.   As an example, assume that the analysis report for a Windows application 
  1610. shows that GetMenuString occurs 100 times.  This is a category 030 keyword 
  1611. since the flag may specify the menu item either by command or by position.  If 
  1612. we examine the code and find that all of the calls are requested by command 
  1613. then we could decide to just implement GetMenuString as a macro which sends the 
  1614. MM_QUERYITEMTEXT messages.  On the other hand if we have a mix of requests by 
  1615. both command and position we could decide to implement GetMenuString as a 
  1616. function which sent the appropriate messages based on the specified flag. 
  1617.  
  1618.   It is recommended that you place all common functions into a single, 
  1619. separate source file or library.  Doing so can ease your effort during the 
  1620. debugging phase and allows you to begin abstracting functionality for future 
  1621. migrations. 
  1622.  
  1623.       CONTINUE - Source Migration Format Considerations 
  1624.       BACK - Interpreting the Analysis 
  1625.       CONTENTS 
  1626.  
  1627.  
  1628. ΓòÉΓòÉΓòÉ 7.6. Source Migration Format Considerations ΓòÉΓòÉΓòÉ
  1629.  
  1630. Source Migration Format Considerations 
  1631.  
  1632.   Each Category of the Migration Process offers a popup dialog panel to select 
  1633. the format of the inserted comments in the migrated code.  These options 
  1634. include: Long, short or no comment, template, prototype, example code, restate 
  1635. original code and ignore migration. 
  1636.  
  1637.   It may appear convenient to insert all of the above items in-line with your 
  1638. source code. However, in general, the more you put in your code the more 
  1639. difficult it is to read.  It is better to insert less in your code and use the 
  1640. SMART Viewer to display information pertaining to the keywords as necessary. 
  1641. You also have the option to clip and paste from the SMART Viewer display panels 
  1642. to your code. 
  1643.  
  1644.   After you have reviewed the Analysis report and made any necessary code 
  1645. changes, you may wish to ignore the Category 000 hits. 
  1646.  
  1647.   Restatement of the original code has been offered as an option particularly 
  1648. for the Windows to OS/2 migration.  This uncommented restatement allows you to 
  1649. rerun the Analysis Process during your process of completing the migration to 
  1650. determine the amount of code left to complete.  Simply remove this code 
  1651. restatement as you make the necessary changes. 
  1652.  
  1653.   You may also use this restatement as a starting point for code modification. 
  1654.  
  1655.   In any case it is recommended that you try various options on the sample code 
  1656. or a small set of you source code to determine what works best for you. 
  1657.  
  1658.       CONTINUE - File Extension Mapping 
  1659.       BACK - Use of Common Functions 
  1660.       CONTENTS 
  1661.  
  1662.  
  1663. ΓòÉΓòÉΓòÉ 7.7. File Extension Mappings ΓòÉΓòÉΓòÉ
  1664.  
  1665. File Extension Mapping 
  1666.  
  1667.   File extension mapping allows you to control the name of the generated source 
  1668. file in the Migration process for source migration, the process for commenting 
  1669. out #ifdef code and the process for removing tagged code. 
  1670.  
  1671.   In all cases where SMART generates new source files the files are placed in 
  1672. the same directory as the original, with the file extension changed.  The 
  1673. alternative to this process is to request that the original file be 
  1674. overwritten.  For obvious reasons this is not recommended. 
  1675.  
  1676.   You can control the extension mapping by specifying the map for each file 
  1677. extension encountered in your processing.  The data for this mapping is 
  1678. contained in the test file MAPEXT.DAT in the main SMART directory. 
  1679.  
  1680.   You can maintain this data from the popup dialog selected in the processes 
  1681. that offer extension mapping such as the Migration Process. 
  1682.  
  1683.   The mapping data simply contains the original extension and then the 
  1684. extension for the map. 
  1685.  
  1686.   The mapping data will not accept wildcards, but is explicitly defined.  You 
  1687. will note that several layers of mapping is defined in the default data.  For 
  1688. example ".C" is mapped to ".C__X", and ".C__X" is mapped to ".C__Y".  This 
  1689. allows you to perform multiple mapping processes while saving each set of files 
  1690. in the processes. 
  1691.  
  1692.   Please note that the mapping data is case sensitive.  If your files are in 
  1693. lower case, the mapping data must be specified in lower case. 
  1694.  
  1695.   You will be notified if SMART encounters a file that cannot be mapped, due to 
  1696. missing mapping data, during the process requiring the map. 
  1697.  
  1698.   The SMART Resource Translator accepts wildcards and does not use this mapping 
  1699. data. 
  1700.  
  1701.       CONTINUE - Source Migration Comment Code Removal 
  1702.       BACK - Source Migration Format Considerations 
  1703.       CONTENTS 
  1704.  
  1705.  
  1706. ΓòÉΓòÉΓòÉ 7.8. Source Migration Comment Code Removal ΓòÉΓòÉΓòÉ
  1707.  
  1708. Source Migration Comment Code Removal 
  1709.  
  1710.   You can automatically remove comment tagged code with SMART.  Comment tagged 
  1711. code is defined by having a short unique set of identification characters. 
  1712.  
  1713.   All of the migration insertion code has tags identified by "SM$:".  The 
  1714. dialog selection panel shown above specifies that codes that are used by SMART. 
  1715. Using this panel you can select the commented code that you wish to remove at 
  1716. any point in your migration process. 
  1717.  
  1718.   The four fields entitled "Other Tagged Lines" allows you to remove code that 
  1719. may have been tagged by you for your own identification purposes. 
  1720.  
  1721.   This process also allows you to just remove the tags without removing the 
  1722. code on the lines.  In this case the tags are removed at the end of the line, 
  1723. leaving the remaining code. To fit into this class of tagging, the tags must be 
  1724. at the end of the line and proceeded by a double slash ("//") and a space. 
  1725.  
  1726.   You may wish to explore the functionality of this process with a file form 
  1727. the sample code that has been migrated. 
  1728.  
  1729.       CONTINUE - Increased Productivity with The SMART Editor 
  1730.       BACK - File Extension Mapping 
  1731.       CONTENTS 
  1732.  
  1733.  
  1734. ΓòÉΓòÉΓòÉ 7.9. Increased Productivity with The SMART Editor ΓòÉΓòÉΓòÉ
  1735.  
  1736. Increased Productivity with The SMART Editor 
  1737.  
  1738.   The SMART Editor is provided, and has been specifically designed, to increase 
  1739. your productivity through the speed and ease of source code navigation and the 
  1740. integration of file manipulation\utilities. 
  1741.  
  1742.   The single most unique feature of The SMART Editor is hyperlink access to 
  1743. your source code. Once you have built a hyperlink data base for your code set, 
  1744. you can mouse click to any function definition or popup a list of all 
  1745. references to a function, symbol or other key element of your code. 
  1746.  
  1747.   You can request that this database be created as a result of the SMART 
  1748. Analysis or Migration Process, or you can create the link data base within The 
  1749. SMART Editor application. 
  1750.  
  1751.   In your migration process, if you wish to look at all the places where a 
  1752. function is used, simply double click with the right mouse button on the 
  1753. function in question, and The SMART Editor will create a display of all 
  1754. references. 
  1755.  
  1756.   Since The SMART Editor displays are both hyperlink sensitive and editable, 
  1757. you may double click (left mouse button) on the filename-line number for any of 
  1758. the displayed references and The SMART Editor will immediately open the file at 
  1759. the point of reference. 
  1760.  
  1761.   Another powerful feature of The SMART Editor is the ability to perform 
  1762. multiple file, string searches and provide a hyperlink display file of all 
  1763. strings found for your immediate access. You can use your "List-of-Files" from 
  1764. the SMART Analysis or Migration as the input file specification to this search 
  1765. process. 
  1766.  
  1767.   In addition to the powerful source code access function The SMART Editor 
  1768. allows you to spawn compiles and hyperlink to the point of error. 
  1769.  
  1770.   The SMART Editor has been specifically designed to assist you in productively 
  1771. maintaining your code.  The integration of the features and the powerful 
  1772. navigation functionality will greatly reduce your time and effort in porting 
  1773. your code. 
  1774.  
  1775.       CONTINUE - Chapter 5 - Reference 
  1776.       BACK - Source Migration Comment Code Removal 
  1777.       CONTENTS 
  1778.  
  1779.  
  1780. ΓòÉΓòÉΓòÉ 8. Chapter 5 - Reference ΓòÉΓòÉΓòÉ
  1781.  
  1782. Chapter 5 - Reference 
  1783.  
  1784.         Migration Formats 
  1785.         SMART Files 
  1786.         Specifications and Restrictions 
  1787.         Technical Support 
  1788.  
  1789.       CONTINUE - Migration Formats 
  1790.       BACK - Increased Productivity with The SMART Editor 
  1791.       CONTENTS 
  1792.  
  1793.  
  1794. ΓòÉΓòÉΓòÉ 8.1. Migration Formats ΓòÉΓòÉΓòÉ
  1795.  
  1796. Migrated code formats are user configurable.  A number of options relating to 
  1797. the migrated code are available. 
  1798.  
  1799. The Format References include the following formats: 
  1800.  
  1801.          Original source code (before migration) 
  1802.          Format - 'ifdef' and '/*...*/' comments 
  1803.          Format - 'ifdef' and '//' comments 
  1804.          Format - NO 'ifdef' and '/*...*/' comments 
  1805.          Format - NO 'ifdef' and '//' comments 
  1806.          Format - '//' comments and NO Tags 
  1807.          Format - '//', Short comments and Prototypes 
  1808.          Format - '/*...*/', Long comments, Prototypes and Examples 
  1809.          Format - Source code with migration comments removed 
  1810.  
  1811.       CONTINUE - Original source code (before migration) 
  1812.       BACK - Chapter 5 - Reference 
  1813.       CONTENTS 
  1814.  
  1815.  
  1816. ΓòÉΓòÉΓòÉ 8.1.1. Original source code (before migration) ΓòÉΓòÉΓòÉ
  1817.  
  1818. Original Source Code 
  1819.  
  1820.   /* Open the file with the OF_PARSE flag to obtain the fully qualified
  1821.    * pathname in the OFSTRUCT structure.
  1822.    */
  1823.   wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);
  1824.  
  1825.   _lclose (wFileTemp);
  1826.  
  1827.   LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));
  1828.  
  1829.       CONTINUE - Format - 'ifdef' and '/*...*/' comments 
  1830.       BACK - Migration Formats 
  1831.       CONTENTS 
  1832.  
  1833.  
  1834. ΓòÉΓòÉΓòÉ 8.1.2. Format - 'ifdef' and '/*...*/' comments ΓòÉΓòÉΓòÉ
  1835.  
  1836. Format - 'ifdef' and '/*...*/' comments 
  1837.  
  1838. /* SM$:FO  C:\TEST\TEST.C - 03/28/94 14:25:07                */
  1839.   /* Open the file with the OF_PARSE flag to obtain the fully qualified
  1840.    * pathname in the OFSTRUCT structure.
  1841.    */
  1842. #ifndef OS221
  1843.   wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);/* SM$:O */
  1844. #else
  1845.   wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  /* SM$:M3 */
  1846.   DosOpen (,,,,,,,)                          /* SM$:M3 */
  1847.   DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              /* SM$:M2 */
  1848.   /*                                   SM$:C
  1849.    * OpenFile Cat:030 Type:010 Area:130                  SM$:K
  1850.    * Replace with DosOpen, DosDelete, or DosQueryPathInfo         SM$:S
  1851.    *                                   SM$:C
  1852.    * LPSTR replaced with PSZ - Cat:010 Type:030 Area:990         SM$:1
  1853.    *                                   SM$:C
  1854.    * OF_PARSE Cat:020 Type:030 Area:130                  SM$:K
  1855.    * Use DosQueryPathInfo to replace OpenFile function call        SM$:S
  1856.    */                                 /* SM$:C */
  1857. #endif
  1858.  
  1859. #ifndef OS221
  1860.   _lclose (wFileTemp);                         /* SM$:O */
  1861. #else
  1862.   DosClose (wFileTemp);                        /* SM$:M1 */
  1863.   /*                                   SM$:C
  1864.    * _lclose replaced with DosClose - Cat:010 Type:010 Area:130      SM$:1
  1865.    */                                 /* SM$:C */
  1866. #endif
  1867.  
  1868. #ifndef OS221
  1869.   LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           /* SM$:O */
  1870. #else
  1871.   LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           /* SM$:R */
  1872.   WinLoadString (,,,,);                         /* SM$:M2 */
  1873.   /*                                    SM$:C
  1874.   * LoadString Cat:020 Type:010 Area:060                 SM$:K
  1875.   * Replace with WinLoadString                      SM$:S
  1876.   */                                  /* SM$:C */
  1877. #endif
  1878.  
  1879.       CONTINUE - Format - 'ifdef' and '//' comments 
  1880.       BACK - Original source code (before migration) 
  1881.       Migration Formats 
  1882.       CONTENTS 
  1883.  
  1884.  
  1885. ΓòÉΓòÉΓòÉ 8.1.3. Format - 'ifdef' and '//' comments ΓòÉΓòÉΓòÉ
  1886.  
  1887. Format - 'ifdef' and '//' comments 
  1888.  
  1889. // SM$:FO  C:\TEST\TEST.C - 03/28/94 14:30:22
  1890.   /* Open the file with the OF_PARSE flag to obtain the fully qualified
  1891.    * pathname in the OFSTRUCT structure.
  1892.    */
  1893. #ifndef OS221
  1894.   wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);// SM$:O
  1895. #else
  1896.   wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  // SM$:M3
  1897.   DosOpen (,,,,,,,)                          // SM$:M3
  1898.   DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              // SM$:M2
  1899.   // OpenFile Cat:030 Type:010 Area:130                  SM$:K
  1900.   // Replace with DosOpen, DosDelete, or DosQueryPathInfo         SM$:S
  1901.   //                                   SM$:C
  1902.   // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990         SM$:1
  1903.   //                                   SM$:C
  1904.   // OF_PARSE Cat:020 Type:030 Area:130                  SM$:K
  1905.   // Use DosQueryPathInfo to replace OpenFile function call        SM$:S
  1906. #endif
  1907.  
  1908. #ifndef OS221
  1909.   _lclose (wFileTemp);                         // SM$:O
  1910. #else
  1911.   DosClose (wFileTemp);                        // SM$:M1
  1912.   // _lclose replaced with DosClose - Cat:010 Type:010 Area:130      SM$:1
  1913. #endif
  1914.  
  1915. #ifndef OS221
  1916.   LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           // SM$:O
  1917. #else
  1918.   LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           // SM$:R
  1919.   WinLoadString (,,,,);                         // SM$:M2
  1920.   // LoadString Cat:020 Type:010 Area:060                 SM$:K
  1921.   // Replace with WinLoadString                      SM$:S
  1922. #endif
  1923.  
  1924.       CONTINUE - Format - NO 'ifdef' and '/*...*/' comments 
  1925.       BACK - Format - 'ifdef' and '/*...*/' comments 
  1926.       Migration Formats 
  1927.       CONTENTS 
  1928.  
  1929.  
  1930. ΓòÉΓòÉΓòÉ 8.1.4. Format - NO 'ifdef' and '/*...*/' comments ΓòÉΓòÉΓòÉ
  1931.  
  1932. Format - NO 'ifdef' and '/*...*/' comments 
  1933.  
  1934. /* SM$:FO  C:\TEST\TEST.C - 03/28/94 14:32:18                */
  1935.   /* Open the file with the OF_PARSE flag to obtain the fully qualified
  1936.    * pathname in the OFSTRUCT structure.
  1937.    */
  1938.   /* wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE); SM$:O */
  1939.   wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  /* SM$:M3 */
  1940.   DosOpen (,,,,,,,)                          /* SM$:M3 */
  1941.   DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              /* SM$:M2 */
  1942.   /*                                   SM$:C
  1943.    * OpenFile Cat:030 Type:010 Area:130                  SM$:K
  1944.    * Replace with DosOpen, DosDelete, or DosQueryPathInfo         SM$:S
  1945.    *                                   SM$:C
  1946.    * LPSTR replaced with PSZ - Cat:010 Type:030 Area:990         SM$:1
  1947.    *                                   SM$:C
  1948.    * OF_PARSE Cat:020 Type:030 Area:130                  SM$:K
  1949.    * Use DosQueryPathInfo to replace OpenFile function call        SM$:S
  1950.    */                                 /* SM$:C */
  1951.  
  1952.   /* _lclose (wFileTemp);                         SM$:O */
  1953.   DosClose (wFileTemp);                        /* SM$:M1 */
  1954.   /*                                   SM$:C
  1955.    * _lclose replaced with DosClose - Cat:010 Type:010 Area:130      SM$:1
  1956.    */                                 /* SM$:C */
  1957.  
  1958.   /* LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           SM$:O */
  1959.   LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           /* SM$:R */
  1960.   WinLoadString (,,,,);                         /* SM$:M2 */
  1961.   /*                                    SM$:C
  1962.   * LoadString Cat:020 Type:010 Area:060                 SM$:K
  1963.   * Replace with WinLoadString                      SM$:S
  1964.   */                                  /* SM$:C */
  1965.  
  1966.       CONTINUE - Format - NO 'ifdef' and '//' comments 
  1967.       BACK - Format - 'ifdef' and '//' comments 
  1968.       Migration Formats 
  1969.       CONTENTS 
  1970.  
  1971.  
  1972. ΓòÉΓòÉΓòÉ 8.1.5. Format - NO 'ifdef' and '//' comments ΓòÉΓòÉΓòÉ
  1973.  
  1974. Format - NO 'ifdef' and '//' comments 
  1975.  
  1976. // SM$:FO  C:\TEST\TEST.C - 03/28/94 14:33:45
  1977.   /* Open the file with the OF_PARSE flag to obtain the fully qualified
  1978.    * pathname in the OFSTRUCT structure.
  1979.    */
  1980.   // wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);SM$:O
  1981.   wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  // SM$:M3
  1982.   DosOpen (,,,,,,,)                          // SM$:M3
  1983.   DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              // SM$:M2
  1984.   // OpenFile Cat:030 Type:010 Area:130                  SM$:K
  1985.   // Replace with DosOpen, DosDelete, or DosQueryPathInfo         SM$:S
  1986.   //                                   SM$:C
  1987.   // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990         SM$:1
  1988.   //                                   SM$:C
  1989.   // OF_PARSE Cat:020 Type:030 Area:130                  SM$:K
  1990.   // Use DosQueryPathInfo to replace OpenFile function call        SM$:S
  1991.  
  1992.   // _lclose (wFileTemp);                         SM$:O
  1993.   DosClose (wFileTemp);                        // SM$:M1
  1994.   // _lclose replaced with DosClose - Cat:010 Type:010 Area:130      SM$:1
  1995.  
  1996.   // LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           SM$:O
  1997.   LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           // SM$:R
  1998.   WinLoadString (,,,,);                         // SM$:M2
  1999.   // LoadString Cat:020 Type:010 Area:060                 SM$:K
  2000.   // Replace with WinLoadString                      SM$:S
  2001.  
  2002.       CONTINUE - Format - '//' comments and NO Tags 
  2003.       BACK - Format - NO 'ifdef' and '/*...*/' comments 
  2004.       Migration Formats 
  2005.       CONTENTS 
  2006.  
  2007.  
  2008. ΓòÉΓòÉΓòÉ 8.1.6. Format - '//' comments and NO Tags ΓòÉΓòÉΓòÉ
  2009.  
  2010. Format - '//' comments and NO Tags 
  2011.  
  2012. Note:   Option chosen to insert Short comment and Prototype only. Elimination 
  2013. of tags on commented lines prevents automatic removal of inserted code! 
  2014.  
  2015. // SM$:FO  C:\TEST\TEST.C - 03/28/94 14:34:59
  2016.   /* Open the file with the OF_PARSE flag to obtain the fully qualified
  2017.    * pathname in the OFSTRUCT structure.
  2018.    */
  2019.   // wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);
  2020.   wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);
  2021.   DosOpen (,,,,,,,)
  2022.   DosQueryPathInfo (, FIL_QUERYFULLNAME,,);
  2023.   // OpenFile Cat:030 Type:010 Area:130
  2024.   // Replace with DosOpen, DosDelete, or DosQueryPathInfo
  2025.   //
  2026.   // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990
  2027.   //
  2028.   // OF_PARSE Cat:020 Type:030 Area:130
  2029.   // Use DosQueryPathInfo to replace OpenFile function call
  2030.  
  2031.   // _lclose (wFileTemp);
  2032.   DosClose (wFileTemp);
  2033.   // _lclose replaced with DosClose - Cat:010 Type:010 Area:130
  2034.  
  2035.   // LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));
  2036.   LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));
  2037.   WinLoadString (,,,,);
  2038.   // LoadString Cat:020 Type:010 Area:060
  2039.   // Replace with WinLoadString
  2040.  
  2041.       CONTINUE - Format - '//', Short comments and Prototypes 
  2042.       BACK - Format - NO 'ifdef' and '//' comments 
  2043.       Migration Formats 
  2044.       CONTENTS 
  2045.  
  2046.  
  2047. ΓòÉΓòÉΓòÉ 8.1.7. Format - '//', Short comments and Prototypes ΓòÉΓòÉΓòÉ
  2048.  
  2049. Format - '//', Short comments and Prototypes 
  2050.  
  2051. // SM$:FO  C:\TEST\TEST.C - 03/28/94 14:37:08
  2052.   /* Open the file with the OF_PARSE flag to obtain the fully qualified
  2053.    * pathname in the OFSTRUCT structure.
  2054.    */
  2055.   // wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);SM$:O
  2056.   wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  // SM$:M3
  2057.   DosOpen (,,,,,,,)                          // SM$:M3
  2058.   DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              // SM$:M2
  2059.   // OpenFile Cat:030 Type:010 Area:130                  SM$:K
  2060.   // Replace with DosOpen, DosDelete, or DosQueryPathInfo         SM$:S
  2061.   //                                   SM$:C
  2062.   // APIRET APIENTRY DosOpen(PSZ pszFileName, PHFILE pHf,         SM$:P
  2063.   //  PULONG pulAction, ULONG  cbFile, ULONG  ulAttribute,        SM$:P
  2064.   //  ULONG  fsOpenFlags, ULONG  fsOpenMode, PEAOP2 peaop2);       SM$:P
  2065.   // APIRET APIENTRY DosQueryPathInfo(PSZ pszPathName,          SM$:P
  2066.   //  ULONG ulInfoLevel, PVOID pInfoBuf, ULONG cbInfoBuf);        SM$:P
  2067.   // APIRET APIENTRY DosSearchPath(ULONG flag, PSZ pszPathOrName,     SM$:P
  2068.   //  PSZ pszFilename, PBYTE pBuf, ULONG cbBuf);             SM$:P
  2069.   // APIRET APIENTRY DosDelete(PSZ pszFile);               SM$:P
  2070.   //                                   SM$:C
  2071.   // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990         SM$:1
  2072.   //                                   SM$:C
  2073.   // OF_PARSE Cat:020 Type:030 Area:130                  SM$:K
  2074.   // Use DosQueryPathInfo to replace OpenFile function call        SM$:S
  2075.   //                                   SM$:C
  2076.   // APIRET APIENTRY DosQueryPathInfo(PSZ pszPathName,          SM$:P
  2077.   //  ULONG ulInfoLevel, PVOID pInfoBuf, ULONG cbInfoBuf);        SM$:P
  2078.  
  2079.   // _lclose (wFileTemp);                         SM$:O
  2080.   DosClose (wFileTemp);                        // SM$:M1
  2081.   // _lclose replaced with DosClose - Cat:010 Type:010 Area:130      SM$:1
  2082.  
  2083.   // LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           SM$:O
  2084.   LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           // SM$:R
  2085.   WinLoadString (,,,,);                         // SM$:M2
  2086.   // LoadString Cat:020 Type:010 Area:060                 SM$:K
  2087.   // Replace with WinLoadString                      SM$:S
  2088.   //                                    SM$:C
  2089.   // LONG APIENTRY WinLoadString (HAB hab, HMODULE hModResource,      SM$:P
  2090.   //  ULONG idString, LONG lBufferMax, PSZ pszBuffer);          SM$:P
  2091.  
  2092. See Also: 
  2093.  
  2094.       CONTINUE - Format - '/*...*/', Long comments, Prototypes and Examples 
  2095.       BACK - Format - '//' comments and NO Tags 
  2096.       Migration Formats 
  2097.       CONTENTS 
  2098.  
  2099.  
  2100. ΓòÉΓòÉΓòÉ 8.1.8. Format - '/*...*/', Long comments, Prototypes and Examples ΓòÉΓòÉΓòÉ
  2101.  
  2102. Format - '/*...*/', Long comments, Prototypes and Examples 
  2103.  
  2104. // SM$:FO  C:\TEST\TEST.C - 03/28/94 14:38:42
  2105.   /* Open the file with the OF_PARSE flag to obtain the fully qualified
  2106.    * pathname in the OFSTRUCT structure.
  2107.    */
  2108.   // wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);SM$:O
  2109.   wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  // SM$:M3
  2110.   DosOpen (,,,,,,,)                          // SM$:M3
  2111.   DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              // SM$:M2
  2112.   // OpenFile Cat:030 Type:010 Area:130                  SM$:K
  2113.   // Replace with DosOpen to open a file.  Use DosQueryPathInfo      SM$:L
  2114.   // specifying FIL_QUERYFULLNAME to parse the file name.  Use      SM$:L
  2115.   // DosSearchPath to query the fully qualified path name of a      SM$:L
  2116.   // file.  Use DosDelete to delete a file.                SM$:L
  2117.   //                                   SM$:C
  2118.   // APIRET APIENTRY DosOpen(PSZ pszFileName, PHFILE pHf,         SM$:P
  2119.   //  PULONG pulAction, ULONG  cbFile, ULONG  ulAttribute,        SM$:P
  2120.   //  ULONG  fsOpenFlags, ULONG  fsOpenMode, PEAOP2 peaop2);       SM$:P
  2121.   // APIRET APIENTRY DosQueryPathInfo(PSZ pszPathName,          SM$:P
  2122.   //  ULONG ulInfoLevel, PVOID pInfoBuf, ULONG cbInfoBuf);        SM$:P
  2123.   // APIRET APIENTRY DosSearchPath(ULONG flag, PSZ pszPathOrName,     SM$:P
  2124.   //  PSZ pszFilename, PBYTE pBuf, ULONG cbBuf);             SM$:P
  2125.   // APIRET APIENTRY DosDelete(PSZ pszFile);               SM$:P
  2126.   //                                   SM$:C
  2127.   // Windows:                               SM$:X
  2128.   //  OFSTRUCT OFStruct;                         SM$:X
  2129.   //  HFILE hFile = OpenFile ("TEST.DAT", &OFStruct,           SM$:X
  2130.   //          OF_CREATE);                    SM$:X
  2131.   // OS/2:                                SM$:X
  2132.   //  HFILE hFile;                            SM$:X
  2133.   //  ULONG ulAction;                          SM$:X
  2134.   //  DosOpen ("TEST.DAT", &hFile, &ulAction, FILE_NORMAL,        SM$:X
  2135.   //   OPEN_ACTION_CREATE_IF_NEW |                   SM$:X
  2136.   //   OPEN_ACTION_REPLACE_IF_EXISTS, OPEN_ACCESS_READWRITE |      SM$:X
  2137.   //   OPEN_SHARE_DENYNONE, NULL);                   SM$:X
  2138.   //                                   SM$:C
  2139.   // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990         SM$:1
  2140.   //                                   SM$:C
  2141.   // OF_PARSE Cat:020 Type:030 Area:130                  SM$:K
  2142.   // Use DosQueryPathInfo specifying FIL_QUERYFULLNAME to         SM$:L
  2143.   // query the full path of a file.  This replaces the OpenFile      SM$:L
  2144.   // function call.                            SM$:L
  2145.   //                                   SM$:C
  2146.   // APIRET APIENTRY DosQueryPathInfo(PSZ pszPathName,          SM$:P
  2147.   //  ULONG ulInfoLevel, PVOID pInfoBuf, ULONG cbInfoBuf);        SM$:P
  2148.  
  2149.   // _lclose (wFileTemp);                         SM$:O
  2150.   DosClose (wFileTemp);                        // SM$:M1
  2151.   // _lclose replaced with DosClose - Cat:010 Type:010 Area:130      SM$:1
  2152.  
  2153.   // LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           SM$:O
  2154.   LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz));           // SM$:R
  2155.   WinLoadString (,,,,);                         // SM$:M2
  2156.   // LoadString Cat:020 Type:010 Area:060                 SM$:K
  2157.   // Replace with WinLoadString                      SM$:L
  2158.   //                                    SM$:C
  2159.   // LONG APIENTRY WinLoadString (HAB hab, HMODULE hModResource,      SM$:P
  2160.   //  ULONG idString, LONG lBufferMax, PSZ pszBuffer);          SM$:P
  2161.   //                                    SM$:C
  2162.   // Windows:                               SM$:X
  2163.   //  int iLen = LoadString (hInst, 1, szBuf, sizeof(szBuf));       SM$:X
  2164.   // OS/2:                                 SM$:X
  2165.   //  LONG lLen = WinLoadString (hAB, hMod, 1, sizeof(szBuf),       SM$:X
  2166.   //          szBuf);                       SM$:X
  2167.  
  2168.       CONTINUE - Format - Source code with migration comments removed 
  2169.       BACK - Format - '//', Short comments and Prototypes 
  2170.       Migration Formats 
  2171.       CONTENTS 
  2172.  
  2173.  
  2174. ΓòÉΓòÉΓòÉ 8.1.9. Format - Source code with migration comments removed ΓòÉΓòÉΓòÉ
  2175.  
  2176. Format - Source code with migration comments removed 
  2177.  
  2178.   /* Open the file with the OF_PARSE flag to obtain the fully qualified
  2179.    * pathname in the OFSTRUCT structure.
  2180.    */
  2181.   wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE);  // SM$:M3
  2182.   DosOpen (,,,,,,,)                          // SM$:M3
  2183.   DosQueryPathInfo (, FIL_QUERYFULLNAME,,);              // SM$:M2
  2184.   DosClose (wFileTemp);                        // SM$:M1
  2185.   WinLoadString (,,,,);                        // SM$:M2
  2186.  
  2187.       CONTINUE - SMART Files 
  2188.       BACK - Format - '/*...*/', Long comments, Prototypes and Examples 
  2189.       Migration Formats 
  2190.       CONTENTS 
  2191.  
  2192.  
  2193. ΓòÉΓòÉΓòÉ 8.2. SMART Files ΓòÉΓòÉΓòÉ
  2194.  
  2195. The SMART generates a number of files related to Analysis and Migration. Also, 
  2196. a set of files may be created as a result of The SMART Editor creating a 
  2197. hyperlink database for the source files processed by SMART. 
  2198.  
  2199. These files are listed below: 
  2200.  
  2201.         SMART Dictionary and Migration Database files (one set per directory) 
  2202.          XXXXXXXX.TBL - Dictionary 
  2203.          SMART1DB.D1 - Database 
  2204.          SMART1DB.D2 - Database 
  2205.          SMART1DB.D3 - Database 
  2206.          SMART1DB.D4 - Database 
  2207.          SMART1DB.K1 - Database 
  2208.  
  2209.         Analysis and Migration files (in List-of-Files Directory) 
  2210.          XXXXXXXX.LST - List-of-Files 
  2211.          (List-of-Files).RPT - Analysis report 
  2212.          (List-of-Files).LOG - Logfile from The SMART Editor (SLBUILD) 
  2213.          (List-of-Files).RSP - Response File for The SMART Editor (SLBUILD) 
  2214.          (List-of-Files).LNK - Analysis Keyword List 
  2215.          (List-of-FileX).LOG - Logfile from The SMART Editor (SLBUILD) 
  2216.       (Migrated files) 
  2217.          (List-of-FileX).RSP - Response File for The SMART Editor (SLBUILD) 
  2218.       (Migrated files) 
  2219.          (List-of-FileX).LNK - Migration Keyword List 
  2220.  
  2221.         Analysis and Migration Files (in directories with original source 
  2222.       files) 
  2223.          XXXXXXXXX.X_X - Migrated Source file with mapped extension 
  2224.          (source file)_^ - Binary analysis data file (one for each source 
  2225.       file) 
  2226.  
  2227.         The SMART Editor Database Link files and report displays (from DB 
  2228.       Build) 
  2229.         (in directory with List-of-Files) 
  2230.          SLINK2DB.D1 - The SMART Editor Link Database file 
  2231.          SLINK2DB.D2 - The SMART Editor Link Database file 
  2232.          SLINK2DB.K1 - The SMART Editor Link Database file 
  2233.          SLINK2DB.K2 - The SMART Editor Link Database file 
  2234.          SLINK2DB.K3 - The SMART Editor Link Database file 
  2235.          SL_CALL.RPT - The SMART Editor Call Tree display report 
  2236.          SL_DLGBOX.RPT - The SMART Editor Dialog Template display report 
  2237.          SL_FUNCT.RPT - The SMART Editor Functions List display report 
  2238.          SL_GLOB.RPT - The SMART Editor Globals display report 
  2239.          SL_MODS.RPT - The SMART Editor Files display report 
  2240.          SL_UNREF.RPT - The SMART Editor Unreferenced Functions display report 
  2241.          SL_USER.RPT - The SMART Editor User Links display report 
  2242.          (contains keywords found in Migration or Analysis from SMART 
  2243.       processes) 
  2244.  
  2245.         SMART Resource Translator 
  2246.          resourcefilename.ERR - Default error filename 
  2247.          resourcefilename.HHH - Default generated header filename 
  2248.          resourcefilename.SUM - Default summary filename 
  2249.          resourcefilename.RCX - Default translated resource filename 
  2250.  
  2251.         Other SMART Files 
  2252.          MAPEXT.DAT - File extension mapping data (SMART directory). 
  2253.  
  2254.       CONTINUE - Specifications and Restrictions 
  2255.       BACK - Format - Source code with migration comments removed 
  2256.       CONTENTS 
  2257.  
  2258.  
  2259. ΓòÉΓòÉΓòÉ 8.3. Specifications and Restrictions ΓòÉΓòÉΓòÉ
  2260.  
  2261. Specifications and Restrictions 
  2262.  
  2263.    Maximum path and file length   255
  2264.    Maximum Migration Database Path length   47
  2265.    Maximum directory levels    10
  2266.    Maximum ifdef name length   40
  2267.    Maximum "List-of-Files" data   64K
  2268.    (unless created by an editor)
  2269.    Maximum lines of code in any one file  32767
  2270.    Maximum code line length    512
  2271.    Supported preprocessor statements:
  2272.    #if, #ifdef, # if defined, #else, #elseif, #endif
  2273.  
  2274.    Analysis and Migration- syntax not supported:
  2275.  
  2276.    - Keywords within quotation marks
  2277.    - Keywords within macro define statements
  2278.    - Fields of a structure are not identified for migration
  2279.    - Context of a parameter within a call
  2280.  
  2281.    Resource Translator (Windows Only) restrictions:
  2282.  
  2283.    - Macros cannot be used for any of the reserved resource
  2284.      definition keywords.
  2285.    - Preprocessor conditional statements must begin and end
  2286.      within a single file.
  2287.    - Preprocessor conditional statements within a DIALOG
  2288.      resource definition template are properly evaluated but
  2289.      are not output to the converted resource file.
  2290.    - #include and rcinclude statements are not recognized within
  2291.      any multiline resource statements.
  2292.    - #define statements are not recognized within any multiline
  2293.      resource statements.
  2294.    - Macro definitions which contain parameter substitutions are
  2295.      currently  not processed.
  2296.    - Can either replace the existing files with the converted files
  2297.      or save the converted file with a different file extension.
  2298.    - When converting dialog units as outlined in the Dialog
  2299.      Conversion  section the conversion is relative to the
  2300.      system font for the current display resolution.
  2301.  
  2302.       CONTINUE - Technical Support 
  2303.       BACK - SMART Files 
  2304.       CONTENTS 
  2305.  
  2306.  
  2307. ΓòÉΓòÉΓòÉ 8.4. Technical Support ΓòÉΓòÉΓòÉ
  2308.  
  2309. Technical Support 
  2310.  
  2311.   Internet:
  2312.      Send questions or comments to devcon@vnet.ibm.com
  2313.  
  2314.   CompuServe:
  2315.      Obtain access to the IBM OS/2 Developer Forum 2.
  2316.      To obtain access to the Developer Connection section, please
  2317.      send a note to CompuServe userid 73423,2767.
  2318.      To access the forum, type GO OS2DF2 at the ! prompt; then
  2319.      select the Developer Connection section.
  2320.  
  2321.   OS/2 BBS:
  2322.      The DEVCON CFORUM, under TalkLink, is a feature under the
  2323.      IBMLink Commercial Services.  Customers in the U.S. can call
  2324.      1-800-547-1283; customers outside of the U.S. should contact
  2325.      their local IBM Marketing Representative.
  2326.  
  2327.       BACK - Specifications and Restrictions 
  2328.       CONTENTS 
  2329.