The Datafile PD-CD 3/PDCD_3.iso/pocketbk/developmen/rvtrn33/REVTRAN.TXT

Text File | 1995-02-16 | 21KB | 469 lines

                           REVTRAN Manual

                   Version 3.3/3.3a, February 1995


Introduction

   Revtran is a program for the Psion Series 3 or 3a, which reverse-
   translates translated programs back into moderately intelligible
   OPL source code.  It is written in OPL, and will run on the
   Series 3/3a, or on Psion's Series 3 or 3a emulators (available
   on CIX) which run on a PC.  Revtran processes both Series 3 and
   Series 3a OPL programs.


Uses

   You might use Revtran on your own programs, e.g. if you have
   lost the source code, or you want to regress to an earlier
   version of a program where you have deleted the earlier source
   code.

   You might use Revtran on someone else's programs, for a variety
   of reasons, for example:

   - to do minor bugfixes, and to make adjustments and improvements
     to a user interface for your own use.
   - to remove features that you don't use, and which are taking up
     space.
   - to understand the data file formats used, so you can read or
     write them from another program.
   - to convert a .OPO to a .OPA or vice versa.
   - to extract, remove, replace or add an icon picture in a .OPA.
   - to convert a Series 3a application to Series 3 (by removing
     Series 3a-specific keywords etc).
   - to learn from others' experience.
   - NOT to hack into authorisation mechanisms etc.!

   NOTE: whatever your reason for using Revtran, please DO NOT
   distribute any modified programs without the original author's
   approval.  See the 'Ethics' section below.


What's new in V3.3

   V3.3 is slightly modified from V3.2, to allow "WHILE"
   statements to be avoided in rare cases where they are
   inferred mistakenly.

   Previous versions fixed problems with IOOPEN, SEND, VECTOR, q-
   code values $7e and $7f, negative single-byte integers, TYPE
   codes, control-structure inference, and 'percentage' operators.


Installation

   You should have unzipped the following files:

   REVTRAN.TXT  This file.

   RVTRN3.OPA   Series 3 version of the program.

   RVTRN3A.OPA  Series 3a version of the program.

   REVTRAN.TBL  A look-up table used by Revtran.

   Put REVTRAN.TBL in a \APP or \APP\REVTRAN directory on disk A, B
   or M.  Put RVTRN3.OPA or RVTRN3A.OPA in any directory, and
   "Install" it from the Sytem screen.

   RVTRN3.OPA will run on a Series 3a in "compatibility mode".
   RVTRN3A.OPA provides identical functionality, but looks slightly
   better.  It is larger mainly because of the larger icon picture.
   Both programs will process Series 3 and 3a .OPO/.OPA files.

   You can rename the .OPA file to anything you like, but
   REVTRAN.TBL must have that name.


Memory/disk space requirements

   You will need about 32k bytes to store the two program files.

   In addition, at run-time Revtran needs up to roughly 30-35k,
   depending on the most complex source-code line being
   reconstructed.

   Also, don't forget you need space for the output file(s).


Running the program

   Start the Revtran application, then choose appropriate items
   from the menus presented, as follows.

   (Open File) This opens a .OPO or .OPA file and checks its basic
   details.  The default directory for input files is \APP, but
   normal Psion dialogs are used when selecting input and output
   files, so you can use Tab or Control-Tab to change directory,
   e.g. to \OPO.  It is also possible to open .IMG, .APP, .ALS,
   .GRP and .PIC files; these contain no translated OPL code, but
   may contain an embedded PIC file (usually an Icon), which
   Revtran can extract.  If you wish to access files in the
   machine's internal ROM, do the following in the "Open input
   file" dialog:

   1. With cursor on the top line, press Control-Tab.
   2. Edit the "Full path" line to show "ROM::".
   3. Press Control-Enter, then scroll the Name selector.

   (Write Icon) If the input file is an OPA and contains an icon
   picture, you should write the picture out to a bitmap (.PIC)
   file if you wish to reconstruct an identical .OPA later, because
   the reverse-translated OPL source will need to make a reference
   to the bitmap file.  Some other file types also have embedded
   PIC files, possibly with multiple bitmaps, not all of which are
   icon-related (e.g. in ROM::WORLD.APP).  You can select which
   bitmaps to write out; e.g. a pair of 48x48 bitmaps to describe
   the black and grey planes of a Series 3a icon, or a 24x24
   bitmap for a Series 3 icon.

   (Write OPL) When you write out reverse-translated OPL, you're
   given the option of adding or discarding an APP..ENDA section,
   by choosing an OPA or OPO module type.  If you keep or add an
   APP..ENDA section, you'll be prompted for the parameters to
   insert (although as many as possible are copied from the
   original by default).  If you put a blank entry in the dialog
   for PATH, EXT or ICON, then that line will be omitted from the
   APP..ENDA section.

   If you choose to alter the 'Text features', you can adjust
   several things.  You can change how new local variable and
   procedure parameter names are invented, but bear in mind that
   you may cause name clashes with global variables.  You can
   choose 'Verbose' comments, so that 'REM' statements will be
   added to the OPL output to record some numerical details which
   may help in debugging a Revtran problem.  You can choose
   Hexadecimal output for all integer literals, although some
   integer literals will be output in hex even if Decimal is
   selected, to ensure that data types are unchanged.  If you find
   that reverse-translated OPL has too many nested levels of
   structure, you can flatten out the
   'ELSE' clauses by choosing 'No ELSE' for the 'ELSE and
   WHILE' item.  If the OPL appears to have missing 'ENDWH'
   statements, this may be due to mis-interpretation of
   poorly-structured code, and you can choose 'No WHILE',
   which will result in 'IF' and 'GOTO' being used to
   achieve the correct behaviour.

   If there is more than one translated procedure, you can select a
   range of procedures to reverse-translate (from 'First proc' to
   'Last proc').  This range defaults to all the procedures in the
   file.  If you specify a 'First proc' number which is larger than
   'Last proc', then all procedures will be skipped, and you will
   just get a REM statement naming each procedure.


Input/Output Files

   When the program runs, it accesses up to three files which you
   specify:

   <your file>.OPO/.OPA (Read, mandatory) The .OPO or .OPA file to
                        reverse-translate, from the M:\APP directory
                        by default.

   <revtran output>.OPL (Write, optional) The new OPL source code
                        extracted from the .OPO/.OPA file, to go in
                        the M:\OPL directory by default.

   <original icon>.PIC  (Write, optional) The extracted icon
                        picture, if one is present inside a .OPA
                        file, to go in the M:\PIC directory by
                        default (M:\PIC will be created if
                        necessary).

   When writing OPL source code for a .OPA, Revtran will also
   prompt you for a filename to go in the ICON command, but Revtran
   will not access that file.


Capabilities and limitations

   Revtran is intended to cope with all the OPL language constructs
   described in the Series 3a Programming Manual (Version 1.0).  It
   will only take as input OPO and OPA files, i.e. those created as
   a result of translating OPL source code.  It cannot process the
   compiled version of 'C' source code etc., e.g. .IMG files.

   If you translate something from, say, English to Japanese, then
   reverse-translate back to English, you'll lose something in both
   directions.  Unfortunately, the situation wi