                                  
                           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 with Revtran is
   similar.  Most of the information loss is in the 'translate'
   direction; see the 'differences' sections below.
   
   There are a few arbitrary limits hard-coded into Revtran.  In
   each procedure to be reverse-translated, there can be no more
   than 40 parameters, 200 global declarations, 100 local
   declarations, 100 string declarations (local and global
   combined), 100 different references to other procedures, 100
   different references to external globals, and 1000 commands.  In
   this context, an unconditional jump (whether a 'GOTO' or as a
   translated part of an 'IF..ENDIF' construct etc.) counts as a
   'command'.  Also, any single command, when reverse-translated,
   is limited to 255 characters in length; whether or not this
   limit is breached will be affected by the choice of invented
   names for locals and parameters, and by the indentation string.

   Revtran does not run particularly quickly, even for an OPL
   program, partly because dynamic storage allocation is achieved
   by doing recursive calls to a procedure with a large local
   storage area.  On a Series 3, with all files on the internal
   disk, Revtran processes roughly 400 bytes of input file per
   minute.  On the emulator (EHWIM) running on a reasonably fast
   PC, it achieves about 4k per minute.


Error handling and bugs

   Revtran will check the input file header and refuse to attempt
   reverse-translation if the signature is not "OPLObjectFile**",
   although PIC file extraction is allowed with some other
   signatures.  After that, if Revtran encounters something it
   isn't prepared for in the file, it is likely to raise an error
   message, but not recover very well; please let me know if this
   happens and you can't fix it (but see 'Ethics' section below).
   I know of no bugs at present, but no doubt there are some!  My
   understanding of .OPA/.OPO file content is based mostly on
   guesswork, not hard fact, so I've probably got some
   misconceptions, which will account for some of the bugs.


Technical description

   Translation
   
   After you write an OPL module, you 'translate' it to produce a
   .OPO or .OPA file.  There is no form of security encryption
   involved; the purpose of translation is mainly to create a
   syntax-checked, semi-interpreted, compact version of the source
   code.  The resulting file is mainly a list of procedures encoded
   in 'Q-code', which is executed by a software 'virtual machine',
   the Runtime Interpreter, in the Series 3/3a when you run the
   program.  The Q-code uses stack-based reverse-Polish logic, i.e.
   postfix operators etc.  Each OPL function or command is
   translated to a specific code (one or two bytes usually).  OPL
   control structure keywords (e.g. GOTO, IF..ENDIF, CONTINUE) are
   translated into jumps and conditional jumps.  OPL global
   variable names and procedure names are stored unchanged (in
   upper case).  OPL local variable names and procedure parameters
   are converted to numbered storage locations, and their names are
   lost.  'REM' comments are discarded.  Any ICON picture is
   incorporated in-line.
   
   Reverse-translation
   
   To regenerate OPL from a Q-code file, Revtran first decodes the
   file header, extracting any APP details (perhaps including an
   icon picture).  Then it deals with each procedure, after
   extracting global variables etc., in three passes:
   
   Pass 1:  All the commands, variable assignments and jumps are
            identified (each command potentially invoking functions
            in its parameters), and local variables are found.
   
   Pass 2:  In three sub-passes, by analysing the jumps, the
            original control structure is inferred (this is one of
            the more tricky bits, but it runs quickly).
   
   Pass 3:  Each command is turned into text, with the addition of
            control structure keywords and indentation.  PRINT,
            LPRINT and GPRINT commands, which were translated
            piecemeal, are reconstructed.
   
   During Pass 1 and Pass 3, Revtran needs to know how to decode
   particular Q-code values into the original OPL keywords.  Some
   of this information is included in the Revtran program itself,
   but most of the run-of-the-mill Function and Command keywords
   are decoded by reference to the external table REVTRAN.TBL,
   which was previously generated by MKTABLE.OPO (not included in
   this package of files).  Revtran behaves a bit like a Q-code
   interpreter in these phases, tracking the way that values are
   placed on a stack, and then are replaced by functions and
   removed by commands.
   The heuristics that Revtran uses in Pass 2 are unlikely to be
   foolproof, but have worked on all the test cases I have tried,
   with the exception of a case in which a 'GOTO' just 
   before 'ENDIF' can (rarely) cause a 'WHILE' to be 
   interpreted mistakenly.  If you find any other example 
   which causes 'unexpected UNTIL', 'structure fault' etc., 
   please let me know.


Differences between original and reverse-translated OPL source code

   Any comments in the original OPL are lost.
   Any pre-processor directives (e.g. for HHTRAN or S3ATRAN) are
   lost.
   Indentation and spacing will be different, and there will only
   be one command per line (no use of ":").
   Global and local declarations are made in a different order (all
   the globals then all the locals), but the translated effect
   should be the same.  Storage space for originally declared but
   unreferenced locals will be reserved by new dummy declarations
   which may be of different data types (integers and strings
   only).
   Local variables, procedure parameters and labels all lose their
   original names, and are given invented ones.
   All global variables and procedure names are shown with an 
   initial capital letter, and remaining letters in lower case.
   Data file record field names are shown in upper-case.  Names of
   arrays for use in ADDR or var-parameters are always like
   "arr()", where the original might have used the "arr(1)" form.
   Literal integers may be represented differently, e.g. "$0020"
   would be reverse-translated as "32" (although, if you wish, you
   can turn on Hex output for literals).
   Literal floating-point numbers may be represented differently,
   e.g. "2.323E04" would be reverse-translated as "23230.0".
   Unnecessary brackets in expressions are generally not included;
   operator precedence rules are applied.  The main exception to
   this is that a pair of brackets is always inserted when the '#'
   feature is used for var-parameters.
   Lists of expressions and commas in PRINT, LPRINT and GPRINT
   commands, may be split into a different number of commands, but
   the effect should be the same.
   Any labels which are not jumped to will vanish, and some
   original GOTO commands may be replaced by functionally
   equivalent BREAK, CONTINUE or ELSE/ELSEIF constructs.


