Tutorial Instructions

It is recommended that this tutorial should be used in conjunction with other help pages available from the "Converter Help Topics" option on the Omnis Studio application O$Converter.lbs "O$Converter" main menu and files provided in the Tutorial folder in the O$Converter package.

1. Copy following source files into from the Source folder into the Pre folder:

  1. Test.lbr
  2. Test.df1
  3. Reusable.lbr

2. Start Omnis 7.3 and open the O7Analyzer library in the Pre folder.

3. Make sure the O7Analyzer menu is installed. If not then install the O7Analyzer.lbr STARTUP menu.

4. Select Analyze... on the O7Analyzer menu.

5. Click the Open... button to open the Test.lbr library in the Pre folder. Note that when you open the Test.lbr in the IDE it initially displays a number of OK messages, if you see them just press the OK button or Return on the keyboard to acknowledge each message. Note that this library has been written to test certain parts of the converter functionality and is not intended as a representative Omnis application.

6. Click the Analyze button to create the analysis datafile O7A_TEST.df1

7. If the Omnnis Utilities menu is not installed on the menu bar then use FileMenusUtilities to install it.

8. Select UtilitiesData File ToolsExamine Data File and note that records have been created in several files.

9. Repeat steps 4 - 8 to analyze the Reusable.lbr and create the analysis datafile O7A_REUSABLE.df1. Note that you should not need to open the Reusable.lbr because there are external references to it in Test.lbr and therefore the O7Analyzer will open it automatically during the analysis of Test.lbr.

10. Use the Format Browser to examine a list of Window formats in the Test.lbr. Note that there is a window called "w called event handler" and this object is one that will be modified during the conversion process.

11. Quit out of Omnis 7 and copy the following files from the Pre folder into the Post folder:

  1. Test.lbr
  2. Test.df1
  3. Reusable.lbr
  4. O7A_TEST.df1
  5. O7A_REUSABLE.df1

12. Start Omnis Studio and open the O$Converter.lbs library in the Post folder. Note that there is another library O$Styles.lbs in the Post folder but you do not need to open that library because it is used internally by the O$Converter to perform certain conversion processing.

13. At this point the "About the Omnis 7 To Studio Converter" window should be open on the screen.

14. Maximize the "About" window and click a module name and press F1 to obtain help for a module. Note that you will need to have copied the contents of the Help folder supplied with the converter into your Omnis Studio>>Help folder for this to work.

15. Any module that is unchecked in the "About" window will not be used when the O$Converter is run. You can take advantage of this to switch off any modules that would perform unwanted processing on your library.

16. Find module "LibraryVariables" in the About window tree list and make sure that it is unchecked so that it will not run.

17. Close the "About" window.

18. Use the Omnis Studio library browser window to open library Test.lbr in the Post folder. Note that on WIndows you may have to change the Files of Type to "*.lbr" to do this.

19. The Omnis Studio IDE will ask you whether you wish to convert the library, answer yes to both questions. Note that this only performs a minimal conversion process at this stage.

20. Now use the Omnis Studio library browser to close the library Test and then make a backup copy of Test.lbs in the Post folder using Windows or Mac/OS. Note that the library file extension was changed by the IDE. The reson for doing this is to enable you to be able to rerun the O$Converter without having to go back and repeat previous steps.

21. Repeat steps 17 - 19 for library Reusable.lbr.

22. Select Conversion Log Options on the O$Converter menu. The window that opens enables you to control what messages are generated by the O$Converter. To avoid a very large log output it is recommended that you should check all options other than "Code fixed by tool" which should be unchecked.

23. Close the "Log Options" window.

24. Select Convert... on the O$Converter menu.

25. Click the Open... button to open the Test.lbs library in the Post folder. Note that the Modules menu on the window is now enabled.

26. Select the Modules menu on the window. Note that the Module_LibraryVariables option is disabled due to the module not being selected to run in the About window.

27. Select Module_CallMethod from the Modules menu on the window. A window opens that lists all the classes in library Test.lbs.

28. Find "mcode" in the list and change the Convert Mode for it to "Code". This will convert menu mcode to a code class and all calls to its methods to use "Do code method" commands.

29. Find "minst" in the list and change the Convert Mode for it to "Instantiated". This will convert all calls to its methods to use "Do $imenus.minst.$fred(p1,p2)" type commands. Note that you need to be careful with this mode of conversion with menus since the calls will only subsequently work if the menu minst is installed on the menu bar (i.e. it is "instantiated")

30. Find "wcode" in the list and change the Convert Mode for it to "Code". This will convert menu wcode to a code class and all calls to its methods to use "Do code method" commands.

31. Find "winst" in the list and change the Convert Mode for it to "Instantiated". This will convert all calls to its methods to use "Do $iwindows.winst.$fred(p1,p2)" type commands. Note that you need to be careful with this mode of conversion with windows since the calls will only subsequently work if the window winst is open (i.e. it is "instantiated")

