═══ 1. The SMART User's Guide ═══ The SMART2 User's Guide Version 2.1B September 1995 (C) 1991, 1994, 1995 One Up Corporation Notice Table of Contents ═══ 2. Notice ═══ ** NOTICE ** This document may not, in whole or in part, be copied, reproduced, photocopied, translated, or reproduced to any electronic medium or machine readable form without prior written consent from One Up Corporation. This publication could contain technical inaccuracies or typographical errors. As changes are periodically made to the information herein; these changes may be incorporated in new additions of the publication. One Up Corporation may make improvements and/or changes in the product and/or the program described in this publication at any time. One Up Corporation is not responsible for any direct or indirect damage or loss of business resulting from inaccuracies or omissions in this publication. The specifications contained in this document are subject to change without notice. SMART - Source Migration Analysis Reporting Toolset is a trademark of One Up Corporation. OS/2, Presentation Manager are trademarks of the International Business Machines Corporation. IBM is a registered trademark of the International Business Machines Corporation. Other trademarks are property of their respective companies. CONTENTS ═══ 3. Table of Contents ═══ Chapter 1 - Introduction SMART - Concepts The Analysis/Migration Process What this Document Contains Where is the Remaining Documentation? Chapter 2 - Installation Before You Begin Installing SMART Setup Options Chapter 3 - Getting Started Getting Ready The Analysis Process The Migration Process Completing The Migration The SMART Viewer The SMART Resource Translator The SMART Win Help Translator Graphical Resource Conversion The SMART Editor Development Tool Chapter 4 - Techniques Preparing Your Source Code Reading the Analysis Summary Reports Reading the Analysis Display/Report Interpreting the Analysis Use of Common Functions Source Migration Format Considerations File Extension Mapping Source Migration Comment Code Removal Increased Productivity with The SMART Editor Chapter 5 - Reference Migration Formats Specifications and Restrictions SMART Files Technical Support CONTINUE - Chapter 1 ═══ 4. Chapter 1 - Introduction ═══ Chapter 1 - Introduction SMART - Concepts The Analysis/Migration Process What this Document Contains Where is the Remaining Documentation? CONTINUE - SMART - Concepts BACK - Table of Contents ═══ 4.1. SMART - Concepts ═══ SMART - Concepts NOTE: REFERENCES TO SOURCELINK, SMART VIEWER, MIGRATION and RESOURCE CONVERSION are only applicable with the Analysis AND Migration version of SMART. If you are only licensed for the Analysis version of SMART, you may ignore information in this and other documents to those functions that you may not have in this product. SMART - Source Migration Analysis Reporting Toolset provides analysis and source code migration assistance from one platform to another or one version to another on a given platform. This version of SMART executes on the OS/2 platform and is used for the migration of 'C' and C++ source code from Windows 16 bit to OS/2 32 bit or OS/2 16 bit to OS/2 32 bit or Win32 to OS/2 32 bit depending upon the licensed, installed tables. The process of porting source code from one platform to another is indeed difficult and subjective. In fact, exploiting the features of one platform, and using proprietary libraries, classes, and objects may make it severely difficult to port to another platform without a major rewrite of the source code. There is no pat solution or utility to port all code to a target platform, and we dare say there most probably never will be. However, with the proper tools, methodology, techniques and training the effort required in the migration of source code can be GREATLY reduced. The most appropriate solution for this process is to use productive computer tools to perform tasks that are easily identified, routine, and labor intensive and provide a knowledge base to contain information related to all occurrence types of differences between the platforms. The human element is most appropriately applied where the complexity of the issue is too complicated for the computer analysis. It is advantageous to provide the programming professional with powerful productivity tools to make global changes based on the migration issues of complex nature. SMART is designed to assist in the analysis and migration of native source code from one platform to another or one version of an operating environment to another on the same platform. The platform dependent data is contained in the migration dictionary (table) and the migration database files. This process is based on finding keywords (API calls, symbols, parameters, typedefs, etc) that differ between the source and target platforms in the migration. No attempt is made to analyze the intended use of the application source code. As such, there is no intent to evaluate platform exploitation, or evaluate the use of the source code for application functionality such as MDI, DDEML, communication, LAN, and etc. The base API keyword differences are categorized into groups to represent the difficulty in migration, ranging from a simple literal replacement to the case where the functionality does not exist in the target platform. In the Analysis process, SMART will analyze source code and prepare a report (display) providing a detailed evaluation of the migration requirements. Furthermore, in the migration process, SMART will process the user specified source files and create migrated source files. The migrated source file will contain automatic migration changes (where possible) and in all cases will provide in-line commented code for the developer to complete the migration. CONTINUE - The Analysis/Migration Process BACK - Chapter 1 - Introduction CONTENTS ═══ 4.2. The Analysis/Migration Process ═══ The Analysis/Migration Process There are several key concepts regarding the operation of the SMART Toolset including: The List-of-Files, keyword, category and hit. A List-of-Files is a text file that contains all of the fully qualified filenames for the source files to be processed by SMART. Typically this will include all program source files (.C) and all header files (.H). Resource files are migrated in a separate process using the resource translator (Windows->OS/2 Migration only). Keywords are items that are the basis for the definition of the interface to a platform and may represent API (Application Programming Interface) calls, symbols, parameters, structures, and typedefs. Keywords are the basis for migration with SMART. As keywords are encountered in the SMART Analysis and/or Migration processes SMART will look to the migration tables to indicate the appropriate change as required. Category is a key concept in the SMART process of source code migration. All of the items to be considered for migration are identified by its migration difficulty. The "category" of difficulty increases in effort and consideration and range from a category of "000" to the most difficult category of "050". There is one additional category of "999" indicating that the keyword has not been defined. This simply indicates that a keyword is identified for migration, but the explanation for the migration has not yet been defined in the SMART database. The definitions for the difficulty categories are as follows: 000 Informational only - An exact match of the keyword exists in the target platform but there is change in the size of type. (e.g. short to a long). 010 Literal replacement or Automatic migration - An equivalent definition exists in the target platform but a literal change in the keyword is required (e.g., LPSTR to PSZ) or keywords that are automatically migrated through the use of MiCL Commands. 020 Replacement with parameter changes - Equivalent functionality exists in the target platform but parameters or fields of a structure differ slightly from the source platform definition (e.g., SetWindowPos to WinSetWindowPos). Also included are parameters that are not applicable or required on the target platform (e.g., MakeProcInstance). 030 Change with more / less API calls - Equivalent functionality exists in the target platform but it must be implemented with more, or sometimes less, function calls (e.g., DlgDirList). Also included are items which map to one of several choices depending upon the type of parameter used (e.g., GetObject). 040 Logic changes required - Similar functionality exists in the target platform but the logic required to emulate the functionality must be reworked (e.g., CreatePatternBrush). 050 Functionality does not exist - There is no means provided to perform the same functionality in the target platform (e.g., GetKeynameText). Workaround coding must be implemented, where possible. 999 Dictionary entry not defined - The database does not currently have a complete description for the migration of the keyword. A Hit is simply a term referring to a match between a keyword in your source code and an item in the migration database indicating that a code change may be required. CONTINUE - What this Document Contains BACK - SMART - Concepts CONTENTS ═══ 4.3. What this Document Contains ═══ What this Document Contains This document, contains an introduction in the use of the application development tool SMART. Detailed information regarding individual functions, dialog panels, controls, parameters and options is available in the on-line documentation accessible when SMART is running. By pressing "F1" or accessing the on-line help through the "Help" menu items you can obtain details regarding the specific operation of SMART. Neither this document nor the SMART on-line help will attempt to cover specific platform migration issues beyond the help found in the on-line migration data base access through the SMART Viewer. Migration issues are covered in the documentation of the specific platforms and are left to the developer to research. This document may make reference to utilities and functions that may be specific to a particular platform and may not be included in your licensed copy of SMART. Programming UDMD dictionaries, including programming with MiCL Commands is fully explained in the document file "SMART2 Programming Guide" found in the SMART2 Desktop Folder. The complete documentation of The SMART Editor is found in the separate manual entitled "The SMART Editor Technical Manual". The chapters of this document flow in a logical order to acquaint you with the concepts, principles and general introduction to SMART. Chapter 1 - Introduction An introduction to the SMART methodology of source code migration and the functionality of the SMART Toolset. Chapter 2 - Installation Step-wise instructions in the installation of SMART. Chapter 3 - Gettiong Started A guided introductory tutorial for executing the analysis and migration processes. Chapter 4 - Techniques A set of topics covering important techniques in the use of SMART. Chapter 5 - Reference A chapter related to reference topics including migration formats specifications and technical support for this product. CONTINUE - Where is the Remaining Documentation? BACK - Analysis/Migration Process CONTENTS ═══ 4.4. Where is the Remaining Documentation? ═══ Where is the Remaining Documentation? It's on-line and accessible as you run SMART. We intentionally put the details of all the parameters, options and definitions of the dialog controls on-line. This puts your reference material where you need it most - contextually sensitive at the point of processing. While you are processing SMART press "F1" to obtain help at any menu item or dialog panel. You can also use the menu items under "Help" on your main menu bar to browse through the SMART On-Line help facility. In addition to the index and contents panels, you can view panels on additional One-Up products, reference material and tutorials on the Analysis or Migration processes. CONTINUE - Chapter 2 - Installation BACK - What This Document Contains CONTENTS ═══ 5. Chapter 2 - Installation ═══ Chapter 2 - Installation Before You Begin Installing SMART Setup Options CONTINUE - Before You Begin BACK - Where is the Remaining Documentation? CONTENTS ═══ 5.1. Before You Begin ═══ Before You Begin Before you begin the installation of SMART you may wish to take a moment to insure that you are prepared for the installation. You can install SMART from CD-ROM or you can install from Diskette. If you have this product on CD-ROM you can create diskettes for installation by executing the command MAKADSK or MAKMDSK (Depending on whether you have the analysis version of SMART or the Analysis and Migration). This command file requires that you specify the full drive and directory path of the SMART base files on the CD-ROM. If you are licensed for The SMART Editor, The SMART Editor documentation regarding installation in The SMART Editor Technical Manual. Your installation of SMART will consist of an Install diskette and one or more migration table diskettes depending upon your license. The hard disk space requirements for the basic installation is as follows: SMART Source Migration: Win3.1 -> OS/2 2.1 - 8 megabytes Win32 -> OS/2 2.1 - 12 megabytes OS/2 16->32 bit - 3 megabytes The SMART Editor: 2 megabytes If you have received this product on CD-ROM you can perform a mini-install of the SMART on your hard disk (requiring only 15 KBYTES) and run from the CD-ROM. This space only considers the installation files and does not include files created during the run time execution of either SMART or The SMART Editor. Depending upon the migration formats chosen, you may experience file requirements over five or six times the original source code space in the source migration and The SMART Editor hyperlink data base build. CONTINUE - Installing SMART BACK - Chapter 2 - Installation CONTENTS ═══ 5.2. Installing SMART ═══ Installing SMART The installation of SMART is simple. 1. Start by inserting the SMART Installation diskette into your floppy drive (A or B) or change directory to the CD-ROM directory containg the SMART files. (Depending upon the source of your SMART installation files). 2. From an OS/2 command line, type: a: (or b:), then install 3. A SMART installation window will appear to guide you through the installation. 4. When ready, select "Install" from the main installation menu bar. 5. You will be requested to specify the directory that will contain all of the SMART executing files and will be the root for subsequent sub-directories to contain sample files and migration tables. 6. You will also have an opportunity to select other installation parameters, including the Platform Tables to be installed (For Full disk installation). 7. Responding to all of the installation pop-up panels with an "Ok" (Enter key) will result in the default installation. 8. It is recommended that you store the SMART DLLs in the directory with the other SMART executables. To do so, you must have a "." (current path) in the LIBPATH statement in your CONFIG.SYS file. If not, then you must store the DLL in a path specified by the LIBPATH statement. 9. At the conclusion of the installation of SMART a desktop icon will be created for the SMART application and the SMART Viewer and two SMART Information Files. 10. If you have not already installed The SMART Editor, please follow the instructions in Chapter 3 of The SMART Editor Technical Manual to properly install this companion application. You should install The SMART Editor before SMART if you are licensed for this product. CONTINUE - Setup Options BACK - Before You Begin CONTENTS ═══ 5.3. Setup Options ═══ Setup Options After you have successfully installed SMART on your computer you may need to modify the initial setup options in the SMART application. 1. Open the Setup Options dialog panel by selecting "Setup Options" under the "Options" main menu item. 2. Check to insure that your editor is specified in this panel. If you have installed The SMART Editor, your editor name will be SLSTART. If you are using any other editor, enter the path and filename of the editor in the "Editor/Browser" entry field. 3. The next item of importance is to insure that you have specified the appropriate SMART Migration Table filename in the Tables Selection panel, under the "Tables" main menu item. 4. Both SMART and The SMART Editor allow you to drag-and-drop a selected font from the OS/2 system font palette onto the menu bar of the application in order to set all window fonts. After you have dropped the selected font, close and reopen the application to propagate the selected font throughout the application. 5. Once you have installed The SMART Editor you can register the SMART Viewer REXX macro (SMVIEWER.REX) under the "Macro" menu item. To accomplish this, pull down the "Macro" menu list in The SMART Editor and select "Define Menu Item". Choose "Add" and complete the dialog panel to register SMVIEWER.REX as a macro item, with your chose of accelerator key. Using this macro, you can mouse click on a source platform keyword and press your chosen accelerator key to display SMART Viewer on-line migration help. Within SMART Viewer you can drop your chosen font on the client area of the application. After you have set the application font you can set the fonts for each of the on-line display windows. The following chapters in this document will guide you through the basic functionality in the Analysis and Migration processes of SMART. CONTINUE - Chapter 3 - Getting Started BACK - Installing SMART CONTENTS ═══ 6. Chapter 3 - Getting Started ═══ Chapter 3 - Getting Started Getting Ready The Analysis Process The Migration Process Completing The Migration The SMART Viewer The SMART Resource Translator The SMART Win Help Translator Graphical Resource Conversion The SMART Editor Development Tool CONTINUE - Getting Ready BACK - Setup Options CONTENTS ═══ 6.1. Getting Ready ═══ Getting Ready You may wish to become familiar with SMART by using the sample source code files supplied in the installation of SMART under the "Samples" sub-directory. You can follow along with this chapter and use the steps as a general tutorial, or you may wish to strike out on your own and explore the SMART functionality on your own files. Before you start processing, it is always a good idea to backup your original source code. SMART Source Migration generates source code. Sparing you the pain of inadvertently overwriting original source code, it is well advised to "hide" your original code during your processing. SMART creates analysis files in the same directory as the source code being analyzed. If you are running from CD-ROM and using the application sample files, you will need to copy these files to your read/write hard drive. It is also advised that you always use the option to generate the changed code using the extension mapping. This will insure that a SMART process creates a file of similar name, having a different file extension to maintain uniqueness. Using this technique, you can simply rerun the process, if needed, without losing the original source file. You will most probably wish to run the SMART migration process multiple times on a sample code set with different format options to insure that you achieve the desired results for your particular needs. CONTINUE - The Analysis Process BACK - Chapter 3 - Getting Started CONTENTS ═══ 6.2. The Analysis Process ═══ The Analysis Process The analysis of source code for an evaluation of the migration and porting effort is accomplished through the use of SMART Analysis Procedure. This procedure simply consists of creating a text file (called a List-of-Files) with the fully qualified filenames of the files to be analyzed, and then perform the analysis procedure. The results of the analysis can be viewed on-screen and printed using The SMART Editor or a word processing application. First, create your analysis directories and sub-directories. Each separate analysis should be performed from a separate directory. The directory will contain the "List-of-Files" file, and subsequently will contain analysis files created by the SMART Analysis process. If separate analyses are to be created, each to represent a different component of the product under analysis, an individual sub-directory should be created to contain the analysis files. Each "List-of-Files" for individual analyses should have a different filename, even though they will be in a different sub-directory for ease of identification. Sub-directories can be created from The SMART Editor using the "Copy" function under the "More" main menu selection. Select the directory to create the new sub-directory in the "TO" section of the "Copy" dialog panel. Type the name of the new sub-directory in the "TO" "File" entry panel and press "Make Dir.". Note that you will automatically be placed in this new sub-directory. Copy the source files to be analyzed to a backup directory (and appropriate sub-directories) that will be used in this analysis. Create the "List-of-Files" files containing the files for the analysis. Use the "Maintain List-of-Files" function under the "Files" main menu item in SMART or the equivalent function in The SMART Editor under the "Link" main menu. The files in this list may span multiple directories and even drives. Execute "Analyze Code" under the "Analysis" Menu selection. Take care to select the proper option on the setup panel for this function. The standard options will have only the "Send Analysis Output to Editor" checked (all other options unchecked). The "List-of-Files" filename should be shown in the "List-of-Files" entry panel. If you chose to create a The SMART Editor Link Database, you will be able to hyperlink to points of change from the report created from this analysis procedure. NOTE: Multiple instances of SMART can be run at the same time if running more than one analysis. This may speed processing. At the completion of the analysis, you will be able to print the analysis report from SMART (as displayed at the completion of the analysis). Select "Printer Setup" to select appropriate printer, and then choose "Job Properties" to select "Landscape" for the printing mode. Close the printing setup panels with "Ok". Select "Formatting" and set the following parameters for the printed format. Uncheck "Date/Time..." and "Word Wrap". Set all page margins to 0.0. Press "Select Fonts". Uncheck "Display" but leave "Printer" fonts checked. Select the smallest "Courier" font available, "Normal" style. Close the "Formatting panels with "Ok". One last check before printing - insure that "Print File" on the "Print" dialog panel is selected (instead of "Print Select"). Press "Ok" on the "Print" dialog panel to print the analysis report. Removal and Backup of Analysis Files. To save the analysis files to floppy disk, select "Pack up Analysis Files" from the "Analysis" menu in SMART If you are running multiple analyses, you may wish to perform this step after each analysis. You will need a floppy disk with blank sufficient space to perform this function. You will also need a copy of the compression utility "PKZIP2.EXE" from PKWARE (not included with this application). The captured data in these analysis files contains absolutely no other information than appears in the analysis report. The data is in text and binary format and is used to rerun the analysis report if necessary with different file combinations or analysis options. The files copied to the floppy disk are of the analysis report, a compress file containing the analysis numerical summary data, and the text format of the List-of-Files file used for the analysis. After the analysis data is copied to the floppy disk, you can remove the small summary analyses files by selecting the "Remove Temp Analysis Files" from the "Analysis" menu. Insure that the proper "List-of-Files" file is used in this process. If multiple analyses are performed, this process must be performed for each List-of-Files used. This process will delete all "*.??^" files associated with the analysis. The 'EFFORT' value calculated for the Analysis Report is a relative number related to the number of hours required to complete the migration. The is a subjective number and varies depending upon the developers experience in the migrating platforms, and the tools, techniques and methodologies uses in the migration. The One Up Corporation Porting Work Shops may greatly reduce your porting effort through the techniques taught in these Work Shop sessions. It is suggested that you proceed through a complete migration of the sample code provided in the installation of this product, or other small sample of your source code to determine the relative difference between the reported EFFORT from SMART and the hours required in your actual process. The EFFORT value from the SMART Analysis should be used as a guide only and may not bear any correspondence to the actual time required in any porting process. The EFFORT value does not include any time required to prepare your code for migration, nor the correction of any compilation errors introduced by the migration process, or time required in learning the target or source platform programming internals. CONTINUE - The Migration Process BACK - Getting Ready CONTENTS ═══ 6.3. The Migration Process ═══ The Migration Process The migration process of SMART processes the specified source files and generates migrated files with code changes and in-line comments. The List-of-Files file contains the fully qualified filenames to migrate (as in the Analysis Process). The migrated files will be placed in the same directory as the source files (with mapped extensions if desired). The Migration Configuration dialog panel provides the user with the opportunity to select migration formats and options for each category of difficulty. It is highly recommended that you test various output migration formats with a small set of sample code in order to determine the best format for your intended purpose. Prior to executing the Migration Procedure, you will want to perform the Analysis Procedure on the source code to be migrated. Create the "List-of-Files" files containing the files for the analysis. Use the "Maintain List-of-Files" function under the "Files" main menu item in SMART or the equivalent function in The SMART Editor under the "Link" main menu. The files in this list may span multiple directories and even drives. If you have created the List-of-Files in the Analysis procedure, you may wish to modify the list for migrating a sub set of the original List-of-Files or simply migrate the full code set. Execute "Migrate Code" under the "Migration" Menu selection. Take care to select the proper option on the setup panel for this function. You will have a great latitude of options in the configuration of the Migration process. Refer to the Migration Configuration Dialog Panel for an explanation of these options. The typical default selections include use of commented code (as opposed to 'ifdef' blocks). If you are using The SMART Editor you will want to create a link database for hyperlinking to migrated changes, otherwise uncheck this option. If building The SMART Editor Database you may wish to set the DB options to link on the migration keyword list. You may wish to use the files in the samples directory of the SMART installation to try migrations with various options and see the results. Rerunning the Migration process with the same List-of-Files and the same file extension mapping will overwrite the original migration files. Recursive migration of the same files may give unpredictable results. Note that the migration process creates a new List-of-Files file containing the new migrated file names which you may wish to use for a number of purposes, including The SMART Editor Link Database build. You can now proceed through the migrated files to complete the migration according to the in-line comments that have been placed in the migrated code. Use of an editor with hyperlink source code access, like The SMART Editor will be a valuable asset in quickly pulling up on-line help and accessing all references to a migrated function, structure, etc. After you have made all changes to the migrated code, you can use the "Remove Comments and Tagged Code" to remove migration comment, examples and other code that has been inserted in the source files to assist you in the migration process. CONTINUE - Completing The Migration BACK - The Analysis Process CONTENTS ═══ 6.4. Completing the Migration ═══ Completing the Migration SMART identifies Category 000 keywords (which may require no migration at all) and automatically makes the changes for Category 010. This may account for 50-70% of the changes required in the migration. The remaining changes are identified by the comment insertion according to the options that you have chosen in the Migration Options Panel. These remaining changes, due to their categories, must be evaluated and changed as you deem necessary. You may wish to write a replacement function for the API call and change the name to call this new function or you may need to go to each change indicated and rewrite a portion of the code depending upon the usage. Any combination of techniques may be used. You are the best one to decide how you should approach this completion effort based upon productivity, compatibility and other criteria. In general, you may have chosen to restate the source code for the Category 020 changes. Since, by definition, these changes may require little effort, the original restated code is a good starting point. In most cases, you will want to make use of The SMART Editor to hyperlink to each type of change and make the decided change "across the board". You will also find The SMART Editor useful to find all occurrences of a structure, or function call before you make a change to a field or parameter to insure you fully understand its use. You may also find The SMART Editor valuable in making global replacements for a number of strings in all source files. It is highly recommended that you become familiar with The SMART Editor before you begin your migration. It will surely save you many hours of searching though your source code to find and display specific keywords, functions and other elements of your code. Take the time to go through the tutorial in The SMART Editor Technical Manual. It will only require about thirty minutes of your time and will provide you with a general understanding of the functionality of this product. With the use of The SMART Editor you will have context sensitive access to the on-line help for the IBM development help facility. The other productive tool in the SMART Toolset is the SMART Viewer. Using this on-line viewer you will be able to access the migration help of any specified keyword. Using these techniques, you may desire to have less comment inserted in-line with the migrated code and prefer to use the SMART Viewer for migration assistance for each encountered keyword. The comment tags at the end of each migration inserted line are coded for identification and removal. You can use these tags for searching (using The SMART Editor). You can adopt techniques of tagging each line as you complete the migration. There are several REXX macros provided with SMART to be used with The SMART Editor to enable personal tagging of the migration lines as you proceed with your work. When complete, you can easily remove all tagged lines and tags using the menu item under "Migration" entitled "Remove Tagged Code Lines...". The dialog panel associated with this function allows you to specify the particular lines or tags to be removed. CONTINUE - The SMART Viewer BACK - The Migration Process CONTENTS ═══ 6.5. The SMART Viewer ═══ The SMART Viewer The SMART Viewer provides a context sensitive on-line help to the SMART Migration knowledge base. By providing a topic name, you can display information regarding the migration of the specified keyword. The display windows that are available in this utility are "Topic", "Template", "Prototype", "Example", and "References". An additional window "History" provides a list of all topics accessed in the current session. The SMART Viewer is invoked from The SMART Editor through the supplied Rexx Macro "SMVIEWER.REX". Simply mouse click on a Source Platform keyword and invoke the Rexx Macro with an assigned hot-key. If you are using an editor other than The SMART Editor, you will want to create a macro or other linking function to spawn SMART Viewer with topic names. The SMART Viewer communicates externally through the proxy process "SMARTVUE.EXE", which eliminates starting a new instance each time a request for a new topic is desired. SMART View contains a search panel which allows you to enter a desired topic (keyword) name for viewing. Selected text from the "Template", "Prototype", and "Example" window displays can be copied to the clipboard buffer providing "cut" and "paste" programming capability from the migration data base to your editor. Additional functionality for this utility of SMART is explained in the SMART Viewer on-line help facility. CONTINUE - The SMART Resource Translator BACK - Completing The Migration CONTENTS ═══ 6.6. The SMART Resource Translator ═══ The SMART Resource Translator (It is necessary to use this utility only when migrating from Windows to OS/2. Resources do not require translating when migrating from one version of OS/2 to another.) The SMART Windows to OS/2 Resource Conversion utility (SMARTRC.EXE) provides source-to-source conversion of Windows resource definition files to OS/2 resource definition files. Support is provided for converting the following resource definition statements: - ACCELERATORS - AUTO3CHECKSTATE - AUTOCHECKSTATE - AUTORADIOBUTTON - BITMAP - CAPTION - CHECKBOX - CLASS - COMBOBOX - CONTROL - CTEXT - CURSOR - DEFPUSHBUTTON - DIALOG - EDITTEXT - FONT - GROUPBOX - ICON - LISTBOX - LTEXT - MENU - MENUITEM - POPUP - PUSHBUTTON - RADIOBUTTON - RCDATA - RTEXT - SCROLLBAR - SEPARATOR - STATE3 - STRINGTABLE - STYLE - USERBUTTON SMARTRC also recognizes and processes the following preprocessor directives: - #define - #elseif - #else - #endif - #if - #ifdef - #ifndef - #include - #undef - rcinclude Additional functionality includes:  Automatic reformatting of all Windows resource definition statements to the equivalent OS/2 format.  Automatic generation of alternate accelerator key sequences.  Automatic reformatting of strings contained in RCDATA to produce equivalent binary representation in the RES file.  Automatic conversion of mnemonic characters.  Automatic scaling and recalculation of OS/2 dialog units from Windows dialog units.  Automatic remapping of Windows dialog control styles to OS/2 dialog control styles.  Automatic remapping of common dialog control identifiers to equivalent OS/2 common dialog control identifiers.  Automatic detection of named-resources and generation of header file to assign integer identifiers.  Optional dialog font mapping from Windows font name and point size to OS/2 font name and point size.  Code page conversion of text strings from Windows code page to OS/2 code page. The general philosophy of converting resource definition statements is that SMARTRC will attempt to convert everything and anything that it understands. For those statements which do not have an equivalent statement in OS/2 SMARTRC will identify the file and line number on which the statement occurs. In addition, SMARTRC will identify any conversion which may result in slightly different functionality in OS/2. It is up to the developer to decide how to proceed with any statement in error. If SMARTRC detects named-resources, it will generate an include file with a .HHH extension containing integer definitions for those resources. The user either needs to rename this .HHH file and include it in the top .RC file or copy its contents into an existing .H file that is already included. It is also a good practice for the user to start at the top-most .RC file when migrating so just one .HHH file will be created and all of the generated ID numbers will be sequential. SMARTRC is a utility that can be executed from SMART through the interface dialog panel associated with "Translate Resources..." under the "Resources" menu item or can be run from a command line or embedded in a batch command file. If the Resource Translator encounters a problem during the conversion process, it will output information, warning or error messages. For a detailed explanation of these messages, select the "Help, Help Contents" menu item in the SMART application, then go to "Utility Processes, Resource Translator Topics, Resource Translator Messages". Although SMARTRC contains many run time options, simply specifying the resource filename without options will process with the system default parameters. CONTINUE - Graphical Resource Conversion BACK - The SMART Viewer CONTENTS ═══ 6.7. Win Help Translation ═══ Win Help Translation (It is necessary to use this utility only when migrating from Windows to OS/2. Help files do not require translating when migrating from one version of OS/2 to another.) The SMART Windows to OS/2 Help Translator Conversion utility (SMARTHLP.EXE) provides conversion of Windows help files to OS/2 help files. This utility can be executed from SMART through the interface dialog panel associated with "Translate Win Help..." under the "Resources" menu item or can be run from a command line or embedded in a batch command file. Follow these steps to convert a Windows RTF (Rich Text Format) file to an OS/2 help file. 1. Create an HPJ file that contains the name of the RTF file to be converted along with any bitmap names that are needed. A sample HPJ file is located in ..SMARTAUX\SAMPLE.HPJ. 2. To access the the Win Help Translator dialog panel, choose "Resources" from the SMART main dialog panel. From the Resources pulldown choose "Translate Win Help". 3. On the Win Help Translator dialog panel, enter the name (including path) of the HPJ file in the "Input Filename" field. 4. Choose the rest of the options as they apply. Generally, most of the options will be needed. 5. If the output will be used by an application, choose "Output .HLP file". If the output will be independent, like a "users' reference", choose "Output .INF file". To view the output, create an .INF file and use the VIEW command (in OS/2). 6. Another useful option is "Send Error file to Editor". Then, errors can be viewed. 7. When all options have been chosen, press "ok". 8. SMART does not display a status on the conversion process for a HELP document. If the "Send Error File to Editor" option is chosen, then the process will be complete when the error file is displayed. Otherwise, watch the OS/2 window in the backgound to ensure that the Help conversion process is complete. 9. Output from the Help conversion will depend on the options chosen. If nothing was entered in the "Output Filename" the file will be written to the same directory as the input file. 10. Unless the "Convert to IPF Only" option is chosen, the IPF file produced by SMART will automatically be sent to the IPF compiler. In that case, an INF or HLP file will be produced (depending on the option chosen). If the "Convert to IPF Only" option IS chosen, only the IPF file will be produced and will not be compiled. Note: Error messages are explained in the online help. To view the error message explanations, choose HELP from the Win Help Translator dialog panel. Then choose "Win Help Translator Topics". After that choose "Win Help Translator Messages". Please note that the IPF compiler (IPFC.EXE) is required for SMART Win Help translation. IPF (Information Processing Facility) is available from the IBM Developers Toolkit. WIN HELP TRANSLATION LIMITATIONS The .RTF format can specify a more general document than the IPF's tag language. Because of this, some word-processing functionality available with Windows help files cannot be translated to the PM IPF system. The following are the word processing functionalities that cannot be supported:  Headers and Footers are not supported and will be ignored.  Metafiles and Macintosh pictures are not supported and will be ignored. You may convert these pictures to bitmaps rather than use these unsupported formats.  Scaling and cropping of pictures are not supported and are ignored.  Outline, shadow, small-cap and all-cap character attributes are not supported and are ignored.  Revision marking, tables, side-by-side paragraphs, centered paragraphs, right-justified paragraphs, paragraph borders, and paragraph leaders are not supported and are ignored.  Decimal, right, and center tabs are not supported and are ignored.  Margins, paragraph indentations, and tabs are approximated to the nearest character width.  Line spacing before, within, and after paragraphs is approximated to the nearest system font character height.  Text does not flow around left or right-margin images, but follows immediately below the image.  Monochrome images appear in black and white instead of the text foreground and background colors.  Character attributes of bold, underline and italics work correctly in all combinations, except for all three together. It produces red text.  A maximum of 64KB of keys information can be provided.  There are cosmetic differences in the way that hypertext links are displayed on the screen and in the mouse and keyboard interfaces to those links. CONTINUE - Graphical Resource Conversion BACK - The SMART Resource Translator CONTENTS ═══ 6.8. Graphical Resource Conversion ═══ Graphical Resource Conversion (It is necessary to use this utility only when migrating from Windows to OS/2. Resource files do not require translating when migrating from one version of OS/2 to another.) The SMART Windows to OS/2 Graphical Resource Conversion utility (SMARTCVT.EXE) provides binary conversion of Windows icon, cursor, and bitmap files to OS/2 pointer files and bitmap files, respectively. Both icon and cursor files are referred to as pointer files in OS/2. The graphical format of Windows icons and cursors is significantly different from OS/2 pointer files. SMARTCVT is a utility that can be executed from SMART through the interface dialog panel associated with "Convert Graphical Resources..." under the "Resources" menu item or can be run from a command line or embedded in a batch command file. If the Graphical Resource Converter encounters a problem during the conversion process, it will output information, warning or error messages. For a detailed explanation of these messages, select the "Help, Help Contents" menu item in the SMART application, then go to "Utility Processes, Graphical Resource Converter Topics, Graphical Resource Converter Messages". The summary information output by SMARTCVT at the completion of file conversion recaps the entire conversion process. Following is an example of the output contained in the summary information: Files Processed: 10 Files Converted: 10 Warnings: 0 Errors: 0 CONTINUE - The SMART Editor Development Tool BACK - The SMART Win Help Translator CONTENTS ═══ 6.9. The SMART Editor Development Tool ═══ The SMART Editor Development Tool The SMART Editor is a feature rich programming development tool combining hyperlink source code access, a fully functional editor, and many file manipulation utility functions. Features:  Build hyperlinks to key elements of your source code.  REXX Macro interface.  Full IBM Workframe interface.  Spawn Compiles directly from The SMART Editor and hyperlink to errors.  Context sensitivity to all IBM development help files (if installed).  Edit with multiple windows, any size files.  Create functional call tree and other documentation display - all hyperlink sensitive.  Unsurpassed methods for navigating directories, drives and source code.  Hyperlink capabilities make learning new code a breeze.  Print SMART analysis and source code with format from within The SMART Editor.  Interface with SMART provides automatic hyperlink to all points of change. Please refer to The SMART Editor Technical Manual for full explanation regarding the powerful functionality available with this tool. CONTINUE - Chapter 4 - Techniques BACK - Graphical Resource Conversion CONTENTS ═══ 7. Chapter 4 - Techniques ═══ Chapter 4 - Techniques Preparing Your Source Code Reading the Analysis Display/Report Interpreting the Analysis Use of Common Functions Source Migration Format Considerations File Extension Mapping Source Migration Comment Code Removal Increased Productivity with The SMART Editor CONTINUE - Preparing Your Source Code BACK - The SMART Editor Development Tool CONTENTS ═══ 7.1. Preparing Your Source Code ═══ Preparing Your Source Code Planning a strategy for the analysis and/or migration of your source code will greatly pay back in the long run. It is essential that your original source code be backed up to insure that an inadvertently mis-chosen option, especially in the migration process, does not prevent you from restoring to your original code state. Both the Analysis and Migration processes of SMART should not be considered one-shot processes. You may wish to run the Analysis a number of times, with global code changes to change the outcome. Likewise, you may find that you want to make global changes to your code fixing a recurring hit to reduce the migration effort before you even apply SMART. For example, after a review of the initial analysis run, changing a parameter type through your code may significantly reduce the Effort reported in the analysis. After looking at the reported keyword hits in your code, you may decide to write a number of common functions that replace the source platform API calls and make global replacements for these calls to your new functions. You can rerun the Analysis Process and see the resulting effort changes. Likewise for other changes that may involve macro #defines, or typedefs. You may be surprised at the results of these preprocessing changes and how they might reduce your porting effort. Likewise, you may wish to rerun the Migration Process after analyzing the resulting initial results. It may be that you need different formatting options in the Migration Process, or you find that you can make global changes to a syntax widely used to eliminate repetitive reporting from SMART of this migration hit. Essentially, anything that you can do to your code to simplify that migration process will greatly reduce the whole porting effort. CONTINUE - Reading the Summary Reports BACK - Chapter 4 - Techniques CONTENTS ═══ 7.2. Reading the Summary Reports ═══ Reading the Summary Reports For each analysis that you run, a summary report files is created and can be printed using the SMART 'Print Analysis Report' process. A cover page preceeds the summary reports when they are printed with information regarding the date and time of the report along with the user supplied report title. A summary report is created with the standard Migration Analysis process, and the Resource Translation Analysis (if the Windows migration tables are selected). The report lines for the cover page and their description follows: SMART Source Code Migration Analysis Report - Cover Report Heading. [Next one to three lines] - User supplied report title (first line appears on each page of the report). Prepared: [Date - Time] - Date stamp of the summary report. Printed: [Date - Time] - Date stamp of the report printing. Summary: [Filename] - Filename(s) of the Summary report files. Report: [Filename] - Filename(s) of the Primary Analysis report file. The report lines for the Migration Analysis Report Summary and their description follows: Total File Count - Number of files processed in the Analysis. Total File Size (Bytes) - Total size of files processed in the Analysis. Total Source Lines - Total number of lines processed. Total Code Lines - Total number of lines processed excluding comment lines and null (skip) lines. Total Category xxx Hits - Total number of keyword encounters by category type. Total Migration Hits - Total number of all keyword encounters. Total Cat 000 and 010 Hits Auto Migrated - Total number of keyword encounters that will be automatically migrated using SMART. Total Hits MiCL Processed - Total number of keyword encounters that will be migrated using MiCL commands in either the primary Migration Database or a UDMD. Total Hits Processed with UDMD - Total number of keyword encounters were encountered from a UDMD. Total Hits Excluded - Total number of keyword encounters were excluded from processing based on a user supplied exclude list. Total Migration Keyword Instances - Total number of keyword encounters that represented different keywords. **NOTE** - The following effort estimates and productivity gains are calculated from a number of generalized factors and assumptions. The actual effort that you may encounter will depend upon your individual experience and productivity, in addition to unique difficulties that may be encountered in your coding. Please use these values as a comparative guideline only. Estimated Migration Effort Without SMART - An estimation of the total number of migration hours required to migrate this project without any use of SMART. Savings from SMART Base Migration - An estimation of the total number of migration hours saved by the base use of SMART without any productivity gains from automatic migration. Savings from Cat 010 Auto Migrate - An estimation of the total number of migration hours saved by the automatic migration from SMART. Savings from Keyword Exclusions - An estimation of the total number of migration hours not required due to exclusion from the user specified keyword exclude list. ** Net Migration Effort ** - An estimation of the total number of migration hours remaining to complete the project after processing with SMART. Percent Effort Reduction using SMART - A calculation of the net estimated migration effort as a percentage of the total estimated effort without the use of SMART. The report lines for the Resource Translation Analysis Report Summary (provided with Windows migration Analysis only) and their description follows: Total Resource File Count - Number of files processed in the Resource Analysis. Total Resource File Size (Bytes) - Size of files processed in the Resource Analysis. Total Dialog Templates - Number of Dialogs encountered in the Analysis. Total Dialog Code Lines - Number of lines of code for the Dialogs. Ave Code Lines Per Dialog - Indicates the code lines size of the average dialog. Total Menu Template Code Lines - Number of coding lines in the Menus. Total StringTable Code Lines - Number of coding lines in the String Tables. Total Accelerator Table Code Lines - Number of coding lines in the Accelerator Tables. **NOTE** - The following effort estimates and productivity gains are calculated from a number of generalized factors and assumptions. The actual effort that you may encounter will depend upon your individual experience and productivity, in addition to unique difficulties that may be encountered in your coding. Please use these values as a comparative guideline only. Estimated Translation Effort Without SMART - Estimated migration hours to convert the resource files without the use of SMART. Savings from SMART Resource Translator - Estimated migration hours saved in the effort to convert the resource files with the use of SMART automation. ** Net Translation Effort ** - An estimation of the total number of migration hours required to translate the resource files with SMART. Percent Effort Reduction using SMART - A calculation of the net estimated translation effort as a percentage of the total estimated effort without the use of SMART. CONTINUE - Reading the Analysis Display/Report BACK - Preparing Your Source Code CONTENTS ═══ 7.3. Reading the Analysis Display/Report ═══ Reading the Analysis Display/Report Each keyword is categorized by the level of difficulty required to migrate to the target platform. These categories can also be viewed as the amount of programmer interaction and expertise required for the migration. The currently defined categories and their description are as follows: 000 Informational only - An exact match of the keyword exists in the target platform but there is change in the size of type. (e.g. short to a long). 010 Literal replacement - An equivalent definition exists in the target platform but a literal change in the keyword is required (e.g., LPSTR to PSZ). 020 Replacement with parameter changes - Equivalent functionality exists in the target platform but parameters or fields of a structure differ slightly from the source platform definition (e.g., SetWindowPos to WinSetWindowPos). Also included are parameters that are not applicable or required on the target platform (e.g., MakeProcInstance). 030 Change with more / less API calls - Equivalent functionality exists in the target platform but it must be implemented with more, or sometimes less, function calls (e.g., DlgDirList). Also included are items which map to one of several choices depending upon the type of parameter used (e.g., GetObject). 040 Logic changes required - Similar functionality exists in the target platform but the logic required to emulate the functionality must be reworked (e.g., CreatePatternBrush). 050 Functionality does not exist - There is no means provided to perform the same functionality in the target platform (e.g., GetKeynameText). Workaround coding must be implemented, where possible. 999 Dictionary entry not defined - The database does not currently have a complete description for the migration of the keyword. Throughout the analysis report there are several column and section headings used to display counts of various pieces of information. These column and section headings are defined as follows: File Detail Report: PATH/FILENAME - Full path specification of the file(s) SIZE - File size in bytes LINES - Number of lines in the file CODE - Number of lines containing code in the file HITS - Number of times a keyword was identified PCT HITS - Percentage of hits per line of code (i.e., HITS / CODE) INSTS - Number of unique keywords that were identified PCT INST - Percentage of unique keywords per line of code (i.e., INSTS / CODE) EFFORT - Calculation of the relative amount of work required to migrate the code in the file CAT xxx - Number of hits in each category Keyword Detail Report: CATEGORIES - Breakdown by category of the keywords found TYPES - Breakdown by type of the keywords found (function calls, messages, symbol definitions, and typedef statements) AREAS - Breakdown by functional area of the keywords found KEYWORDS - Breakdown by individual keyword. Ordered by category and from the most number of occurrences to the least number of occurrences. HITS - Number of times a keyword for the specified item was identified. PCT HITS - Percentage of all hits identified (i.e., HITS / section total HITS) FILES - Number of files that a keyword for the specified item was found INSTS - Number of unique keywords that were identified for the specified item PCT INST - Percentage of all unique keywords identified (i.e., INSTS / section total INSTS) EFFORT - Calculation of the relative amount of work required to migrate the code for the specified item CONTINUE - Interpreting the Analysis BACK - Reading the Summary Reports CONTENTS ═══ 7.4. Interpreting the Analysis ═══ Interpreting the Analysis The analysis portion of SMART actually generates two related reports. Each report presents the detailed analysis from a different perspective. The two reports together should give you a thorough understanding of the amount of code that requires migration and the amount of effort that will be involved. A brief overview of the contents of the analysis report is relevant here before discussing how to interpret the data contained in the report. The file detail report presents a detailed analysis of each source file. This includes all of the items previously defined for the file detail report. The keyword detail report presents a more thorough breakdown of the keywords identified during the analysis. The analysis data is broken down four different ways. The first is a breakdown by category showing the counts of the keywords as identified by their respective category. The second is a breakdown by the types of the keywords. The third is a breakdown of the identified keywords by the various functional areas that a keyword is classified. The fourth is a breakdown by the individual keywords. This last breakdown shows each and every keyword that was identified and the number of occurrences. The analysis report contains a lot of valuable information about your source code. Once you understand how to interpret the data you will be able to more accurately size and evaluate the migration effort. In addition you can rerun the analysis program on your code during the migration process to give you accurate progress statistics. We begin the interpretation with the file detail portion of the analysis report. The first thing to be learned from the file detail report is simply how many lines of code are in each file and in the entire the application. This forms the basis for determining the relative distribution of the keywords in the code. The total number of hits, shown at the bottom of this part of the report, tells you how many changes must be made to the code. The percentage of hits times the number of lines of code tells you how many lines of code must be changed. Don't get overly excited at this point if this number is rather large. Until we examine the keyword detail report you don't know how many of these will be automatically migrated by SMART. Next look at the total number of instances. This is the number of unique keywords that must be migrated. What this really tells you is approximately how many individual keywords the programmer(s) will have to be familiar with in order to make various decisions during the migration. Since many migration issues and changes related to a specific keyword are the same or similar for all occurrences of that keyword the actual effort is reduced to deciding what needs to be changed and simply repeating the change for each occurrence. Again, many of these changes may be automatically migrated by SMART. At this point the effort number that is shown for each file has very little significance unless you have migrated source before. The effort calculation is based on the relative difficulty of migrating a keyword -- category 030 items are more difficult to migrate than category 020 items. Since the actual time to migrate a section of code also depends on the experience and knowledge of the programmer and on the tools being used the amount of actual time that the effort number translates to will be different for each person. In order to translate the effort number to actual time it is necessary to migrate several source files containing a mix of keywords in each of the difficulty categories. Using the actual time and the effort calculations for those migrated files you get an approximate time value for each effort unit. The last portion of the file detail report is the breakdown of the hits by their respective categories. These numbers can assist you in assigning groups of files to programmers with different levels of expertise. A file that is mostly composed of category 020 items can be assigned to someone with little experience on the target platform since most of the keywords are relatively simply to migrate. In fact, the changes required for almost all of the category 020 items is exactly a one-to-one change as detailed in the migration database. Files that contain category 040 and 050 items can be assigned to your more experienced programmers since these items require a more in-depth knowledge of what the code is attempting to do on the source platform and how the logic can be restructured to implement the same functionality on the target platform. In general, the file detail section provides a quantitative analysis of the source code showing how much must be changed. On the other hand, the keyword detail section provides more of a qualitative analysis of those changes. In the keyword detail report we get to the real nitty-gritty of what is contained in the source code. The first section, CATEGORIES, presents the first indication of how the migration breaks down by difficulty. Collectively the six columns of data can tell you a lot about how much effort will be involved and where that effort will be concentrated. The HITS, PCT HITS, and FILES columns tell you the volume of physical changes that have to be made. Even minor changes can require a great deal of time if the item occurs thousands of times or exists in hundreds of files. Time is required to open files, locate and enter changes, and save the files. Review the INSTS and PCT INSTS columns to identify the number of unique items that have to be migrated at each difficulty category. There are two things that may be learned from this information. First, while there may be a large number of HITS in a particular category it may be that they are isolated to a few particular keywords. This would actually indicate that less work is required compared to the situation where a large number of instances occur with a large number of hits. When we look at the KEYWORDS section it will be more evident if that is the case, but this section can give use a good indication of where the effort is concentrated. Second, look at the distribution of the hits and instances among the various categories. Most likely the majority of the hits as well as the instances are in categories 020 or less. The desired trend is for the numbers to decrease significantly from category 020 to category 050. Obviously the fewer category 040 and 050 items the less difficult the migration. The last column, EFFORT, is a good indicator of where you will spend most of the time during the migration. Depending on the number of instances of category 030 and 040 items it is possible that the effort for these categories can be greatly reduced. The next section, TYPES, is mostly for information purposes only. A couple of useful things about your migration effort can still be learned from it. Function and message items typically require the most effort since program logic can be affected. Symbol items require the least effort since most of the time it requires a simple change to a bit flag or a #define statement. The typedef items typically require modifications to structure field references and aren't significantly difficult items. The next section, AREAS, is again mostly for information purposes only. This section can help in staffing the migration and assigning programmers to work on individual areas of the project. By analyzing the various functional areas that require migration and the numbers associated with each you can decide what expertise on both the source and target platform is required. For example, if large portions of the migration are in the bitmap, color-palette, and drawing-tool areas you will want to make sure you assign a programmer with graphics expertise to the project. The last section, KEYWORDS, shows exactly what keywords were identified in the source and their frequency of occurrence. Since the keywords are organized by category and listed in decreasing order of occurrence it is very easy to see what needs to be changed. It is also here that you can see if you have an even distribution of hits on each keyword or if there are a lot of hits on relatively few keywords. For example, if you have 800 hits in category 030 but 450 of them are SendMessage and 250 are SelectObject then the amount of effort can be reduced. This is because the programmer will have only to look at these two items, decide the general migration changes to be applied, and make the changes (thus eliminating 700 of the 800 hits). On the other hand, if the hits are fairly evenly distributed in a category it will require more time since many more decisions on migration changes will have to be performed. This is especially important when looking at the category 040 and 050 items since these items may require significant logic changes to the application. One additional thing to note is the relationship of the various keywords in a category. If you see several keywords which relate to the same functionality it may be possible that all of those keywords will be migrated by a change to a single portion of the code. For example, if you encounter a set of mouse related messages in category 040 then all of these will most likely be resolved in the same manner or with a single change to the code. There are a few items that warrant special consideration when evaluating the SMART analysis report. The current knowledge-base technology may over-categorize a keyword resulting in a higher relative effort than is actually required. There are many functions and messages which have a one-to-many mapping to the target platform. In these cases the actual migration depends upon the intention of the function or the value of one or more parameters (e.g., a flag set in a variable). When more than one choice exists for the migration SMART will use the higher category level for the analysis report so as not to significantly underestimate the effort. For example, the Windows RegisterClass function is categorized as category 040. If the class uses the default cursor and icon then it actually is a category 020 item. Yet, if a class specific cursor, icon, or background brush is used it is a category 040 since this would require logic changes. Category 040 would be used by SMART since it would depend on the values in the WNDCLASS structure. Be aware that you may have some keywords that are overclassified. One of the suggested techniques to significantly increase the speed of the migration is to use macros or to implement functions for category 030 and 040 items that have high hit counts. This eliminates larger, redundant blocks of migrated code that implement the intended functionality and also localizes the debugging effort to a single function. If this technique is applied to your migration effort then you should take into consideration that the keywords implemented in this manner are actually category 020 items instead of category 030 or 040. CONTINUE - Use of Common Functions BACK - Reading the Analysis Display/Report CONTENTS ═══ 7.5. Use of Common Functions ═══ Use of Common Functions Significant improvements in your migration effort may be achieved through the use of common functions. Common functions refers to the implementation of source platform functions as their equivalent target platform functions. Since the migration of many keywords involves replacing the existing function call with multiple lines of code, using common functions can reduce the amount of code and coding changes required. Selecting candidates for common functions is a very subjective process. You must evaluate the analysis report for your application and review the difficulty and hit counts for each of the keywords. As a general rule a keyword is a candidate if the hit count is at least twenty (20) and the difficulty category is 030 or higher. Once a candidate is identified you must review the use of that keyword throughout the application. If the keyword is used in generally the same context throughout the application then you will probably gain migration speed by implementing the particular function or defining an appropriate macro. As an example, assume that the analysis report for a Windows application shows that GetMenuString occurs 100 times. This is a category 030 keyword since the flag may specify the menu item either by command or by position. If we examine the code and find that all of the calls are requested by command then we could decide to just implement GetMenuString as a macro which sends the MM_QUERYITEMTEXT messages. On the other hand if we have a mix of requests by both command and position we could decide to implement GetMenuString as a function which sent the appropriate messages based on the specified flag. It is recommended that you place all common functions into a single, separate source file or library. Doing so can ease your effort during the debugging phase and allows you to begin abstracting functionality for future migrations. CONTINUE - Source Migration Format Considerations BACK - Interpreting the Analysis CONTENTS ═══ 7.6. Source Migration Format Considerations ═══ Source Migration Format Considerations Each Category of the Migration Process offers a popup dialog panel to select the format of the inserted comments in the migrated code. These options include: Long, short or no comment, template, prototype, example code, restate original code and ignore migration. It may appear convenient to insert all of the above items in-line with your source code. However, in general, the more you put in your code the more difficult it is to read. It is better to insert less in your code and use the SMART Viewer to display information pertaining to the keywords as necessary. You also have the option to clip and paste from the SMART Viewer display panels to your code. After you have reviewed the Analysis report and made any necessary code changes, you may wish to ignore the Category 000 hits. Restatement of the original code has been offered as an option particularly for the Windows to OS/2 migration. This uncommented restatement allows you to rerun the Analysis Process during your process of completing the migration to determine the amount of code left to complete. Simply remove this code restatement as you make the necessary changes. You may also use this restatement as a starting point for code modification. In any case it is recommended that you try various options on the sample code or a small set of you source code to determine what works best for you. CONTINUE - File Extension Mapping BACK - Use of Common Functions CONTENTS ═══ 7.7. File Extension Mappings ═══ File Extension Mapping File extension mapping allows you to control the name of the generated source file in the Migration process for source migration, the process for commenting out #ifdef code and the process for removing tagged code. In all cases where SMART generates new source files the files are placed in the same directory as the original, with the file extension changed. The alternative to this process is to request that the original file be overwritten. For obvious reasons this is not recommended. You can control the extension mapping by specifying the map for each file extension encountered in your processing. The data for this mapping is contained in the test file MAPEXT.DAT in the main SMART directory. You can maintain this data from the popup dialog selected in the processes that offer extension mapping such as the Migration Process. The mapping data simply contains the original extension and then the extension for the map. The mapping data will not accept wildcards, but is explicitly defined. You will note that several layers of mapping is defined in the default data. For example ".C" is mapped to ".C__X", and ".C__X" is mapped to ".C__Y". This allows you to perform multiple mapping processes while saving each set of files in the processes. Please note that the mapping data is case sensitive. If your files are in lower case, the mapping data must be specified in lower case. You will be notified if SMART encounters a file that cannot be mapped, due to missing mapping data, during the process requiring the map. The SMART Resource Translator accepts wildcards and does not use this mapping data. CONTINUE - Source Migration Comment Code Removal BACK - Source Migration Format Considerations CONTENTS ═══ 7.8. Source Migration Comment Code Removal ═══ Source Migration Comment Code Removal You can automatically remove comment tagged code with SMART. Comment tagged code is defined by having a short unique set of identification characters. All of the migration insertion code has tags identified by "SM$:". The dialog selection panel shown above specifies that codes that are used by SMART. Using this panel you can select the commented code that you wish to remove at any point in your migration process. The four fields entitled "Other Tagged Lines" allows you to remove code that may have been tagged by you for your own identification purposes. This process also allows you to just remove the tags without removing the code on the lines. In this case the tags are removed at the end of the line, leaving the remaining code. To fit into this class of tagging, the tags must be at the end of the line and proceeded by a double slash ("//") and a space. You may wish to explore the functionality of this process with a file form the sample code that has been migrated. CONTINUE - Increased Productivity with The SMART Editor BACK - File Extension Mapping CONTENTS ═══ 7.9. Increased Productivity with The SMART Editor ═══ Increased Productivity with The SMART Editor The SMART Editor is provided, and has been specifically designed, to increase your productivity through the speed and ease of source code navigation and the integration of file manipulation\utilities. The single most unique feature of The SMART Editor is hyperlink access to your source code. Once you have built a hyperlink data base for your code set, you can mouse click to any function definition or popup a list of all references to a function, symbol or other key element of your code. You can request that this database be created as a result of the SMART Analysis or Migration Process, or you can create the link data base within The SMART Editor application. In your migration process, if you wish to look at all the places where a function is used, simply double click with the right mouse button on the function in question, and The SMART Editor will create a display of all references. Since The SMART Editor displays are both hyperlink sensitive and editable, you may double click (left mouse button) on the filename-line number for any of the displayed references and The SMART Editor will immediately open the file at the point of reference. Another powerful feature of The SMART Editor is the ability to perform multiple file, string searches and provide a hyperlink display file of all strings found for your immediate access. You can use your "List-of-Files" from the SMART Analysis or Migration as the input file specification to this search process. In addition to the powerful source code access function The SMART Editor allows you to spawn compiles and hyperlink to the point of error. The SMART Editor has been specifically designed to assist you in productively maintaining your code. The integration of the features and the powerful navigation functionality will greatly reduce your time and effort in porting your code. CONTINUE - Chapter 5 - Reference BACK - Source Migration Comment Code Removal CONTENTS ═══ 8. Chapter 5 - Reference ═══ Chapter 5 - Reference Migration Formats SMART Files Specifications and Restrictions Technical Support CONTINUE - Migration Formats BACK - Increased Productivity with The SMART Editor CONTENTS ═══ 8.1. Migration Formats ═══ Migrated code formats are user configurable. A number of options relating to the migrated code are available. The Format References include the following formats:  Original source code (before migration)  Format - 'ifdef' and '/*...*/' comments  Format - 'ifdef' and '//' comments  Format - NO 'ifdef' and '/*...*/' comments  Format - NO 'ifdef' and '//' comments  Format - '//' comments and NO Tags  Format - '//', Short comments and Prototypes  Format - '/*...*/', Long comments, Prototypes and Examples  Format - Source code with migration comments removed CONTINUE - Original source code (before migration) BACK - Chapter 5 - Reference CONTENTS ═══ 8.1.1. Original source code (before migration) ═══ Original Source Code /* Open the file with the OF_PARSE flag to obtain the fully qualified * pathname in the OFSTRUCT structure. */ wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE); _lclose (wFileTemp); LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); CONTINUE - Format - 'ifdef' and '/*...*/' comments BACK - Migration Formats CONTENTS ═══ 8.1.2. Format - 'ifdef' and '/*...*/' comments ═══ Format - 'ifdef' and '/*...*/' comments /* SM$:FO C:\TEST\TEST.C - 03/28/94 14:25:07 */ /* Open the file with the OF_PARSE flag to obtain the fully qualified * pathname in the OFSTRUCT structure. */ #ifndef OS221 wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);/* SM$:O */ #else wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE); /* SM$:M3 */ DosOpen (,,,,,,,) /* SM$:M3 */ DosQueryPathInfo (, FIL_QUERYFULLNAME,,); /* SM$:M2 */ /* SM$:C * OpenFile Cat:030 Type:010 Area:130 SM$:K * Replace with DosOpen, DosDelete, or DosQueryPathInfo SM$:S * SM$:C * LPSTR replaced with PSZ - Cat:010 Type:030 Area:990 SM$:1 * SM$:C * OF_PARSE Cat:020 Type:030 Area:130 SM$:K * Use DosQueryPathInfo to replace OpenFile function call SM$:S */ /* SM$:C */ #endif #ifndef OS221 _lclose (wFileTemp); /* SM$:O */ #else DosClose (wFileTemp); /* SM$:M1 */ /* SM$:C * _lclose replaced with DosClose - Cat:010 Type:010 Area:130 SM$:1 */ /* SM$:C */ #endif #ifndef OS221 LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); /* SM$:O */ #else LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); /* SM$:R */ WinLoadString (,,,,); /* SM$:M2 */ /* SM$:C * LoadString Cat:020 Type:010 Area:060 SM$:K * Replace with WinLoadString SM$:S */ /* SM$:C */ #endif CONTINUE - Format - 'ifdef' and '//' comments BACK - Original source code (before migration) Migration Formats CONTENTS ═══ 8.1.3. Format - 'ifdef' and '//' comments ═══ Format - 'ifdef' and '//' comments // SM$:FO C:\TEST\TEST.C - 03/28/94 14:30:22 /* Open the file with the OF_PARSE flag to obtain the fully qualified * pathname in the OFSTRUCT structure. */ #ifndef OS221 wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);// SM$:O #else wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE); // SM$:M3 DosOpen (,,,,,,,) // SM$:M3 DosQueryPathInfo (, FIL_QUERYFULLNAME,,); // SM$:M2 // OpenFile Cat:030 Type:010 Area:130 SM$:K // Replace with DosOpen, DosDelete, or DosQueryPathInfo SM$:S // SM$:C // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990 SM$:1 // SM$:C // OF_PARSE Cat:020 Type:030 Area:130 SM$:K // Use DosQueryPathInfo to replace OpenFile function call SM$:S #endif #ifndef OS221 _lclose (wFileTemp); // SM$:O #else DosClose (wFileTemp); // SM$:M1 // _lclose replaced with DosClose - Cat:010 Type:010 Area:130 SM$:1 #endif #ifndef OS221 LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); // SM$:O #else LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); // SM$:R WinLoadString (,,,,); // SM$:M2 // LoadString Cat:020 Type:010 Area:060 SM$:K // Replace with WinLoadString SM$:S #endif CONTINUE - Format - NO 'ifdef' and '/*...*/' comments BACK - Format - 'ifdef' and '/*...*/' comments Migration Formats CONTENTS ═══ 8.1.4. Format - NO 'ifdef' and '/*...*/' comments ═══ Format - NO 'ifdef' and '/*...*/' comments /* SM$:FO C:\TEST\TEST.C - 03/28/94 14:32:18 */ /* Open the file with the OF_PARSE flag to obtain the fully qualified * pathname in the OFSTRUCT structure. */ /* wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE); SM$:O */ wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE); /* SM$:M3 */ DosOpen (,,,,,,,) /* SM$:M3 */ DosQueryPathInfo (, FIL_QUERYFULLNAME,,); /* SM$:M2 */ /* SM$:C * OpenFile Cat:030 Type:010 Area:130 SM$:K * Replace with DosOpen, DosDelete, or DosQueryPathInfo SM$:S * SM$:C * LPSTR replaced with PSZ - Cat:010 Type:030 Area:990 SM$:1 * SM$:C * OF_PARSE Cat:020 Type:030 Area:130 SM$:K * Use DosQueryPathInfo to replace OpenFile function call SM$:S */ /* SM$:C */ /* _lclose (wFileTemp); SM$:O */ DosClose (wFileTemp); /* SM$:M1 */ /* SM$:C * _lclose replaced with DosClose - Cat:010 Type:010 Area:130 SM$:1 */ /* SM$:C */ /* LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); SM$:O */ LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); /* SM$:R */ WinLoadString (,,,,); /* SM$:M2 */ /* SM$:C * LoadString Cat:020 Type:010 Area:060 SM$:K * Replace with WinLoadString SM$:S */ /* SM$:C */ CONTINUE - Format - NO 'ifdef' and '//' comments BACK - Format - 'ifdef' and '//' comments Migration Formats CONTENTS ═══ 8.1.5. Format - NO 'ifdef' and '//' comments ═══ Format - NO 'ifdef' and '//' comments // SM$:FO C:\TEST\TEST.C - 03/28/94 14:33:45 /* Open the file with the OF_PARSE flag to obtain the fully qualified * pathname in the OFSTRUCT structure. */ // wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);SM$:O wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE); // SM$:M3 DosOpen (,,,,,,,) // SM$:M3 DosQueryPathInfo (, FIL_QUERYFULLNAME,,); // SM$:M2 // OpenFile Cat:030 Type:010 Area:130 SM$:K // Replace with DosOpen, DosDelete, or DosQueryPathInfo SM$:S // SM$:C // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990 SM$:1 // SM$:C // OF_PARSE Cat:020 Type:030 Area:130 SM$:K // Use DosQueryPathInfo to replace OpenFile function call SM$:S // _lclose (wFileTemp); SM$:O DosClose (wFileTemp); // SM$:M1 // _lclose replaced with DosClose - Cat:010 Type:010 Area:130 SM$:1 // LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); SM$:O LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); // SM$:R WinLoadString (,,,,); // SM$:M2 // LoadString Cat:020 Type:010 Area:060 SM$:K // Replace with WinLoadString SM$:S CONTINUE - Format - '//' comments and NO Tags BACK - Format - NO 'ifdef' and '/*...*/' comments Migration Formats CONTENTS ═══ 8.1.6. Format - '//' comments and NO Tags ═══ Format - '//' comments and NO Tags Note: Option chosen to insert Short comment and Prototype only. Elimination of tags on commented lines prevents automatic removal of inserted code! // SM$:FO C:\TEST\TEST.C - 03/28/94 14:34:59 /* Open the file with the OF_PARSE flag to obtain the fully qualified * pathname in the OFSTRUCT structure. */ // wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE); wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE); DosOpen (,,,,,,,) DosQueryPathInfo (, FIL_QUERYFULLNAME,,); // OpenFile Cat:030 Type:010 Area:130 // Replace with DosOpen, DosDelete, or DosQueryPathInfo // // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990 // // OF_PARSE Cat:020 Type:030 Area:130 // Use DosQueryPathInfo to replace OpenFile function call // _lclose (wFileTemp); DosClose (wFileTemp); // _lclose replaced with DosClose - Cat:010 Type:010 Area:130 // LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); WinLoadString (,,,,); // LoadString Cat:020 Type:010 Area:060 // Replace with WinLoadString CONTINUE - Format - '//', Short comments and Prototypes BACK - Format - NO 'ifdef' and '//' comments Migration Formats CONTENTS ═══ 8.1.7. Format - '//', Short comments and Prototypes ═══ Format - '//', Short comments and Prototypes // SM$:FO C:\TEST\TEST.C - 03/28/94 14:37:08 /* Open the file with the OF_PARSE flag to obtain the fully qualified * pathname in the OFSTRUCT structure. */ // wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);SM$:O wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE); // SM$:M3 DosOpen (,,,,,,,) // SM$:M3 DosQueryPathInfo (, FIL_QUERYFULLNAME,,); // SM$:M2 // OpenFile Cat:030 Type:010 Area:130 SM$:K // Replace with DosOpen, DosDelete, or DosQueryPathInfo SM$:S // SM$:C // APIRET APIENTRY DosOpen(PSZ pszFileName, PHFILE pHf, SM$:P // PULONG pulAction, ULONG cbFile, ULONG ulAttribute, SM$:P // ULONG fsOpenFlags, ULONG fsOpenMode, PEAOP2 peaop2); SM$:P // APIRET APIENTRY DosQueryPathInfo(PSZ pszPathName, SM$:P // ULONG ulInfoLevel, PVOID pInfoBuf, ULONG cbInfoBuf); SM$:P // APIRET APIENTRY DosSearchPath(ULONG flag, PSZ pszPathOrName, SM$:P // PSZ pszFilename, PBYTE pBuf, ULONG cbBuf); SM$:P // APIRET APIENTRY DosDelete(PSZ pszFile); SM$:P // SM$:C // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990 SM$:1 // SM$:C // OF_PARSE Cat:020 Type:030 Area:130 SM$:K // Use DosQueryPathInfo to replace OpenFile function call SM$:S // SM$:C // APIRET APIENTRY DosQueryPathInfo(PSZ pszPathName, SM$:P // ULONG ulInfoLevel, PVOID pInfoBuf, ULONG cbInfoBuf); SM$:P // _lclose (wFileTemp); SM$:O DosClose (wFileTemp); // SM$:M1 // _lclose replaced with DosClose - Cat:010 Type:010 Area:130 SM$:1 // LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); SM$:O LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); // SM$:R WinLoadString (,,,,); // SM$:M2 // LoadString Cat:020 Type:010 Area:060 SM$:K // Replace with WinLoadString SM$:S // SM$:C // LONG APIENTRY WinLoadString (HAB hab, HMODULE hModResource, SM$:P // ULONG idString, LONG lBufferMax, PSZ pszBuffer); SM$:P See Also: CONTINUE - Format - '/*...*/', Long comments, Prototypes and Examples BACK - Format - '//' comments and NO Tags Migration Formats CONTENTS ═══ 8.1.8. Format - '/*...*/', Long comments, Prototypes and Examples ═══ Format - '/*...*/', Long comments, Prototypes and Examples // SM$:FO C:\TEST\TEST.C - 03/28/94 14:38:42 /* Open the file with the OF_PARSE flag to obtain the fully qualified * pathname in the OFSTRUCT structure. */ // wFileTemp = OpenFile ((LPSTR)szFile, (LPOFSTRUCT)&of, OF_PARSE);SM$:O wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE); // SM$:M3 DosOpen (,,,,,,,) // SM$:M3 DosQueryPathInfo (, FIL_QUERYFULLNAME,,); // SM$:M2 // OpenFile Cat:030 Type:010 Area:130 SM$:K // Replace with DosOpen to open a file. Use DosQueryPathInfo SM$:L // specifying FIL_QUERYFULLNAME to parse the file name. Use SM$:L // DosSearchPath to query the fully qualified path name of a SM$:L // file. Use DosDelete to delete a file. SM$:L // SM$:C // APIRET APIENTRY DosOpen(PSZ pszFileName, PHFILE pHf, SM$:P // PULONG pulAction, ULONG cbFile, ULONG ulAttribute, SM$:P // ULONG fsOpenFlags, ULONG fsOpenMode, PEAOP2 peaop2); SM$:P // APIRET APIENTRY DosQueryPathInfo(PSZ pszPathName, SM$:P // ULONG ulInfoLevel, PVOID pInfoBuf, ULONG cbInfoBuf); SM$:P // APIRET APIENTRY DosSearchPath(ULONG flag, PSZ pszPathOrName, SM$:P // PSZ pszFilename, PBYTE pBuf, ULONG cbBuf); SM$:P // APIRET APIENTRY DosDelete(PSZ pszFile); SM$:P // SM$:C // Windows: SM$:X // OFSTRUCT OFStruct; SM$:X // HFILE hFile = OpenFile ("TEST.DAT", &OFStruct, SM$:X // OF_CREATE); SM$:X // OS/2: SM$:X // HFILE hFile; SM$:X // ULONG ulAction; SM$:X // DosOpen ("TEST.DAT", &hFile, &ulAction, FILE_NORMAL, SM$:X // OPEN_ACTION_CREATE_IF_NEW | SM$:X // OPEN_ACTION_REPLACE_IF_EXISTS, OPEN_ACCESS_READWRITE | SM$:X // OPEN_SHARE_DENYNONE, NULL); SM$:X // SM$:C // LPSTR replaced with PSZ - Cat:010 Type:030 Area:990 SM$:1 // SM$:C // OF_PARSE Cat:020 Type:030 Area:130 SM$:K // Use DosQueryPathInfo specifying FIL_QUERYFULLNAME to SM$:L // query the full path of a file. This replaces the OpenFile SM$:L // function call. SM$:L // SM$:C // APIRET APIENTRY DosQueryPathInfo(PSZ pszPathName, SM$:P // ULONG ulInfoLevel, PVOID pInfoBuf, ULONG cbInfoBuf); SM$:P // _lclose (wFileTemp); SM$:O DosClose (wFileTemp); // SM$:M1 // _lclose replaced with DosClose - Cat:010 Type:010 Area:130 SM$:1 // LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); SM$:O LoadString (hInst, IDS_UNTITLED, sz, sizeof(sz)); // SM$:R WinLoadString (,,,,); // SM$:M2 // LoadString Cat:020 Type:010 Area:060 SM$:K // Replace with WinLoadString SM$:L // SM$:C // LONG APIENTRY WinLoadString (HAB hab, HMODULE hModResource, SM$:P // ULONG idString, LONG lBufferMax, PSZ pszBuffer); SM$:P // SM$:C // Windows: SM$:X // int iLen = LoadString (hInst, 1, szBuf, sizeof(szBuf)); SM$:X // OS/2: SM$:X // LONG lLen = WinLoadString (hAB, hMod, 1, sizeof(szBuf), SM$:X // szBuf); SM$:X CONTINUE - Format - Source code with migration comments removed BACK - Format - '//', Short comments and Prototypes Migration Formats CONTENTS ═══ 8.1.9. Format - Source code with migration comments removed ═══ Format - Source code with migration comments removed /* Open the file with the OF_PARSE flag to obtain the fully qualified * pathname in the OFSTRUCT structure. */ wFileTemp = OpenFile ((PSZ)szFile, (LPOFSTRUCT)&of, OF_PARSE); // SM$:M3 DosOpen (,,,,,,,) // SM$:M3 DosQueryPathInfo (, FIL_QUERYFULLNAME,,); // SM$:M2 DosClose (wFileTemp); // SM$:M1 WinLoadString (,,,,); // SM$:M2 CONTINUE - SMART Files BACK - Format - '/*...*/', Long comments, Prototypes and Examples Migration Formats CONTENTS ═══ 8.2. SMART Files ═══ The SMART generates a number of files related to Analysis and Migration. Also, a set of files may be created as a result of The SMART Editor creating a hyperlink database for the source files processed by SMART. These files are listed below: SMART Dictionary and Migration Database files (one set per directory)  XXXXXXXX.TBL - Dictionary  SMART1DB.D1 - Database  SMART1DB.D2 - Database  SMART1DB.D3 - Database  SMART1DB.D4 - Database  SMART1DB.K1 - Database Analysis and Migration files (in List-of-Files Directory)  XXXXXXXX.LST - List-of-Files  (List-of-Files).RPT - Analysis report  (List-of-Files).LOG - Logfile from The SMART Editor (SLBUILD)  (List-of-Files).RSP - Response File for The SMART Editor (SLBUILD)  (List-of-Files).LNK - Analysis Keyword List  (List-of-FileX).LOG - Logfile from The SMART Editor (SLBUILD) (Migrated files)  (List-of-FileX).RSP - Response File for The SMART Editor (SLBUILD) (Migrated files)  (List-of-FileX).LNK - Migration Keyword List Analysis and Migration Files (in directories with original source files)  XXXXXXXXX.X_X - Migrated Source file with mapped extension  (source file)_^ - Binary analysis data file (one for each source file) The SMART Editor Database Link files and report displays (from DB Build) (in directory with List-of-Files)  SLINK2DB.D1 - The SMART Editor Link Database file  SLINK2DB.D2 - The SMART Editor Link Database file  SLINK2DB.K1 - The SMART Editor Link Database file  SLINK2DB.K2 - The SMART Editor Link Database file  SLINK2DB.K3 - The SMART Editor Link Database file  SL_CALL.RPT - The SMART Editor Call Tree display report  SL_DLGBOX.RPT - The SMART Editor Dialog Template display report  SL_FUNCT.RPT - The SMART Editor Functions List display report  SL_GLOB.RPT - The SMART Editor Globals display report  SL_MODS.RPT - The SMART Editor Files display report  SL_UNREF.RPT - The SMART Editor Unreferenced Functions display report  SL_USER.RPT - The SMART Editor User Links display report (contains keywords found in Migration or Analysis from SMART processes) SMART Resource Translator  resourcefilename.ERR - Default error filename  resourcefilename.HHH - Default generated header filename  resourcefilename.SUM - Default summary filename  resourcefilename.RCX - Default translated resource filename Other SMART Files  MAPEXT.DAT - File extension mapping data (SMART directory). CONTINUE - Specifications and Restrictions BACK - Format - Source code with migration comments removed CONTENTS ═══ 8.3. Specifications and Restrictions ═══ Specifications and Restrictions  Maximum path and file length 255  Maximum Migration Database Path length 47  Maximum directory levels 10  Maximum ifdef name length 40  Maximum "List-of-Files" data 64K (unless created by an editor)  Maximum lines of code in any one file 32767  Maximum code line length 512  Supported preprocessor statements: #if, #ifdef, # if defined, #else, #elseif, #endif  Analysis and Migration- syntax not supported: - Keywords within quotation marks - Keywords within macro define statements - Fields of a structure are not identified for migration - Context of a parameter within a call  Resource Translator (Windows Only) restrictions: - Macros cannot be used for any of the reserved resource definition keywords. - Preprocessor conditional statements must begin and end within a single file. - Preprocessor conditional statements within a DIALOG resource definition template are properly evaluated but are not output to the converted resource file. - #include and rcinclude statements are not recognized within any multiline resource statements. - #define statements are not recognized within any multiline resource statements. - Macro definitions which contain parameter substitutions are currently not processed. - Can either replace the existing files with the converted files or save the converted file with a different file extension. - When converting dialog units as outlined in the Dialog Conversion section the conversion is relative to the system font for the current display resolution. CONTINUE - Technical Support BACK - SMART Files CONTENTS ═══ 8.4. Technical Support ═══ Technical Support Internet: Send questions or comments to devcon@vnet.ibm.com CompuServe: Obtain access to the IBM OS/2 Developer Forum 2. To obtain access to the Developer Connection section, please send a note to CompuServe userid 73423,2767. To access the forum, type GO OS2DF2 at the ! prompt; then select the Developer Connection section. OS/2 BBS: The DEVCON CFORUM, under TalkLink, is a feature under the IBMLink Commercial Services. Customers in the U.S. can call 1-800-547-1283; customers outside of the U.S. should contact their local IBM Marketing Representative. BACK - Specifications and Restrictions CONTENTS