Differences between original and re-translated .OPO/.OPA

   If you re-translate Revtran output and compare the result
   against the original .OPO/.OPA, then functionally there should
   be no difference when the program runs, but some of the bytes
   may be different, as follows:
   
   Encoded source line numbers will usually be different.
   The source file pathname may be different.
   You may have changed, removed or added an icon picture.
   There may be other differences if a different translator version
   is used.


Ethics

   Revtran is intended for private use, and must not be used to
   create OPL source code which is subsequently transferred to
   anyone else (whether modified or not, and whether re-translated
   or not).  European law allows reverse-engineering in certain
   reasonable circumstances, but anything sold as a result of
   reverse-engineering is likely to be a breach of copyright.
   
   Regardless of the law, if a software author clearly does not
   want you to see the structure of his program, then it would be
   unethical for you to use Revtran on it.  See also the lengthy
   discussion on the CIX psion/2_series3 topic, starting at
   messages #858 and #903.
   
   If you experience an error (especially "string too long") while
   processing another author's program, this may be because he has
   included code to deliberately exceed one of Revtran's
   limitations.  If the author has explicitly requested that you
   don't reverse-translate, then please don't report the problem to
   me as a bug, as I won't fix it.


Preventing reverse-translation

   Despite the above guidance to software users, some authors may
   wish to prevent users from reverse-translating their code.  The
   simplest approach is to put a polite request to this effect in a
   program's documentation.
   The translation of OPL into .OPA or .OPO is not very secure; the
   process is direct and easily reversible.  The best way to
   acheive good security is to write in 'C' or some other compiled
   language.
   Listed below are some options for improving the privacy of OPL
   programs, but please do not ask me for more details, as I am not
   interested or experienced in defeating Revtran.
   
   1. Modify all procedure and global variable names to make them
   meaningless.  This can be done before translation, or using a
   special program after translation.  If done after translation,
   it is possible to replace alphabetic characters with non-
   printing control characters for greater obscurity.
   
   2. Replace some non-executed parts of the translated program
   with garbage, so that a reverse-translator such as Revtran will
   stumble or crash.  A dedicated hacker will easily overcome this.
   
   3. Find some limit or bug in Revtran, and include code that
   crashes Revtran by exploiting it.  This is unreliable, as a
   future version of Revtran may have bugs fixed, and there may be
   other reverse-translation tools.
   

Distribution and (lack of) support

   I'm distributing Revtran as Smileware - if you use it 
   and like it, then smile :-)  I wrote Revtran largely out 
   of curiosity and to get myself familiar with OPL, rather 
   than to make money.  Even so, you're welcome to send 
   tokens of appreciation if you find it useful!
   I do not promise any user support (try me anyway), but would
   welcome bug reports and constructive criticism.  Why not drop me
   a line anyway as a sort of informal registration.  Please quote
   version number and machine type.
   Revtran is all my own work, and if you use any of the better
   bits of my source code, please credit me as author.  You are 
   welcome to use Revtran on itself (but don't distribute any
   changed version), and if you need access to the original source
   code I will give it and other notes to you for a small or zero
   fee.
   
   You may freely give Revtran to your friends, unmodified and
   including REVTRAN.TXT, but if you wish to make it any more
   public (on a BBS for example), then first check carefully with
   the people who run and use the BBS, and let me know so that I
   have a chance of keeping it up-to-date.
   
   If you want the latest version of Revtran in a hurry, send me a
   cheque for 5 pounds and I'll send you it on an IBM-PC-compatible
   3.5" DD Diskette, or other IBM PC formats if you really prefer.
   If you need it on SSD, write to me and we'll discuss content,
   delivery etc.  You may find the most recent version on CIX, in
   the psion/files topic, or via Internet at src.doc.ic.ac.uk, in
   the /packages/psion/icdoc/development directory.


Copyright etc.

   Revtran is copyright of the author.
   
   You must not use Revtran (source code or executable) for
   financial gain or to infringe other authors' copyright.  It is
   your responsibility to use Revtran within the law.
   
   No warranty is given on this program.  No liability for any
   damage or loss to equipment, data or software will be assumed.
   You use this program at your own risk.
   
   Revtran must not be sold, and may be freely distributed (see
   above) provided that this copyright notice always accompanies it
   unaltered.  Revtran must not be used commercially, but otherwise
   permission is granted for free use of the program and its source
   code in any legal way which does not involve financial gain.
   
   Psion is a registered trademark, and Psion Series 3, Series 3a
   and SSD are trademarks of Psion PLC.  IBM PC is a trademark of
   International Business Machines Corp.


Author

   Mike Rudin
   9, Highfield Rd,
   Coventry
   ENGLAND
   CV2 4GU
   
   Or email me on CIX:
   mrudin@cix.compulink.co.uk


[End of Revtran manual]

