home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 1B / DATAFILE_PDCD1B.iso / _pocketbk / pocketbook / 004 / aka220_zip / AKA2.DOC < prev    next >
Text File  |  1994-08-25  |  8KB  |  218 lines

  1. AKA
  2.  
  3. AKA is a variable compactor for OPL programs developed for Psion
  4. Series 3/3a machines. Variable compaction is the replacement of
  5. long (meaningful) variable names with optimally short (obscure)
  6. ones. Variables in this context includes data variables and
  7. procedure and label names.
  8.  
  9. OPL is an interpreted language and the translator that generates
  10. the intermediate code incorporates into that code the name of
  11. each global variable on each occurrence within the source
  12. program.
  13.  
  14. The use of AKA brings the following advantages:
  15.  
  16.   - Distributed object files (*.OPA and *.OPO) are reduced in
  17.   size; This may be particularly important where the distribution
  18.   medium is an SSD;
  19.  
  20.   - There is no penalty in the use of long mnemonic variable
  21.   names in the source code, and no advantage in using short and
  22.   obscure ones;
  23.  
  24.   - Compacted modules require significantly less working memory
  25.   in the run-time interpreter;
  26.  
  27.   - Compacted modules run slightly faster;
  28.  
  29.   - The use of reverse-translation tools is confounded to a large
  30.   extent, since the code so produced is effectively 'obfuscated'.
  31.  
  32.  
  33. The status of AKA
  34.  
  35. AKA may be distributed freely for personal, non-commercial use,
  36. provided that:
  37.  
  38.  a) no charge is made for the program or its supply, and
  39.  b) the original archive is supplied complete and unmodified.
  40.  
  41. Commercial users of AKA (those creating or distributing software
  42. in expectation of reward) should register the program with Ferret
  43. Information Systems Ltd - further details of registration can be
  44. found in the accompanying file REGISTER.DOC.
  45.  
  46. This document and the programs referred to within it are supplied
  47. in the belief that the contents are correct and they operate as
  48. described, but Ferret Information Systems Ltd. (the company)
  49. shall not be liable in any circumstances whatsoever for any
  50. direct or indirect loss or damage suffered by any person as a
  51. consequence of any fault or defect in any goods or services
  52. supplied by the company and in no circumstances shall the company
  53. be liable for consequential damage or loss arising from the use
  54. or performance of such goods or services.
  55.  
  56.  
  57. What AKA does
  58.  
  59. AKA makes two passes through the set of source files. The first
  60. tabulates all the variables that are not reserved or built-in,
  61. and assigns each its optimally small replacement name (or alias)
  62. based on its category (global or local) and the number of
  63. occurrences of the variable in the source files.
  64.  
  65. The second pass creates the output files - with extension .OPP -
  66. substituting the aliases for the original names. This will
  67. overwrite any existing .OPP files of the same name.
  68.  
  69. A list file tabulating the variable name substitutions and the
  70. likely space saved by compaction is written to a file named
  71. AKA.LIS in the current directory. The estimate of space saved is
  72. a theoretical figure; Various other factors affect the actual
  73. size and padding of translated files.
  74.  
  75. AKA will handle all legal constructs of OPL/mcwa in the source
  76. files. The output files can be translated without prior manual
  77. amendment, as normal OPL source files. See the 'Notes' section,
  78. below, for further guidance.
  79.  
  80.  
  81. Using AKA - preliminaries
  82.  
  83. AKA should be used when program testing is complete and modules
  84. are ready to be built for distribution.
  85.  
  86. In order to be handled by AKA, OPL source files must be
  87. pre-processed using the -p switch to HHTRAN or S3ATRAN. This
  88. removes comments, resolves conditional translation, and performs
  89. token replacement. In most cases this can be done simply by:
  90.  
  91.   hhtran -p *.opl
  92.  
  93. for OPL/mcw, with a similar command for OPL/mcwa. It is
  94. recommended that this step be performed always - even if the
  95. sources make no use of the pre-processor. The resulting files
  96. *.PRP are then transformed by AKA.
  97.  
  98.  
  99. Invoking AKA
  100.  
  101. When AKA starts it expects to find the files AKA.MSG and AKA.DAT
  102. in the same directory as the AKA executable; If these files are
  103. not found it halts forthwith.
  104.  
  105. AKA expects one argument on the command line:
  106.  
  107.   aka sources
  108.  
  109. where 'sources' is either an ambiguous filespec (possibly with
  110. path) or a single filename preceded by an @ sign. The latter is
  111. interpreted as the name of a file (possibly with path) containing
  112. the names of the actual files to process, one per line. The files
  113. named in the @ file may also be pathed.
  114.  
  115. Type just 'aka' for a reminder of the program syntax.
  116.  
  117. Examples:
  118.  
  119.   aka *.prp
  120.  
  121. processes all .PRP files in the current directory and produces
  122. compacted files of the same name but with extension .OPP.
  123.  
  124.   aka @list.fil
  125.  
  126. processes all files named in the file LIST.FIL and creates the
  127. output files with extension .OPP. If a filename in LIST.FIL has
  128. no extension then .PRP is assumed.
  129.  
  130. An @ file containing the names of the files to process may have
  131. blank lines in it - these are ignored. Also ignored is any text
  132. following the pathname and separated by at least one space
  133. character. This can be used to add comments to the @ file.
  134.  
  135. It is possible to invoke AKA with an additional switch (/i or -i)
  136. as the second argument, e.g.
  137.  
  138.   aka *.prp -i
  139.  
  140. in which case AKA stops after the first pass through the source
  141. files and informs of the likely saving from variable compaction.
  142. No output files *.OPP are produced, but the informational file
  143. AKA.LIS is.
  144.  
  145.  
  146. Notes
  147.  
  148. AKA must be presented with syntactically correct post-processed
  149. source files. Furthermore, the set of files must be complete -
  150. that is all variables used must be declared in one of the source
  151. files seen by AKA. This is necessary because AKA performs
  152. variable substitution on a global basis, and cannot track
  153. entities external to the source files.
  154.  
  155. The pre-declared calculator variables M0 - M9 are never
  156. substituted, and existing variables never renamed to one of them.
  157. As a result, the calculator variable usage is not affected by
  158. AKA.
  159.  
  160. In some circumstances it is necessary to prevent a variable, or
  161. variables, from being compacted. This arises where a procedure is
  162. called by its string name using the @(name$): syntax. If such
  163. procedures are not identified, then AKA will change their lexical
  164. name, but cannot change their string name (which is known only at
  165. run-time) and so a 'missing procedure' error will result.
  166.  
  167. To circumvent this problem, create a file called AKA.EXT in the
  168. same directory as the source files. In this file, name, one per
  169. line, those procedures that are called indirectly. Include the
  170. colon character as part of the procedure name. A sample AKA.EXT
  171. file follows; A line with a semicolon in the first character
  172. position is ignored.
  173.  
  174.   ; AKA.EXT for my project - procedures called indirectly
  175.   choicea:
  176.   choiceb:
  177.   choicec:
  178.  
  179. If AKA detects an AKA.EXT file in the current directory, it will
  180. display a message confirming that it is processing that file.
  181.  
  182.  
  183. Limits
  184.  
  185. The current implementation places the following limits on program
  186. use:
  187.  
  188.   - no more than 1024 distinct variable identifiers (excluding
  189.   built-ins) can be processed in a set of source files;
  190.  
  191.   - no more than 90 variables identifiers can be specified in the
  192.   AKA.EXT file of user-defined reserved identifiers;
  193.  
  194. The program will abort if either of these limits is exceeded.
  195.  
  196.  
  197. Messages from AKA
  198.  
  199. AKA produces messages of two kinds - informational and error.
  200. Error messages cause AKA to abandon further processing.
  201.  
  202. Messages of the form:
  203.  
  204.   ! AKA: aborting - error is n Message text
  205.  
  206. indicate an internal error, or the traversal of an implementation
  207. limit. Please inform the author if a message of this type appears
  208. and the reason for it is not obvious.
  209.  
  210.  
  211. --------------------------
  212. David Palmer
  213. Ferret Information Systems
  214. March 1994
  215.  
  216. dpalmer@cix.compulink.co.uk
  217.  
  218.