home *** CD-ROM | disk | FTP | other *** search
/ TopWare Tools / TOOLS.iso / tools / top1655 / gepackt.exe / README.1ST < prev    next >
Encoding:
Text File  |  1994-03-22  |  9.2 KB  |  255 lines
  1.  
  2.  
  3.                 ┌────────────────────────────────────────────┐
  4.                 │                                            │
  5.                 │   ▀█▀▀▀█                          █▀▀▀     │
  6.                 │    █   █ █▀▀█ █▀▀█ █▀▀█ █  █ █▀▀█ █        │
  7.                 │    █▀▀█▀ █  █ █    █    █  █ █  █ ▀▀▀█     │
  8.                 │    █  █  █▀▀▀ ▀▀▀█ █    █  █ █▀▀▀    █     │
  9.                 │   ▄█  █▄ █▄▄█ █▄▄█ █▄▄█ █▄▄█ █▄▄█ ▄▄▄█  TM │
  10.                 │                                            │
  11.                 │     Copyright APTware Limited 1993,94      │
  12.                 │            All rights reserved.            │
  13.                 │                                            │
  14.                 └────────────────────────────────────────────┘
  15.  
  16.  
  17.  
  18.  Distributor in Europe:
  19.  
  20.       Magic Media Systems GmbH
  21.       Frohnhardter Strasse 79
  22.       D-53639 Koenigswinter (Oberpleis)
  23.       Germany
  24.  
  25.       (Pre-Dial for Germany: "+49" without leading "0")
  26.  
  27.       Tel: 02244/9209-0
  28.       Fax: 02244/81902
  29.       BBS: 02244/5552 or 02244/81901
  30.  
  31.  
  32.  
  33.  Demonstration version
  34.  ═════════════════════
  35.  
  36.  This is a demonstration version of Rescue5, the CA-Clipper 5 decompiler.
  37.  
  38.  To install:
  39.  
  40.  Create a new directory for Rescue5 (unless you want to install
  41.  Rescue5 to an existing directory), move to the new directory and
  42.  copy the self-extracting file RESCUE.EXE into it.  Type:
  43.  
  44.     rescue
  45.  
  46.  The following files will be extracted into the following directories
  47.  (assuming you created the directory \RESCUE5):
  48.  
  49.     \RESCUE5\
  50.      RSQDEMO.EXE   Rescue5 demonstration version.
  51.      VARIABLE.UDT  Default names for unknown variables
  52.      RESCUE5.NG    Documentation in Norton guide format.
  53.  
  54.     \RESCUE5\SAMPLE\
  55.      APTFILER.EXE  Sample session .EXE file
  56.      APTFILER.SRC  Some of the source to APTFILER.EXE
  57.      APTFILER.UDT  User defined type file for APTFILER
  58.      APTFILER.CH   Header file needed to compile APTFILER
  59.      SAMPLE.GRP    Edited grouping and variable files
  60.      SAMPLE.VAR    for the example second pass.
  61.      SAMPLE.LIB    Code required to rebuild APTFILER.EXE
  62.  
  63.  Differences:
  64.  
  65.  This is a dual-mode version of Rescue5:
  66.  
  67.  1) If you follow the sample session in the Norton Guides, this version
  68.     will behave exactly like a full version.
  69.  
  70.     We recommend that you follow the sample session first.  See 'Take
  71.     me though...' in the Norton Guide.
  72.  
  73.     After following the sample session you may decide to rebuild
  74.     APTFILER.EXE, with or without the /b switch, and decompile the
  75.     resulting .EXE.  For the demo version of Rescue5 to recognise the
  76.     new .EXE as the sample system:
  77.  
  78.        o You must edit the .LNK file to link SAMPLE.LIB
  79.  
  80.        o You should link with CA-Clipper version 5.2c
  81.  
  82.        o You must use RTlink or Blinker 2.x.
  83.  
  84.        o You must not change or remove functions or link other code in,
  85.          doing so may prevent Rescue5 from decompiling all the code from
  86.          the new .EXE.
  87.  
  88.     If the demo version of Rescue5 fails to recognise the new .EXE as the
  89.     sample system it will treat it like any other .EXE (see 2) below).
  90.  
  91.  2) If you use this version on any other .EXE file it will decompile
  92.     the module containing the largest non-static procedure or function.
  93.  
  94.     The module recovered will contain the largest non-static procedure or
  95.     function, together with any static procedures or functions that are
  96.     called from it, and any procedures or functions that share static
  97.     variables with it.
  98.  
  99.     In demonstration mode this version will also recover the GETSYS and
  100.     ERRORSYS modules from the EXE specified.
  101.  
  102.     In demonstration mode Rescue5 will ignore the grouping file
  103.     (<EXE name>.GRP) on the second pass, preventing you from moving
  104.     procedures and functions into different modules.
  105.  
  106.     Note that although the demonstration version of Rescue5 only emits
  107.     part of the code, it will decompile all of it.  This means that the
  108.     demonstration version will take the same amount of time to run as the
  109.     full version would take to recover all of your code.
  110.  
  111.  
  112.  In every other respect this is a full working version of Rescue5.
  113.  
  114.  
  115.  
  116.  New / changed features
  117.  ══════════════════════
  118.  
  119.  1) /c switch (Code generation)
  120.  
  121.     A new switch has been created to change the default behaviour
  122.     of the Rescue5 code generator.  This affects grouping, the
  123.     guide section for which is reproduced below:
  124.  
  125.        "A technique that is widely used, code grouping is the
  126.         placing of a comma-separated list of expressions within
  127.         parentheses:
  128.  
  129.         cName := (cust->(dbsetorder(2), dbseek('123')), cust->name)
  130.  
  131.         The expressions are evaluated from left to right, the
  132.         result of the entire group being the value of the last
  133.         expression.  Thus the expression above is the equivalent
  134.         of:
  135.  
  136.         cust->(dbsetorder(2))
  137.         cust->(dbseek('123'))
  138.         cName = cust->name
  139.  
  140.         Under rare circumstances Rescue5 may encounter p-code that
  141.         is ambiguous to the extent that the original code might
  142.         have been grouped or might not.  In these cases Rescue5
  143.         will not group the recovered code."
  144.              ___
  145.  
  146.     Note that the default grouping strategy is now the reverse of
  147.     the one stated in the printed documentation.
  148.  
  149.     It is possible (although very unusual) for Rescue not to group
  150.     code that was originally grouped.  The /c switch forces Rescue5
  151.     to try to group ambiguous code, eliminating errors introduced by
  152.     the default grouping strategy.  /c should be used with caution,
  153.     since it can introduce other problems by causing Rescue to attempt
  154.     to group code that was not originally grouped.
  155.  
  156.     You should only use /c if you encounter a code generation error.
  157.  
  158.  2) Increased memory requirements
  159.  
  160.     Rescue5 now requires about 535K of conventional memory free, but
  161.     is significantly faster with 570K or more.
  162.  
  163.     If you get any memory errors, increase conventional memory first.
  164.  
  165.  
  166.  Known anomalies
  167.  ═══════════════
  168.  
  169.  1) MAIN is sometimes not the first procedure in the .LNK file
  170.  
  171.     Rescue5 sometimes fails to place MAIN first in the list of
  172.     procedures in the .LNK file, resulting in an EXE file that does
  173.     not run.
  174.  
  175.     The workaround is to edit the .LNK file to make MAIN the first
  176.     procedure.
  177.  
  178.     This does not apply to systems in which all the code was
  179.     compiled with the /b switch, which do not have a MAIN.UDF.
  180.  
  181.  2) CA-Clipper reports 'string space exhausted error'
  182.  
  183.     This can occur when compiling source files that contain a very
  184.     large number of string operations.  The CA-Clipper parser
  185.     simply runs out of the memory it reserves for string
  186.     processing.
  187.  
  188.     In every case identified to date, the original source code had
  189.     embedded quotes in strings, which Rescue5 recovers as chr(34)
  190.     string concatenations:
  191.  
  192.  
  193.       Original:
  194.  
  195.          '"This is a fine example", she said'
  196.  
  197.  
  198.       Recovered:
  199.  
  200.          chr(34) + "This is a fine example" + chr(34) + ", she said"
  201.  
  202.     Workarounds include reducing the number of string operations by
  203.     editing the strings, moving some of the strings into another
  204.     source file by splitting the procedures(s) concerend, or trying
  205.     a different memory configuration and/or different version of
  206.     CA-Clipper 5.x.
  207.  
  208.  3) CA-Clipper reports 'too many segments' error
  209.  
  210.     A recovered source file is too large for CA-Clipper to compile.
  211.  
  212.     Although Rescue5 splits files that are becoming too large, it is
  213.     difficult to predict the point beyond which this error will
  214.     occur (it is only indirectly related to the number of lines of
  215.     code and file size).
  216.  
  217.     Workarounds include changing the grouping file to move code
  218.     into another file, using a different /s switch setting or
  219.     manually splitting the file.
  220.  
  221.  4) CA-Clipper reports 'phase error'
  222.  
  223.     Phase errors are caused by some combination of STATIC
  224.     declarations (both variable and procedure).  The precise
  225.     combination varies from version to version, and a source file
  226.     that CA-Clipper 5.01 compiles without a problem may cause
  227.     CA-Clipper 5.2 to choke, or vice-versa.
  228.  
  229.     If a version of CA-Clipper reports a phase error in Rescue5
  230.     recovered code, then that error would also have been reported
  231.     in the original code.
  232.  
  233.     The workarounds are not very precise - change the order of
  234.     STATIC's or assign them at a different point in the program, or
  235.     try a different version of CA-Clipper.
  236.  
  237.  5) CA-Clipper reports 'duplicate procedure name' in ORPHAN.UDF
  238.  
  239.     ORPHAN.UDF is now included in the .RMK and .LNK files (contrary
  240.     to the printed documentation), and it can contain duplicate
  241.     procedure names.
  242.  
  243.     Workarounds include removing ORPHAN.UDF from the .RMK and .LNK
  244.     files, renaming the procedures concerned or distributing the
  245.     duplicate procedures in different source files by editing the
  246.     grouping file.
  247.  
  248.  6) RDD request statements
  249.  
  250.     The REQUEST <rdd> statement is a directive to the linker, not a
  251.     CA-Clipper command.  If your system uses RDD's other than
  252.     DBFNTX you will need to insert the appropriate REQUEST
  253.     statements in the source code in addition to adding the
  254.     appropriate libraries to the .LNK file.
  255.