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.

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

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.