32. Close the "Classes in library" window and answer "Yes" to the message about saving changes.

33. Press the "Convert" button on the "Select library" window.

34. Answer "Yes" to any messages that follow. Note that you will see a message relating to the conversion of data file O7A_REUSABLE.df1 because it is used during the conversion of Test.lbs.

35. When the processing is complete the Conversion Log window will open and you will be asked whether you want to reopen library Test. Answer No to this question. As general rule it is better not to reopen a converted library at this point because some libraries will cause the log window to be destroyed during their Startup_Task $construct phase and there is no way to recover the log data if this happens.

36. Maximize the Conversion Log window and take a look at the messages. Note that there may be issues that will cause problems in the converted library other than those reported in the log so thorough testing is recommended.

  1. Red messages are errors that could not be fixed by the O$Converter tool and will need to be fixed manually.
  2. Magenta messages are warnings from the tool relating to issues in the library that you may need to fix manually.
  3. Green lines are information messages from the tool.
  4. Black messages relate to issues that were fixed by the tool but you should not have any of these if you set your log options correctly in step 22.

37. In order to keep a copy of the Log for future reference it is recommended that you print it to an HTML file as follows:

  1. Click the "Print log" button on the Conversion Log window toolbar.
  2. Click the HTML icon on the Report Destination window.
  3. Click the "Parameters" tab on the Report Destination window.
  4. Click the "Browse..." button on the Report Destination window.
  5. Browse to locate the Post folder.
  6. Enter the filename TestLog.HTM and press the Save button on the file dialog window.
  7. Click the "OK" button on the Report Destination window to output the file.

38. In order to avoid subsequently accidentally overwriting the log file it is recommended that you immediately change the file path for HTML report output as follows:

  1. Click the "Print log" button on the Conversion Log window toolbar.
  2. Click the HTML icon on the Report Destination window.
  3. Click the "Parameters" tab on the Report Destination window.
  4. Click the "Browse..." button on the Report Destination window.
  5. Enter the filename Temp.HTM and press the Save button on the file dialog window.
  6. Click the "Cancel" button on the Report Destination window to close it.

39. Close the "Conversion Log" window.

40. Close the "Log Options" window.

41. Repeat steps 18 - 38 in order to convert library Reusable.lbs. Leave all classes as Convert Mode "Do not convert" in the Module_CallMethod window. Note that you need to go into this window once for each library prior to converting it even if you do not want to set the Convert Mode for any classes to "Code" or "Instantiated". Type a filename of "ReusableLog.HTM" in order to save the log to an HTML file.

42. Now you can close all open libaries using the "Close library" button on the Omnis Studio IDE libraries window and then reopen library Test.lbs. Answer OK when prompted to convert Test.df1 and you will get a number of OK messages to which you should replay OK.

43. The automated conversion processing is now completed. In a real conversion you would now begin to make manual fixes to the library to deal with issues reported in the conversion log and additional issues found in testing.

44. It is recommended that you run the Method Checker to check for coding errors in your converted library. Run it against the Test.lbr as follows:

  1. Make sure that the Test.lbr library is open.
  2. Click the "Add-On tools" button on the Omnis IDE toolbar (hammer icon.)
  3. Click the "Method Checker..." option on the popup menu.
  4. Double-click the "Test" library in the Method Checker window.
  5. Set the Check Level radio buttons to "Error Conditions".
  6. Click the "Select All Classes" button.
  7. Click the "Check" button to start the method checker.
  8. Note the errors listed in the Method Checker Error Log window.
  9. Double-click the following error line "Encountered a construct element ('Else If #MODIFIED') in an invalid context".
  10. The method editor will open at the selected code line.

45. Have a look at the converted classes in Test.lbs and Reusable.lbs.

  1. Note that the window "w called event handler" is now called "wCalledEventHandler".
  2. Look at window class "wevents" field "field2" method "$event". The event handling code has been converted but the code block "Else If #MODIFIED" and the following 2 lines need to be manually changed to "If #MODIFIED" and an "End if" inserted and the 4 code lines need to be moved to the end of the "On evAfter" block. The completed method should look like this:

     Send to trace log {Field level default handler, method = [sys(85)], events = [sys(84)]}
      On evBefore
       Send to trace log {[sys(85)] - Entering [$cclass().$name] [$cobj().$name]}
 
      On evAfter
       Send to trace log {[sys(85)] - Leaving [$cclass().$name] [$cobj().$name]}
       If #MODIFIED
        Send to trace log {[sys(85)] - Leaving [$cclass().$name] [$cobj().$name]}
        OK message {You have modified the value of the second field}
       End If

46. Because the flexibility of Omnis enables developers to use the product in an infinite number of different ways, each conversion project is unique. The conversion tool has been designed to deal with many situations but it can be adapted to deal with new situations. If there is a problem issue that crops up in a large number of places in the converted library then it may be worthwhile to modify the O7Analyze.lbr and/or the O$Converter.lbs and then rerun the conversion on the original library.