OPL Wizard ========== Version 1.00 for Nokia 9200 Series Communicator - March 2004 Copyright (C) 2003-4 Roberto Colistete Jr. & Pocket IQ Introduction ------------ OPL Wizard is a freeware tool for OPL programming. It is aimed to help the OPL community develop to Epoc and Symbian OS. OPL Wizard comprises statistics tools, aiding tools to convert OPL code and reformatting tools. Description ----------- Current features of OPL Wizard: - opening of text files in Unicode format, ASCII-DOS and ASCII-Unix; - browsing with many options (full screen and zoom mode, find, go to line, show cursor coordinates, etc); - statistics reports about the OPL source code, in multi-line and CSV formats, with approx. 20 fields (like number of lines, procedures, variables, IF, WHILE, procedure calls to/from, etc); - OPL convert tool that helps the conversion of OPL/nOPL+ source code from EPOC32 to Nokia 9200 Series, EPOC32 to UIQ and Nokia 9200 to UIQ (Series 60, Series 90, etc. in the future) by inserting 'REM' comments pointing to the parts of the code which need rewriting or verification; - saving of the statistics results or converted source code in Unicode or ASCII-DOS format. As OPL Wizard is written in OPL, it is slow for making the statistics report of an OPL source code, the speed is approx. 30 lines per second of source code (for each pass) on a Nokia 9200 Series Communicator. The OPL converting tool reads the source code at a speed of approx. 800 lines*rules per second on a Nokia 9200 machine, so using a converting rule file with 350 rules, the converting of an OPL source code with 1000 lines takes approx. 7 minutes. Such speed is greatly increased if you are running the OPL SDK on a (fast) PC computer. Future features of OPL Wizard, i.e., the To-Do list without any time ordering: - create other converting rules files to support OPL converting between EPOC16, EPOC32, Nokia 9200, Series 60, UIQ, Series 90 and Series 80; - finish the screen browsing code, i.e., optimize the horizontal mouvement of the cursor, recognize tabs for horizontal mouvement and implement scroll bars; - try to interpret nOPL+ comments ('//' and '/* */') and line separator ('\') to allow statistics reports on OPL+ source codes; - in statistics reports, try to recognize constant and variable names along the source code to add some options alerting the programmer which variables are not used or even not declared; - release an Epoc Release 3-5 version of OPL Wizard without the Unicode capability; - try to read native OPL source code, so the programmer does not need to export the source code to text format; - add reformatting of OPL source code: vertical and horizontal spacing, upper and lower case changes, inserting of DECLARE procedures and variables declarations, etc; - add on-line help; - do you have any other ideas ? Freeware version 1.00 for Nokia 9200 Series Communicator and UIQ. Further versions will be ported to Epoc Release 3-5 and Symbian OS 6/7 with Series 60, Series 90 and Series 80. Release History --------------- Version 1.00 (16/03/2004): - first non-Beta version; - first UIQ release, including stylus and jog-dial support; - the initial screen shows the PocketIQ info; - addition of Epoc32(ER5)->UIQ conversion; - date&hour are included in the beginning&end of the statistics report and converted source code; Version 0.50 (29/02/2004): - OPL convert tool is implemented, reading OPL and nOPL+ source codes; - statistics reports are 4% faster; - cursor coordinates are shown on bottom or top position depending on the cursor position; - support for OPL source code using Unicode characters. Version 0.45 (09/09/2003): - the options of Global and PROC's statistics preferences about procedure calls are implemented, giving statistics and listings of procedure calls origins (calls from) and destinations (calls to); - added options to Global and PROC's statistics preferences about unused constants, global and local variables, to be implemented on a future version; - there is an option to run 1, 2 or 3 statistics passes. To be able to list the PROC's calls, it needs 3 passes; - added statistics of LABEL's; - added statistics of BREAK/CONTINUE; - added a 'Find' capability to the 'View' menu pane; - the vertical browsing is optimized (faster) and the horizontal browsing now works; - added a right arrow cursor on the left of the current line; - corrected a small bug when no file was open: the cursor and zoom are now disabled. Version 0.40 (24/08/2003): - first public release to Nokia 9200 Series Communicator. Warning ------- I accept no liability for any data that may be lost using this program. Always take backups of your valuable data, and try to not overwrite the text files when using OPL Wizard to avoid losing OPL source files. The converting rules are based on the current OPL documentation and may contain errors. If you find them please contact the author. Download Zip File Details ------------------------- Go the Internet site of OPL Wizard, www.RobertoColistete.net/OPLWizard or www.PocketIQ.com (in the freeware section), to obtain the last version of the OPLWizard zip file. The zip file for Nokia 9200 should contain the following files: ReadMe.txt (this file) Buffer.SIS (installation file for Buffer.OPX) Convert.SIS (installation file for Convert.OPX) OPLWizardNokia.SIS (installation file for OPL Wizard) Installation ------------ Before installing OPL Wizard, the Symbian Operating System V6.0 OPL Runtime code has to be installed on your Nokia 9200 Series Communicator. You can obtain it from the OPL-Dev project site at http://opl-dev.sourceforge.net/opl9200.html OPL Wizard depends on the Buffer and Convert OPX, so you need them installed before installing OPL Wizard. If you are using the Symbian OS v6.0 OPL SDK to run OPL Wizard on a PC machine, then these OPX are already installed, so do not install the OPX SIS files cited here because they are not targeted to the OPL SDK. From a PC computer, to install OPL Wizard simply double-click the SIS files to install all the required files on the connected Nokia Communicator. At first, the OPX SIS files, then at last the SIS file of OPL Wizard. You can also copy the SIS files directly to your Nokia Communicator machine and open them from the file manager or the control panel "Install/Remove" icon. At first, the OPX SIS files, then at last the SIS file of OPL Wizard. As PocketIQ is not registered with Nokia as a full software agent, you will be warned that "supplier cannot be guaranteed". Just ignore this warning and continue with "Install". To install a new version of OPL Wizard, do not uninstall the previous one ! If you uninstall it, the preferences will be lost. Running OPL Wizard ------------------ Start the program by selecting the 'Extras' application group and then 'OPL Wizard'. The text window is initially clear, so you shall open an OPL text file (previously converted to text Unicode or ASCII-DOS or ASCII-Unix). Now you can browse the OPL text using the common navigation keys and the go to line feature. See the 'View' menu pane. There are also some preferences available in 'Tools/Preferences... Ctrl+K'. Currently, only the statistics report and converting tools are available. The features not available are marked by '(-)'. See the 'Statistics' menu pane to verify the large number of preferences that can be selected. If ok, just select 'Statistics report Shift+Ctrl+S', when the source code will be analysed; the first pass counts the global statistics, and the second pass the procedure statistics. Now you have the statistics report visible, you can save, browse it, switch the view to go back to the OPL source code, etc. See the 'OPL Convert' menu pane to verify the preferences and the OPL convert directions that can be selected (if one direction is not implemented then a dialog shows the missing converting rules file). If ok, just select one of these convert directions and the source code will be converted : REM comments will be inserted pointing to code that needs changes or verification. Now you have the converted source code visible, you can save, browse it, switch the view to go back to the OPL source code, etc. The CBA buttons can be used in a straightforward way. After starting 'OPL Wizard', select the 'Open' button (press Enter) to open the OPL file, then choose the 'Statistics' button (press Enter) to start the statistics report, and finally select the 'Save as' button (press Enter) to save the report to a file. I hope that you find OPL Wizard useful. Suggestions are welcome. Memory usage ------------ After the installation of OPL Wizard, the files in the directory "..\System\Apps\OPLWizard" take 196 KB. OPL Wizard uses 1.0 MB of RAM (after compressing heaps) before opening any OPL source file. For example, to open a OPL file with 2,500 lines and run the statistics report, it needs a total of 1.3 MB of RAM (after compressing heaps). OPL Converting rules files -------------------------- The OPL converting rules files are text files (ASCII-DOS, ASCII-Unix or Unicode) composed by comments and rules, for example : # This line is a comment because it begins with '#' \Mod&: (System.OPX) Mod&:(left&,right&) -> SyMod&:(left&,right&) Syntax : - the rule text has to be in a line starting with '\', and all characters until the end of line (including spaces) are used in the search, that matches whole words only (so 'myMod&:' is not matched); - if the rule text does not use '"' (quotation marks) then the search will exclude any strings from the source code line; - after the '\' line follows the rule description lines that are inserted in 'REM' lines to create the converted source code; - if you want to disable some rule, just edit the converting rules file and put some "#" in the beginning of each disabled line. Epoc32 (ER5) -> Nokia 9200 (348 rules) ++++++++++++++++++++++++++++++++++++++ Read the "\System\Apps\OPLWizard\RulesEpoc32toNokia9200.txt" converting rules file for a complete example. It includes all constants and functions changes from OPXes and the OPL core. Unicode, help and screen size changes are not covered. Epoc32 (ER5) -> UIQ (355 rules) +++++++++++++++++++++++++++++++ The "\System\Apps\OPLWizard\RulesEpoc32toUIQ.txt" converting rules file is a preliminary version based on "RulesEpoc32toNokia9200.txt" with some changes and additions covering UIQ issues. It includes all constants and functions changes from OPXes and the OPL core. Unicode, help and interface design changes are not covered. Nokia 9200 -> UIQ (20 rules) ++++++++++++++++++++++++++++ The "RulesNokia9200toUIQ.txt" converting rules file shows the main issues for porting to UIQ using the current UIQ-OPL-DevPack-2004-02-23. Look at the bug list of OPL for UIQ available on OPL Wiki and SourceForge Symbian OS OPL sites. Interface design changes between Nokia 9200 and UIQ are not addressed by OPL Wizard. The author hopes that the OPL developers will create other converting rules files as well as improve the existing ones and send them to be included in the OPL Wizard distribution. Learning OPL for Symbian OS --------------------------- I suggest the : - download of the "9200-OPL-DevPack-2003-01-01" OPL SDK from the SourceForge Symbian OS OPL site (http://sourceforge.net/projects/opl-dev/) because it includes the "Crystal v6.00 OPL Porting Guide" documentation as well as Epoc32 (ER5) OPL documentation in Win32 help format; - use of the last OPL SDK to develop Nokia 9200, Series 60 or UIQ OPL programs; - study of the documentation and the "DemoOPL" example from the OPL SDK; - study of the "EventCore" OPL skeleton from the FreEpoc site (http://freepoc.org/); - reading of the OPL-Dev project site (http://opl-dev.sourceforge.net/) and its links; - reading of the OPL Wiki site (http://www.allaboutopl.com/wiki/) and its links. Acknowledgements ---------------- I would like to thank the OPL-Dev team for supporting OPL on Symbian OS. The EventCore code and the dpNote section (www.dp.com.my) were very useful, so thanks to Ewan Spence and Martin Harnevie. Also many thanks to the Nokia Product Loan Program for giving me the chance to use a Nokia 9290. Author Support -------------- You can send comments, questions and bug reports to the author, Roberto Colistete Jr., via the email Roberto@PocketIQ.com Visit the OPL Wizard web page on the freeware section of www.PocketIQ.com or www.RobertoColistete.net/OPLWizard for updates.