home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD1.img / d2xx / d232 / resourcedemo / docs / manual.doc next >
Text File  |  1989-08-02  |  172KB  |  3,358 lines
  1.                           ReSource Reference Manual V1.0
  2.  
  3.                            For ReSource V3.05 and later
  4.  
  5.  
  6.  
  7.         Intelligent Interactive Disassembler for Amiga® Programmers
  8.  
  9.  
  10.  
  11.                   Copyright © 1988, 1989 by Glen McDiarmid
  12.                             All Rights Reserved.
  13.  
  14. Copyright Notice
  15.  
  16. ReSource software and documentation are copyright by Glen McDiarmid.  No part
  17. of the software or documentation may be reproduced,  transmitted,  translated
  18. into  other  languages,  posted to a network, or distributed by electronic or
  19. other means without the express permission of the author, or his agents.
  20.  
  21. In an effort to minimize piracy, each copy of ReSource sold  is  individually
  22. assembled and linked.  Complex macros used during  assembly  are  capable  of
  23. creating  literally  millions  of unique code combinations, making it easy to
  24. trace any illegal copies back to the original  purchaser.   Software  thieves
  25. will be prosecuted to the full extent of the law.
  26.  
  27. Disclaimer
  28.  
  29. No responsibility will be  accepted  for  damage  that  may  appear  to  have
  30. resulted  from  the use of this product.  The user assumes all responsibility
  31. in using this product.  The  material  contained  in  this  documentation  is
  32. believed  to  be  accurate,  but  the author reserves the right to update the
  33. software and/or documentation without notice.
  34.  
  35. Distribution
  36.  
  37. ReSource software and documentation are available from:
  38.  
  39.         Glen McDiarmid                  The Puzzle Factory
  40.         28 Marginson Street             P.O. Box 986
  41.         Ipswich, Queensland             Veneta, OR 97487
  42.         AUSTRALIA  4305                 U.S.A.
  43.         (07) 812-2963                   (503) 935-3709
  44.  
  45.  
  46. Update Policy
  47.  
  48. Our update policy is very simple:  For updates  within  a  version  (revision
  49. changes only), we simply ask that you return your original ReSource disk.  If
  50. you  provide  postage  and  a return mailer, we will return it free of charge
  51. with the latest revision of the software.  Otherwise, there will be a  charge
  52. for media and shipping.
  53.  
  54. For major updates, we will  charge  a  nominal  fee.   Please  send  in  your
  55. original ReSource disk and we will ship you the latest version.
  56.  
  57. Trademarks
  58.  
  59. Amiga, AmigaDOS,  Kickstart,  Intuition,  and  Workbench  are  trademarks  of
  60. Commodore-Amiga, Inc.
  61.  
  62. C.A.P.E. 68K, and C.A.P.E. are trademarks of Inovatronics, Inc.
  63.  
  64. FastFonts © by MicroSmiths, Blitzfonts © by Hayes Haugen.
  65.  
  66. [NOTE: Page numbers are  only  shown  in  the  printed  manual.   Also,  this
  67. document  is  an  early  version,  and  there  have  been  some additions and
  68. corrections to the final, printed version.  Sorry!  JL]
  69.  
  70.  
  71. Table Of Contents
  72.  
  73. Introduction . . . . . . . . . . . . . . . . . . . . . . . xx
  74. Getting Started  . . . . . . . . . . . . . . . . . . . . . xx
  75.    System Requirements . . . . . . . . . . . . . . . . . . xx
  76.    The Command Line  . . . . . . . . . . . . . . . . . . . xx
  77.  
  78. Part 1.  Tutorial  . . . . . . . . . . . . . . . . . . . . xx
  79.     1. About the User Interface  . . . . . . . . . . . . . xx
  80.     2. Definition of the Current Line  . . . . . . . . . . xx
  81.     3. Disassembling a Program . . . . . . . . . . . . . . xx
  82.     4. About Menus . . . . . . . . . . . . . . . . . . . . xx
  83.     5. About Keys  . . . . . . . . . . . . . . . . . . . . xx
  84.     6. About Load Files  . . . . . . . . . . . . . . . . . xx
  85.     7. About Data Files  . . . . . . . . . . . . . . . . . xx
  86.     8. About Output  . . . . . . . . . . . . . . . . . . . xx
  87.     9. About Symbols . . . . . . . . . . . . . . . . . . . xx
  88.    10. Display Preferences . . . . . . . . . . . . . . . . xx
  89.    11. About Searches  . . . . . . . . . . . . . . . . . . xx
  90.    12. ARP and Wildcards . . . . . . . . . . . . . . . . . xx
  91.  
  92. Part 2.  Reference . . . . . . . . . . . . . . . . . . . . xx
  93.     1. PROJECT MENU  . . . . . . . . . . . . . . . . . . . xx
  94.         1. Abort . . . . . . . . . . . . . . . . . . . . . xx
  95.         2. Open load file  . . . . . . . . . . . . . . . . xx
  96.         3. Open binary file. . . . . . . . . . . . . . . . xx
  97.         4. Restore file  . . . . . . . . . . . . . . . . . xx
  98.         5. Dismble memory  . . . . . . . . . . . . . . . . xx
  99.         6. Read tracks . . . . . . . . . . . . . . . . . . xx
  100.         7. O'lay binary image  . . . . . . . . . . . . . . xx
  101.         8. Save .RS  . . . . . . . . . . . . . . . . . . . xx
  102.         9. About . . . . . . . . . . . . . . . . . . . . . xx
  103.        10. Quit  . . . . . . . . . . . . . . . . . . . . . xx
  104.  
  105.     2. DISPLAY MENU  . . . . . . . . . . . . . . . . . . . xx
  106.         1. Hiliting (menu) . . . . . . . . . . . . . . . . xx
  107.             1. None  . . . . . . . . . . . . . . . . . . . xx
  108.             2. BSS hunks . . . . . . . . . . . . . . . . . xx
  109.             3. DATA hunks  . . . . . . . . . . . . . . . . xx
  110.             4. CODE hunks  . . . . . . . . . . . . . . . . xx
  111.             5. Chip load hunks . . . . . . . . . . . . . . xx
  112.             6. Fast load hunks . . . . . . . . . . . . . . xx
  113.             7. Reloc32 . . . . . . . . . . . . . . . . . . xx
  114.             8. Symbol scan . . . . . . . . . . . . . . . . xx
  115.             9. Data type uncertain . . . . . . . . . . . . xx
  116.            10. Data type known . . . . . . . . . . . . . . xx
  117.            11. Internally produced refs  . . . . . . . . . xx
  118.         2. Set data type (menu)  . . . . . . . . . . . . . xx
  119.         3. Set numeric base (menu) . . . . . . . . . . . . xx
  120.         4. Decimal conversion (menu) . . . . . . . . . . . xx
  121.         5. Blank lines (menu)  . . . . . . . . . . . . . . xx
  122.         6. Cursor address (menu) . . . . . . . . . . . . . xx
  123.             1. Relative  . . . . . . . . . . . . . . . . . xx
  124.             2. Absolute  . . . . . . . . . . . . . . . . . xx
  125.         7. Titlebar info (menu)  . . . . . . . . . . . . . xx
  126.             1. Filename  . . . . . . . . . . . . . . . . . xx
  127.             2. Attributes  . . . . . . . . . . . . . . . . xx
  128.             3. Accumulator . . . . . . . . . . . . . . . . xx
  129.         8. Wrap  . . . . . . . . . . . . . . . . . . . . . xx
  130.         9. Block-fill  . . . . . . . . . . . . . . . . . . xx
  131.        10. Fill-in data types  . . . . . . . . . . . . . . xx
  132.        11. Fill-in D/T Fwd . . . . . . . . . . . . . . . . xx
  133.        12. Set counter . . . . . . . . . . . . . . . . . . xx
  134.        13. Reset counter . . . . . . . . . . . . . . . . . xx
  135.        14. Flip case - code  . . . . . . . . . . . . . . . xx
  136.        15. Flip case - data  . . . . . . . . . . . . . . . xx
  137.  
  138.     3. SYMBOLS1 MENU . . . . . . . . . . . . . . . . . . . xx
  139.         1. Set Source/dest (Menu)  . . . . . . . . . . . . xx
  140.         2. Object (Menu) . . . . . . . . . . . . . . . . . xx
  141.  
  142.     4. SYMBOLS2 MENU . . . . . . . . . . . . . . . . . . . xx
  143.  
  144.     5. CURSOR MENU . . . . . . . . . . . . . . . . . . . . xx
  145.         1. Remember  . . . . . . . . . . . . . . . . . . . xx
  146.         2. Clear loc stack . . . . . . . . . . . . . . . . xx
  147.         3. Relative (Menu) . . . . . . . . . . . . . . . . xx
  148.             1. Next byte . . . . . . . . . . . . . . . . . xx
  149.             2. Previous byte . . . . . . . . . . . . . . . xx
  150.             3. Next line . . . . . . . . . . . . . . . . . xx
  151.             4. Previous line . . . . . . . . . . . . . . . xx
  152.             5. Next label  . . . . . . . . . . . . . . . . xx
  153.             6. Previous label  . . . . . . . . . . . . . . xx
  154.             7. Next symbol . . . . . . . . . . . . . . . . xx
  155.             8. Previous symbol . . . . . . . . . . . . . . xx
  156.             9. Next section  . . . . . . . . . . . . . . . xx
  157.            10. Previous section  . . . . . . . . . . . . . xx
  158.            11. Next reloc32  . . . . . . . . . . . . . . . xx
  159.            12. Previous reloc32  . . . . . . . . . . . . . xx
  160.            13. Next page . . . . . . . . . . . . . . . . . xx
  161.            14. Previous page . . . . . . . . . . . . . . . xx
  162.            15. Skip forward  . . . . . . . . . . . . . . . xx
  163.            16. Skip backward . . . . . . . . . . . . . . . xx
  164.            17. Next unparsed code  . . . . . . . . . . . . xx
  165.            18. Next D/T change . . . . . . . . . . . . . . xx
  166.            19. Previous D/T change . . . . . . . . . . . . xx
  167.            20. Next uncertain D/T  . . . . . . . . . . . . xx
  168.            21. Next backward reference . . . . . . . . . . xx
  169.         4. Absolute (Menu) . . . . . . . . . . . . . . . . xx
  170.             1. End of file . . . . . . . . . . . . . . . . xx
  171.             2. Start of file . . . . . . . . . . . . . . . xx
  172.             3. Forward reference . . . . . . . . . . . . . xx
  173.             4. Second forward reference  . . . . . . . . . xx
  174.             5. Backward reference  . . . . . . . . . . . . xx
  175.             6. Previous location . . . . . . . . . . . . . xx
  176.             7. Specify offset  . . . . . . . . . . . . . . xx
  177.             8. Specify label . . . . . . . . . . . . . . . xx
  178.             9. Specify symbol  . . . . . . . . . . . . . . xx
  179.            10. Specify percentage  . . . . . . . . . . . . xx
  180.         5. Copy (Menu) . . . . . . . . . . . . . . . . . . xx
  181.         6. Paste (Menu)  . . . . . . . . . . . . . . . . . xx
  182.         7. Swap (Menu) . . . . . . . . . . . . . . . . . . xx
  183.         8. Scrolling speed (Menu)  . . . . . . . . . . . . xx
  184.         9. Normal search (Menu)  . . . . . . . . . . . . . xx
  185.             1. Set search string . . . . . . . . . . . . . xx
  186.             2. Find next occurrence  . . . . . . . . . . . xx
  187.             3. Find previous occurrence  . . . . . . . . . xx
  188.             4. Find nearest occurrence . . . . . . . . . . xx
  189.             5. Search this line  . . . . . . . . . . . . . xx
  190.             6. Search accumulator  . . . . . . . . . . . . xx
  191.        10. Pattern search (Menu) . . . . . . . . . . . . . xx
  192.  
  193.     6. LABELS MENU . . . . . . . . . . . . . . . . . . . . xx
  194.         1. Create single (Menu)  . . . . . . . . . . . . . xx
  195.             1. End-of-line comment . . . . . . . . . . . . xx
  196.             2. Full-line comment . . . . . . . . . . . . . xx
  197.             3. Label . . . . . . . . . . . . . . . . . . . xx
  198.             4. Label - fwd ref . . . . . . . . . . . . . . xx
  199.             5. Symbol  . . . . . . . . . . . . . . . . . . xx
  200.             6. Symbol - dest . . . . . . . . . . . . . . . xx
  201.         2. Edit single (Menu)  . . . . . . . . . . . . . . xx
  202.         3. Replace single (Menu) . . . . . . . . . . . . . xx
  203.             1. Label . . . . . . . . . . . . . . . . . . . xx
  204.         4. Remove single (Menu)  . . . . . . . . . . . . . xx
  205.             1. Label . . . . . . . . . . . . . . . . . . . xx
  206.             2. Symbol  . . . . . . . . . . . . . . . . . . xx
  207.             3. End-of-line comment . . . . . . . . . . . . xx
  208.             4. Full-line comment . . . . . . . . . . . . . xx
  209.             5. All . . . . . . . . . . . . . . . . . . . . xx
  210.         5. Create multiple (Menu)  . . . . . . . . . . . . xx
  211.             1. Reloc32 . . . . . . . . . . . . . . . . . . xx
  212.             2. All . . . . . . . . . . . . . . . . . . . . xx
  213.  
  214.     7. LOCAL MACROS MENU . . . . . . . . . . . . . . . . . xx
  215.  
  216.     8. GLOBAL MACROS MENU  . . . . . . . . . . . . . . . . xx
  217.  
  218.     9. STRINGS MENU  . . . . . . . . . . . . . . . . . . . xx
  219.         1. Get (Menu)  . . . . . . . . . . . . . . . . . . xx
  220.             1. Label . . . . . . . . . . . . . . . . . . . xx
  221.             2. Symbol  . . . . . . . . . . . . . . . . . . xx
  222.             3. Symbol - dest . . . . . . . . . . . . . . . xx
  223.             4. Symbol value  . . . . . . . . . . . . . . . xx
  224.             5. Symbol value - dest . . . . . . . . . . . . xx
  225.             6. End-of-line comment . . . . . . . . . . . . xx
  226.             7. Full-line comment . . . . . . . . . . . . . xx
  227.             8. Search string . . . . . . . . . . . . . . . xx
  228.             9. Filename  . . . . . . . . . . . . . . . . . xx
  229.            10. Save .asm name  . . . . . . . . . . . . . . xx
  230.            11. Save .RS name . . . . . . . . . . . . . . . xx
  231.            12. Macros filename . . . . . . . . . . . . . . xx
  232.            13. Keytable filename . . . . . . . . . . . . . xx
  233.            14. Cursor longword . . . . . . . . . . . . . . xx
  234.            15. Cursor offset . . . . . . . . . . . . . . . xx
  235.            16. Accumulator length  . . . . . . . . . . . . xx
  236.            17. Partial save size . . . . . . . . . . . . . xx
  237.            18. File  . . . . . . . . . . . . . . . . . . . xx
  238.            19. Attribute bits  . . . . . . . . . . . . . . xx
  239.         2. Put label . . . . . . . . . . . . . . . . . . . xx
  240.         3. Put attributes  . . . . . . . . . . . . . . . . xx
  241.         4. Edit functions (Menu) . . . . . . . . . . . . . xx
  242.             1. Clip start  . . . . . . . . . . . . . . . . xx
  243.             1. Clip end  . . . . . . . . . . . . . . . . . xx
  244.             1. Prepend . . . . . . . . . . . . . . . . . . xx
  245.             1. Append  . . . . . . . . . . . . . . . . . . xx
  246.             1. Reverse . . . . . . . . . . . . . . . . . . xx
  247.             1. Lower case  . . . . . . . . . . . . . . . . xx
  248.         5. Operand size (Menu) . . . . . . . . . . . . . . xx
  249.         6. Accumulator (Menu)  . . . . . . . . . . . . . . xx
  250.         7. Maths functions (Menu)  . . . . . . . . . . . . xx
  251.             1. Increment . . . . . . . . . . . . . . . . . xx
  252.             2. Decrement . . . . . . . . . . . . . . . . . xx
  253.             3. Add . . . . . . . . . . . . . . . . . . . . xx
  254.             4. Subtract  . . . . . . . . . . . . . . . . . xx
  255.             5. Multiply  . . . . . . . . . . . . . . . . . xx
  256.             6. Divide  . . . . . . . . . . . . . . . . . . xx
  257.             7. Negate  . . . . . . . . . . . . . . . . . . xx
  258.             8. Logical NOT . . . . . . . . . . . . . . . . xx
  259.             9. Logical AND . . . . . . . . . . . . . . . . xx
  260.            10. Logical OR  . . . . . . . . . . . . . . . . xx
  261.            11. Exclusive OR  . . . . . . . . . . . . . . . xx
  262.         8. Define string (Menu)  . . . . . . . . . . . . . xx
  263.         9. Swap with buffer (Menu) . . . . . . . . . . . . xx
  264.        10. Input buffer (Menu) . . . . . . . . . . . . . . xx
  265.        11. Output buffer (Menu)  . . . . . . . . . . . . . xx
  266.  
  267.    10. SPECIAL FUNCTIONS MENU  . . . . . . . . . . . . . . xx
  268.         1. Repeat last command . . . . . . . . . . . . . . xx
  269.         2. Dos Command . . . . . . . . . . . . . . . . . . xx
  270.         3. Zap . . . . . . . . . . . . . . . . . . . . . . xx
  271.         4. Screen (Menu) . . . . . . . . . . . . . . . . . xx
  272.         5. Set task priority . . . . . . . . . . . . . . . xx
  273.         6. Origin (Menu) . . . . . . . . . . . . . . . . . xx
  274.         7. Convert xx(A4) EA's (Menu)  . . . . . . . . . . xx
  275.         8. Convert specific EA's (Menu)  . . . . . . . . . xx 
  276.         9. Data type set (Menu)  . . . . . . . . . . . . . xx
  277.        10. Convert to.. (Menu) . . . . . . . . . . . . . . xx
  278.        11. Reloc32 (Menu)  . . . . . . . . . . . . . . . . xx
  279.  
  280.    11. SAVE MENU . . . . . . . . . . . . . . . . . . . . . xx
  281.         1. O/P Directory . . . . . . . . . . . . . . . . . xx
  282.         2. Partial save (Menu) . . . . . . . . . . . . . . xx
  283.             1. Set start . . . . . . . . . . . . . . . . . xx
  284.             2. Set end . . . . . . . . . . . . . . . . . . xx
  285.         3. Save binary image (Menu)  . . . . . . . . . . . xx
  286.         4. Save .asm (Menu)  . . . . . . . . . . . . . . . xx
  287.         5. Calculate .asm size (Menu)  . . . . . . . . . . xx
  288.             1. All . . . . . . . . . . . . . . . . . . . . xx
  289.             2. Partial . . . . . . . . . . . . . . . . . . xx
  290.         6. Save to memory (Menu) . . . . . . . . . . . . . xx
  291.         7. Save tracks (Menu)  . . . . . . . . . . . . . . xx
  292.         8. Tabs (Menu) . . . . . . . . . . . . . . . . . . xx
  293.         9. Symbol table (Menu) . . . . . . . . . . . . . . xx
  294.  
  295.    12. OPTIONS1 MENU . . . . . . . . . . . . . . . . . . . xx
  296.         1. Show offsets (Menu) . . . . . . . . . . . . . . xx
  297.         2. Display beep (Menu) . . . . . . . . . . . . . . xx
  298.         3. User feedback (Menu)  . . . . . . . . . . . . . xx
  299.         4. Feedback Delays (Menu)  . . . . . . . . . . . . xx
  300.         5. Labels (Menu) . . . . . . . . . . . . . . . . . xx
  301.         6. Hidden labels (Menu)  . . . . . . . . . . . . . xx
  302.         7. Symbols (Menu)  . . . . . . . . . . . . . . . . xx
  303.         8. End-of-line comments (Menu) . . . . . . . . . . xx
  304.         9. Full-line comments (Menu) . . . . . . . . . . . xx
  305.        10. Chip-load info (Menu) . . . . . . . . . . . . . xx
  306.        11. Section statements (Menu) . . . . . . . . . . . xx
  307.        12. End statement (Menu)  . . . . . . . . . . . . . xx
  308.        13. DCB statements (Menu) . . . . . . . . . . . . . xx
  309.        14. Reference recognition (Menu)  . . . . . . . . . xx
  310.  
  311.    13. OPTIONS2 MENU . . . . . . . . . . . . . . . . . . . xx
  312.         1. ASCII longs (Menu)  . . . . . . . . . . . . . . xx
  313.         2. Short branches (Menu) . . . . . . . . . . . . . xx
  314.         3. Leading zeroes (Menu) . . . . . . . . . . . . . xx
  315.         4. Assembler (Menu)  . . . . . . . . . . . . . . . xx
  316.  
  317.    14. KEY BINDINGS MENU . . . . . . . . . . . . . . . . . xx
  318.  
  319.  
  320. Introduction
  321.  
  322. ReSource was originally just an interactive disassembler, but  Version  3  is
  323. much  more than this.  Because ReSource can get its input from a file, track,
  324. or memory, and output all or part to any of these, it is more  of  a  general
  325. purpose  hacking  tool.  It can be used to browse through files, without ever
  326. bothering to save anything, just to find out what is inside.  It  also  knows
  327. quite a bit about AmigaDOS(TM) and the Amiga® OS.  This built-in intelligence
  328. will  save  you  a  great deal of time when disassembling files.  ReSource is
  329. also blindingly fast.  It is completely written  in  assembly  language,  and
  330. does all text rendering using its own special internal routines.
  331.  
  332. When you run ReSource, you cannot do anything until you give it something  to
  333. work on.  You can supply the name of the file to load on the command line:
  334.  
  335.        1> [run] ReSource c:popcli
  336.  
  337. Alternatively, you can wait until ReSource starts running, and select a  file
  338. using  the  ARP  file  requester.   For  full  specifications on command line
  339. parameters, see below.  Providing that there is enough memory available,  you
  340. can  load  ANY  file into ReSource.  If ReSource recognizes it as a load file
  341. (one that can be run; an executable  program),  it  will  load  the  program,
  342. and perform any necessary relocation, etc., as if the program is going to  be
  343. actually  run.   If  the  file that you request loaded is not a load file, it
  344. will be loaded "as-is".  Load files may be also loaded "as-is", by using  the
  345. "Load  binary" function, in the "PROJECT" menu.  This will give you access to
  346. the hunk, symbol, and relocation information, that  otherwise  gets  stripped
  347. when the program is loaded into  memory.   Libraries,  devices  drivers,  and
  348. fonts  are  also  load files, which means that you can disassemble them, save
  349. the assembler source code, modify them, and re-assemble them.
  350.  
  351. Getting Started
  352.  
  353. If the version/revision of ReSource you have purchased  is  higher  than  the
  354. version  indicated  on  the  title  page  of  this  manual,  please  refer to
  355. "History.doc", an ASCII file on your  ReSource  disk  containing  incremental
  356. documentation.   A  "ReadMe"  file may also be present containing information
  357. about your particular release of ReSource.
  358.  
  359. System Requirements
  360. ReSource is designed to work on any properly  configured  Amiga®  500,  1000,
  361. 2000, or 2500.
  362.  
  363. Kickstart V1.2 or higher is required.
  364.  
  365. Because ReSource uses functions in the "ARP" library, you must have the  file
  366. "arp.library"  in your "LIBS:" directory when you run ReSource.  This file is
  367. supplied with the commercial version of ReSource, and is available from  most
  368. BBS's.  The version of "arp.library" must be 34 or higher.
  369.  
  370. While ReSource will run on a 512K Amiga®, you will be severely limited in the
  371. size  of  programs  that  you may disassemble.  One megabyte of RAM should be
  372. considered the minimum necessary to disassemble all but the smaller programs,
  373. and you will need 1 1/2 to 2 megabytes of  RAM  if  you  want  to  work  with
  374. programs larger than 30-40K.
  375.  
  376. To  make  the  best  use  of  the  menus,  run  FastFonts©,  or  Blitzfonts©.
  377. Otherwise,  scanning through the menus will be very sluggish due to the large
  378. number of sub-items.
  379.  
  380. The Command Line
  381. When you run ReSource from a  CLI,  you  can  supply  a  parameter,  so  that
  382. ReSource  gets  its  input right away.  The following parameters are accepted
  383. with the following meanings:
  384.  
  385.   1> ReSource <ProgName>
  386.      (The executable program <ProgName> will be loaded as a load file
  387.       ONLY if it is a load file.  Otherwise it will  be  loaded  as a
  388.       binary file)
  389.  
  390.   1> ReSource *b <FileName>
  391.      (The file <FileName> will be loaded as a binary image)
  392.  
  393.   1> ReSource *m <Sloc> <Eloc>
  394.      (Load memory, from location <Sloc> to location <Eloc>)
  395.  
  396.   1> ReSource *DFn: <Scyl> <Ecyl+1> [#sec] [Offsec]
  397.      (Load from drive DFn: starting at cylinder  <Scyl> and  continuing
  398.       to <Ecyl+1>.  The default is to read complete track(s).  This may
  399.       be  modified  by  the  next  two optional parameters:  The fourth
  400.       parameter specifies that ReSource  should  read  [#sec]  sectors,
  401.       and the fifth parameter specifies that these sectors should start
  402.       at [Offsec] sector.)
  403.  
  404.   1> ReSource *
  405.      (Kickstart(TM) as it appears in memory is loaded)
  406.  
  407. Examine the following examples:
  408.  
  409.   1> ReSource c:popcli
  410.      (The program "popcli" will be loaded as a load file, from the C: device)
  411.  
  412.   1> ReSource libs:arp.library
  413.      (Load the file "arp.library", from the LIBS: device, as a load file)
  414.  
  415.   1> ReSource *b c:popcli
  416.      (The file "popcli" will be loaded as a binary image, from the C: device)
  417.  
  418.   1> ReSource *m $FC0000 $FD0000
  419.      (The first 64K of Kickstart(TM) will be loaded)
  420.  
  421.   1> ReSource *DF0: 0 0 1
  422.      (The boot sector from DF0: will be loaded, a total of 512 bytes.
  423.       Use this to check for/disassemble viruses)
  424.  
  425.   1> ReSource *DF1: 40 41
  426.      (The entire directory cylinder from DF1: will be loaded, 11K in all)
  427.  
  428.   1> ReSource *m $400 $800
  429.      (For most Amigas®, this will load the Exec library)
  430.  
  431.   1> ReSource *m 0 1
  432.      (Load one byte of memory, at location zero)
  433.  
  434. ReSource may be "Run" without problem, and  multitasks beautifully.  It will
  435. even allow you to change the task priority from inside ReSource.
  436.  
  437. Do not load ReSource from the Workbench(TM).
  438.  
  439.  
  440. Tutorial
  441.  
  442. About the User Interface
  443. Because of the large number of functions in ReSource, it was decided  to  use
  444. one-and  two-character menu names, so that more menus could be used.  Looking
  445. from the left, the first menu is "P", which stands for "PROJECT".   The  real
  446. menu  name  is  directly  under  the  one-or  two-character  name, in capital
  447. letters, so should be fairly easy to find them.  In all future  reference  to
  448. menus,  the full menu name will be used.
  449.  
  450. In the reference section, a heading ending with a ":"  refers to  the  lowest
  451. hierarchical  menu  item  for that function.  In some cases, the heading will
  452. end with a "/:"  to indicate that there are several  sub-items  with  related
  453. functions being discussed under that heading, e.g.:
  454.  
  455.      DISPLAY/Block-fill:   Refers to a single item.
  456.      DISPLAY/Wrap/:        Refers to a group of sub-items.
  457.  
  458. When  describing a function, rather than tell you what key to press to invoke
  459. that function, I'll describe where in  the  menus  you  will  find  it.   For
  460. example,  the  "Quit"  function  would  be  described as "PROJECT/Quit".  The
  461. function to restore the current file would be  "PROJECT/Restore".   You  will
  462. find  both  of  these  under the "PROJECT" menu.  Functions in sub-menu boxes
  463. will be described in a similar way, e.g.,  "SAVE/Tabs/Spaces".   Because  any
  464. key  can  have  any  function bound to it (except "PROJECT/Abort"), key usage
  465. will not be discussed, when  referencing  functions.   However,  to  make  it
  466. easier  to  get  started,  some  key  bindings  will be present, even without
  467. loading a  keytable.   Note  that  loading  a  keytable  may  override  these
  468. keybindings:
  469.  
  470.      up arrow..............................scroll up one line
  471.      down arrow............................scroll down line line
  472.      shift-up arrow........................page backward
  473.      shift-down arrow......................page forward
  474.      right arrow...........................forward reference
  475.      left arrow............................previous location
  476.      right-Amiga Q.........................quit
  477.      right-Amiga O.........................open a file
  478.      
  479. To rebind a key, select "KEY BINDINGS/Rebind key" from the  menus,  select  a
  480. function  from  the  menus to have bound, then press the key that you want it
  481. bound to.  You can overwrite key bindings if you want.  When done, you should
  482. save the keytable as "S:RS.keytable".  This can be  done  by  selecting  "KEY
  483. BINDINGS/Save"  from the menus.  Even both of these functions can be bound to
  484. a key, in fact the only function that is not practical to rebind is "PROJECT/
  485. Abort", which is always bound to right-Amiga A.
  486.  
  487. A sample keytable is provided for your use.  The key mapping used in the file
  488. is described in a file named "MyKeyBindings.doc".  Alternately, you  may  use
  489. the  supplied  program  "ShowKeys"  to  read  your S:RS.keytable at any time.
  490. ShowKeys may be used without parameters or it will accept the pathname  of  a
  491. keytable  as  an optional parameter.  You may want to redirect output to your
  492. printer for hardcopy.
  493.  
  494. Definition of the Current Line
  495. Many functions in ReSource operate only on the current line.   Because  there
  496. is no real "cursor", it is necessary to define the "current line":
  497.  
  498. >> The "current line" is the top line, as you see it on ReSource's screen. <<
  499.  
  500. If there is a section statement (e.g., SECTION BSS) to be  displayed  at  the
  501. cursor  address,  this will be shown before any other text, and will force it
  502. to be shown on the next  line  down.   If  this  is  not  the  first  section
  503. statement  in  the  program, there will be an extra blank line, which will be
  504. shown before the section statement.  After the section statement, and  before
  505. the  rest  of  the  line,  one  or more "full-line comments" can be attached.
  506. Immediately after the cursor line, any "hidden  labels"  will  be  shown.   A
  507. hidden  label may also have a full-line comment attached, which will be shown
  508. immediately before it, but after the cursor line.  Note that in this example:
  509.  
  510.             SECTION prog000000,CODE    ;Section statement
  511.   ;This is a full line comment!
  512.   ;This is another full line comment!
  513.             MOVE.L  D1-D4/A2-A6,-(SP)  ;Line of code
  514.  
  515. all the above text is one line.  Whenever you scroll up or down a  line,  all
  516. parts  of  the  "current  line"  will scroll together, which may sometimes be
  517. visually jarring if there are many extra lines of text attached.  To  put  it
  518. simply,  the  first  "real" line of code or data in the window is the current
  519. line.
  520.  
  521. Disassembling a Program
  522. To disassemble a program is to interpret what went into the program  to  make
  523. it work.  It can be a very complex and trying task, but with practice one can
  524. become quite adept at it.  There are many different and separate things to do
  525. when disassembling.  One of the most important is to separate the  code  from
  526. the  data.   There  is  only one part of a load file that is guaranteed to be
  527. code, and that is at the very start.
  528.  
  529. One very useful function of ReSource is its ability to scan  lines  of  code,
  530. looking  for  references  to  other  parts of the program being disassembled.
  531. When a reference is made, it creates a label at that address, which  will  be
  532. used in all future references to that part of the program.  More importantly,
  533. ReSource  can determine what type of data is being referenced, and be correct
  534. (almost) every time.  If you intend to  reassemble  the  source,  you  should
  535. still  verify  it before saving, as mistakes will occasionally occur.  Before
  536. ReSource makes a decision about what type of data  is  being  referenced,  it
  537. examines  many  different pieces of information that are available, including
  538. the actual instruction that made the reference.  There  are  a  few  ways  of
  539. getting  ReSource  to  scan  lines of code.  The simplest way is by using the
  540. "LABELS/Create single/Label - fwd ref".  This scans only  the  current  line,
  541. and does NOT advance the cursor.
  542.  
  543. If a line of code makes a reference to somewhere  within  the  program,  that
  544. HASN'T  got  a  label  yet,  it  will  be shown as some offset from the label
  545. "START", which is imagined to be (but is not actually, unless YOU  have  done
  546. it)  attached  to  the  first  byte of the program.  You could create a label
  547. called "START", at the first byte of the  program.   However,  when  you  re-
  548. assemble,  there  is a chance that some different length instructions will be
  549. generated.  This will make all references past  the  first  different  length
  550. instruction inaccurate.
  551.  
  552. Another way to get ReSource to scan lines of code is with the  "LABELS/Create
  553. multiple/ALL".   This  function  scans  the  current  line.   If  ReSource is
  554. reasonably sure that it is code, it will scan the line, and move  on  to  the
  555. next  line.   This process will repeat until either the end of file, or until
  556. ReSource believes that the current line may not be code, even though  it  may
  557. currently be displayed as such.  After executing this function, if the cursor
  558. isn't  at  the end of file, and there is more code that hasn't been "scanned"
  559. yet, you can scroll to the start of the next block of code, and execute  this
  560. function again, repeating until all code in the program has been scanned.  At
  561. this point, most references within the program will be to labels, and not use
  562. the  "START+$xxxx" type of reference.  To make sure of this, you can set up a
  563. search for "START+", and perhaps scan the lines individually.
  564.  
  565. There is still another way to scan code, and it may  be  best  when  you  are
  566. first  starting  to  use  ReSource  and  haven't yet learned when to scan the
  567. entire program, and when not to.  First, make the top of the file the current
  568. line.  Then, hold down the left-Amiga key, and while also  holding  down  the
  569. left  mouse  button, scroll through the file until you come to the end.  This
  570. sequence calls the function "LABELS/Create single/Label - fwd ref" repeatedly
  571. and generates labels for all forward references within the file.
  572.  
  573. When all code in a program has been "scanned", the  next  function  that  you
  574. will  generally  want  to use is "DISPLAY/Fill-in data types".  This function
  575. does two passes over the entire program, and does NOT shift the cursor.   The
  576. first pass looks at what data types have been set, and makes some assumptions
  577. about all places in the program where the data type has not been specifically
  578. set.  When you "Set data type", you are telling ReSource "this is  CODE",  or
  579. "this  is  ASCII",  or "these are to be displayed as bytes", etc.  Generally,
  580. this data type will be assumed from this byte forward, until  the  next  byte
  581. that has had the data type specifically set.  Many conditions are tested when
  582. making decisions  about  what type of data is where.  Providing that you have
  583. "scanned" all code in the program, after executing the "Fill-in  data  types"
  584. function the resulting source code will look like source code should look.
  585.  
  586. The second pass in "Fill-in data types" is called "Calculating line  lengths"
  587. in the title bar.  This is used to let ReSource know how far back to go, when
  588. scrolling  backwards.   Also, string lengths are determined during this pass.
  589. When you first load in a file, all line lengths are set to two  bytes.   When
  590. scrolling  forward,  most  things  will  be shown properly anyway, but if you
  591. scroll backwards before first doing a "Fill-in data types", a jarring display
  592. will result.
  593.  
  594. At this point, if you output to a ".asm"  file,  it  will  probably  be  good
  595. enough  to  re-assemble.  However, most people will want to examine the file,
  596. and make it more readable, especially if the program needs  to  be  modified.
  597. An  excellent  place  to  start  is  by finding where any libraries are being
  598. opened, finding where the library base is being stored, and giving meaningful
  599. names  to  these data storage locations.  Assume that the following code is a
  600. small part of a program:
  601.  
  602.                   MOVE.L  4,A6
  603.                   LEA     START+$06B6(PC),A1
  604.                   JSR     -$0198(A6)
  605.                   MOVE.L  D0,START+$0C36
  606.                   BNE.S   START+$06AE
  607.                   MOVE.L  #$00038007,D7
  608.                   JSR     -$006C(A6)
  609.                   BRA.S   START+$06B2
  610.  
  611.                   JSR     START+$0142
  612.                   ADDQ.W  #8,SP
  613.                   RTS     
  614.  
  615.                   BCC     START+$0727
  616.                   ????    
  617.                   BGE     START+$0725
  618.                   BHI     START+$0730
  619.                   BSR     START+$0732
  620.                   ????    
  621.  
  622. After scanning all code in this program, it would look like this:
  623.  
  624.                   MOVE.L  4,A6
  625.   lbC000694       LEA     doslibrary.MSG(PC),A1
  626.                   JSR     -$0198(A6)
  627.                   MOVE.L  D0,START+$0C36
  628.                   BNE.S   lbC0006AE
  629.                   MOVE.L  #$00038007,D7
  630.                   JSR     -$006C(A6)
  631.                   BRA.S   lbC0006B2
  632.  
  633.   lbC0006AE       JSR     lbC000142
  634.   lbC0006B2       ADDQ.W  #8,SP
  635.                   RTS     
  636.  
  637.   doslibrary.MSG  dc.b    'do'
  638.                   dc.b    's.'
  639.                   dc.b    'li'
  640.                   dc.b    'br'
  641.                   dc.b    'ar'
  642.                   dc.b    'y',0
  643.  
  644. Next, "DISPLAY/Fill-in data types" will be used:
  645.  
  646.                   MOVE.L  4,A6
  647.   lbC000694       LEA     doslibrary.MSG(PC),A1
  648.                   JSR     -$0198(A6)
  649.                   MOVE.L  D0,lbL000C36
  650.                   BNE.S   lbC0006AE
  651.                   MOVE.L  #$00038007,D7
  652.                   JSR     -$006C(A6)
  653.                   BRA.S   lbC0006B2
  654.  
  655.   lbC0006AE       JSR     lbC000142
  656.   lbC0006B2       ADDQ.W  #8,SP
  657.                   RTS
  658.  
  659.   doslibrary.MSG  dc.b    'dos.library',0
  660.  
  661. The astute will have noticed that because the A6  register  was  loaded  from
  662. location  4,  it  will  point to the Exec library base.  Therefore, the third
  663. line of this block of code is a call to somewhere in the  Exec  library.   By
  664. scrolling so that this line becomes the top line on the screen, and selecting
  665. the "SYMBOLS/Libraries/Exec", our block of code will now look like this:
  666.  
  667.                   MOVE.L  4,A6
  668.   lbC000694       LEA     doslibrary.MSG(PC),A1
  669.                   JSR     _LVOOldOpenLibrary(A6)
  670.                   MOVE.L  D0,lbL000C36
  671.                   BNE.S   lbC0006AE
  672.                   MOVE.L  #$00038007,D7
  673.                   JSR     -$006C(A6)
  674.                   BRA.S   lbC0006B2
  675.  
  676.   lbC0006AE       JSR     lbC000142
  677.   lbC0006B2       ADDQ.W  #8,SP
  678.                   RTS     
  679.  
  680.   doslibrary.MSG  dc.b    'dos.library',0
  681.  
  682. Checking the documentation for the "OldOpenLibrary" Exec call  will  tell  us
  683. that on return, the D0 register will contain the library base for the library
  684. just opened, if successful.  Because we know that it was the DOS library that
  685. was  opened, the label "lbL000C36" referenced on the fourth line could now be
  686. called "Dos_Base", instead of "lbL000C36":
  687.  
  688.                   MOVE.L  4,A6
  689.   lbC000694       LEA     doslibrary.MSG(PC),A1
  690.                   JSR     _LVOOldOpenLibrary(A6)
  691.                   MOVE.L  D0,Dos_Base
  692.                   BNE.S   lbC0006AE
  693.                   MOVE.L  #$00038007,D7
  694.                   JSR     -$006C(A6)
  695.                   BRA.S   lbC0006B2
  696.  
  697.   lbC0006AE       JSR     lbC000142
  698.   lbC0006B2       ADDQ.W  #8,SP
  699.                   RTS     
  700.  
  701.   doslibrary.MSG  dc.b    'dos.library',0
  702.  
  703. If the D0 register DID contain a non-zero value, it means that  "dos.library"
  704. did  open  successfully,  and the following conditional branch WILL be taken.
  705. Where this branches to, is labeled "lbC0006AE".  A better name for this might
  706. be "DosOpenedOkay".  Scroll so that the line "lbC0006AE JSR lbC000142" is  on
  707. the  top  line of the display, and select "LABELS/Create single/Label".  When
  708. requested, type in "DosOpenedOkay":
  709.  
  710.                   MOVE.L  4,A6
  711.   lbC000694       LEA     doslibrary.MSG(PC),A1
  712.                   JSR     _LVOOldOpenLibrary(A6)
  713.                   MOVE.L  D0,Dos_Base
  714.                   BNE.S   DosOpenedOkay
  715.                   MOVE.L  #$00038007,D7
  716.                   JSR     -$006C(A6)
  717.                   BRA.S   lbC0006B2
  718.  
  719.   DosOpenedOkay   JSR     lbC000142
  720.   lbC0006B2       ADDQ.W  #8,SP
  721.                   RTS     
  722.  
  723.   doslibrary.MSG  dc.b    'dos.library',0
  724.  
  725. If the call to "OldOpenLibrary" was unsuccessful, the  branch  on  the  fifth
  726. line  would  NOT  be taken.  In this case, the D7 register is loaded with the
  727. value "$38007", and a call is made to the  subroutine  at  offset  -$6C  from
  728. where the A6 register is currently pointing.  We do know that the A6 register
  729. was pointing to the Exec library base before, and we also know that  none  of
  730. the  code  executed  so  far  has destroyed the value in A6, so we can safely
  731. assume that A6 still points to Exec library base.   Hence,  by  scrolling  so
  732. that  the  seventh  line of this block is on the top line of the display, and
  733. selecting "SYMBOLS/Libraries/Exec" again, our block will look like this:
  734.  
  735.                   MOVE.L  4,A6
  736.   lbC000694       LEA     doslibrary.MSG(PC),A1
  737.                   JSR     _LVOOldOpenLibrary(A6)
  738.                   MOVE.L  D0,Dos_Base
  739.                   BNE.S   DosOpenedOkay
  740.                   MOVE.L  #$00038007,D7
  741.                   JSR     _LVOAlert(A6)
  742.                   BRA.S   lbC0006B2
  743.  
  744.   DosOpenedOkay   JSR     lbC000142
  745.   lbC0006B2       ADDQ.W  #8,SP
  746.                   RTS     
  747.  
  748.   doslibrary.MSG  dc.b    'dos.library',0
  749.  
  750. After reading the documentation for the Exec call "Alert", we find  out  that
  751. on entry, the D7 register should contain a number representing an alert code.
  752. By scrolling so the the line "MOVE.L #$00038007,D7" is on the top line of the
  753. display,  and  selecting  "SYMBOLS/A-B/Alert codes", our  block will now look
  754. like this:
  755.  
  756.                   MOVE.L  4,A6
  757.   lbC000694       LEA     doslibrary.MSG(PC),A1
  758.                   JSR     _LVOOldOpenLibrary(A6)
  759.                   MOVE.L  D0,Dos_Base
  760.                   BNE.S   DosOpenedOkay
  761.                   MOVE.L  #AT_Recovery!AG_OpenLib!AO_DOSLib,D7
  762.                   JSR     _LVOAlert(A6)
  763.                   BRA.S   lbC0006B2
  764.  
  765.   DosOpenedOkay   JSR     lbC000142
  766.   lbC0006B2       ADDQ.W  #8,SP
  767.                   RTS     
  768.  
  769.   doslibrary.MSG  dc.b    'dos.library',0
  770.  
  771. Examining the include file "exec/alerts.i" will tell us that "AT_Recovery" is
  772. used for recoverable alerts, "AG_OpenLib" means  that  a  library  failed  to
  773. open, and "AO_DOSLib" tells us which library is in question.  Because this is
  774. a  recoverable  alert, the following line of code ("BRA.S lbC0006B2") WILL be
  775. executed, in which case we might change the label  "lbC0006B2"  to  something
  776. like "DosDidntOpen", or "NoDosAvailable".  This is important,  since  if  any
  777. other  code  in  this  program makes a reference to one of the labels that we
  778. have changed, it too will use the new name.  In this example, another part of
  779. the program that WAS:
  780.  
  781.   lbC0007DE       MOVE.L  4(SP),D1
  782.                   MOVE.L  lbL000C36,A6
  783.                   JMP     -$0024(A6)
  784.  
  785.   lbC0007EA       MOVE.L  D4,-(SP)
  786.                   MOVEM.L 8(SP),D1-D4
  787.                   MOVE.L  lbL000C36,A6
  788.                   JSR     -$008A(A6)
  789.                   MOVE.L  (SP)+,D4
  790.                   RTS     
  791.  
  792.   lbC0007FE       MOVE.L  4(SP),D1
  793.                   MOVE.L  lbL000C36,A6
  794.                   JMP     -$007E(A6)
  795.  
  796. now will be shown as:
  797.  
  798.   lbC0007DE       MOVE.L  4(SP),D1
  799.                   MOVE.L  Dos_Base,A6
  800.                   JMP     -$0024(A6)
  801.  
  802.   lbC0007EA       MOVE.L  D4,-(SP)
  803.                   MOVEM.L 8(SP),D1-D4
  804.                   MOVE.L  Dos_Base,A6
  805.                   JSR     -$008A(A6)
  806.                   MOVE.L  (SP)+,D4
  807.                   RTS     
  808.  
  809.   lbC0007FE       MOVE.L  4(SP),D1
  810.                   MOVE.L  Dos_Base,A6
  811.                   JMP     -$007E(A6)
  812.  
  813. After using the function "SYMBOLS/Libraries/Dos" a few times, it would become:
  814.  
  815.   lbC0007DE       MOVE.L  4(SP),D1
  816.                   MOVE.L  Dos_Base,A6
  817.                   JMP     _LVOClose(A6)
  818.  
  819.   lbC0007EA       MOVE.L  D4,-(SP)
  820.                   MOVEM.L 8(SP),D1-D4
  821.                   MOVE.L  Dos_Base,A6
  822.                   JSR     _LVOCreateProc(A6)
  823.                   MOVE.L  (SP)+,D4
  824.                   RTS     
  825.  
  826.   lbC0007FE       MOVE.L  4(SP),D1
  827.                   MOVE.L  Dos_Base,A6
  828.                   JMP     _LVOCurrentDir(A6)
  829.  
  830. To continue, we would replace a few labels:
  831.  
  832.   CloseSUB        MOVE.L  4(SP),D1
  833.                   MOVE.L  Dos_Base,A6
  834.                   JMP     _LVOClose(A6)
  835.  
  836.   CreateProcSUB   MOVE.L  D4,-(SP)
  837.                   MOVEM.L 8(SP),D1-D4
  838.                   MOVE.L  Dos_Base,A6
  839.                   JSR     _LVOCreateProc(A6)
  840.                   MOVE.L  (SP)+,D4
  841.                   RTS     
  842.  
  843.   CurrentDirSUB   MOVE.L  4(SP),D1
  844.                   MOVE.L  Dos_Base,A6
  845.                   JMP     _LVOCurrentDir(A6)
  846.  
  847. Okay, so far so good.  Now, where the line:
  848.  
  849.                   JSR     lbC0007FE
  850.  
  851. used to be, it would be replaced by:
  852.  
  853.                   JSR     CurrentDirSUB
  854.  
  855. This happens automatically, whenever you  replace  any  label.   The  process
  856. helps itself; starting is hardest, the rest come fairly easily.
  857.  
  858. In general, where a label is used, if you have any idea of what is  happening
  859. at  all,  you should replace it with a label that will remind you of what the
  860. code is doing.  It doesn't matter what name you use (as long as it is a legal
  861. label for the assembler that you plan to use); if necessary you  can  replace
  862. it  with  something  better  later  on.   Anything nominally mnemonic will be
  863. superior to a "shop" label while you're trying to understand the code.
  864.  
  865. One last point that needs to be covered briefly is the cursor location stack.
  866. When  certain  functions  are  called,  or  whenever YOU want to, the current
  867. cursor loacation may be pushed onto ReSource's  location  stack.   This  will
  868. allow  you  to easily move around in code.  Returning to our example program,
  869. place the second line, at label lbC000694,  on  the  cursor  line,  and  then
  870. select  "CURSOR/Absolute/Forward  reference".   The last line will move up to
  871. the cursor line.  You can now use "LABELS/Create single/Label" to change  the
  872. name  "doslibrary.MSG"  into  something more meaningful, like "DosName".  Now
  873. use "CURSOR/Absolute/Previous location", and you will find yourself  back  at
  874. the second line of the file, with a new name for the first operand.  Normally
  875. you will just use right-Arrow, and left-Arrow for these two functions  rather
  876. than using the menus.
  877.  
  878.                   MOVE.L  4,A6
  879.   lbC000694       LEA     doslibrary.MSG(PC),A1
  880.                   JSR     _LVOOldOpenLibrary(A6)
  881.                   MOVE.L  D0,Dos_Base
  882.                   BNE.S   DosOpenedOkay
  883.                   MOVE.L  #AT_Recovery!AG_OpenLib!AO_DOSLib,D7
  884.                   JSR     _LVOAlert(A6)
  885.                   BRA.S   lbC0006B2
  886.  
  887.   DosOpenedOkay   JSR     lbC000142
  888.   lbC0006B2       ADDQ.W  #8,SP
  889.                   RTS     
  890.  
  891.   doslibrary.MSG  dc.b    'dos.library',0
  892.  
  893. About Menus
  894. The menus in ReSource fully support drag-selecting, and  multiple  selection.
  895. Many  options  within  ReSource have a "checked" menu, which in most cases is
  896. "hot".  This means that even though ReSource may be busy doing something,  if
  897. you make a selection in the menus that effects the current operation, it will
  898. take  effect  IMMEDIATELY.   For  example,  while saving the source code to a
  899. ".asm" file, if you select "OPTIONS 1/Symbols/Off", from that point  on,  the
  900. output  file will not show any symbols.  Similarly, if you selected "OPTIONS/
  901. DCB statements/On" during the save, DCB  statements  would  be  used  in  the
  902. output  file  from that point on.  This feature is handy during the execution
  903. of macros, as you will see in the section on macros.
  904.  
  905. About Keys
  906. As mentioned previously, any function except the "PROJECT/Abort" function can
  907. be bound to any key.  All non-qualifier keys can be used, with or without any
  908. of the following combinations of qualifier keys:
  909.  
  910.      shift - left or right, or caps lock, all treated as one
  911.      alt   - left or right, both treated as one
  912.      ctrl   shift-ctrl   alt-ctrl   shift-alt   shift-alt-ctrl
  913.      left-Amiga          right-Amiga
  914.  
  915. For example, to rebind the "Open load file" function to right-Amiga O, select
  916. "KEY REBINDINGS/Rebind key", then select "PROJECT/Open load file", then press
  917. and hold down the right-Amiga key, press and release the "O" key, and finally
  918. release the right Amiga key.  From then on, instead of using  the  menus  for
  919. opening  a  file,  you  could just press right-Amiga O.  To make this binding
  920. permanent, you would save the  current  bindings,  to  a  ReSource  KEYTABLE.
  921. Select  "KEY  BINDINGS/Save",  and type in the name of a file to save the key
  922. bindings to.  If you want these bindings used every time  you start ReSource,
  923. you need to save the key bindings as "S:RS.keytable".
  924.  
  925. With many programs, when you press and hold  down  the  down  arrow  key,  to
  926. scroll  down, a backlog of key repeats will form, making it difficult to stop
  927. the scrolling, even after releasing the offending key.  Where this would be a
  928. problem, the repeats are flushed, making key control better.
  929.  
  930. About Load Files
  931. There are five functions that deal with loading.  These are:
  932.  
  933.     "PROJECT/Open load file"
  934.     "PROJECT/Open  binary  file"
  935.     "PROJECT/Restore"
  936.     "PROJECT/Dismble memory"
  937.     "PROJECT/Read tracks"
  938.  
  939. The first of these will examine the start of the file, to check if it  is  an
  940. Amiga®  load  file.   Amiga®  load  files  include  all  executable  programs
  941. (excepting those using overlays), libraries, device drivers, and fonts.  With
  942. this type of load, ReSource examines, then strips out, all hunk,  relocation,
  943. and  debug  symbol  information.   This  information  is not lost, it is used
  944. internally to ReSource, to make better decisions about data type setting, etc.
  945.  
  946. ReSource was designed with speed as the PRIMARY objective.  It  is  does  not
  947. use  memory  sparingly.   To load a file, ReSource sometimes requires a great
  948. deal of memory, especially when disassembling large files.  For any file, the
  949. approximate memory requirement will be 6 to 10 times the  file  size.   As  a
  950. further  requirement, much of this is required to be contiguous.  ReSource is
  951. NOT practical on a 512K machine.  If you have 2 Megs of fast memory, you will
  952. be able to disassemble most programs.  Users with 1 Meg  machines  will  feel
  953. constrained  when  attempting  to  disassemble 30-40K executables, but should
  954. have little difficulty with programs smaller than this and most C: programs.
  955.  
  956. Any  debug  symbols will be shown as labels in their proper places within the
  957. program, and even the relocation information is available.  For  example,  if
  958. you  select  "DISPLAY/Hiliting/Reloc32",  any relocated pointers are hilited.
  959. When disassembling, this information is quite valuable, as it  helps  you  to
  960. tell  where  code is, where tables of pointers are, etc.  ReSource also makes
  961. heavy use of this information in many functions, and this is one of the  main
  962. reasons  that  it  is  so accurate in determining data types, especially when
  963. telling code from  ASCII.   The  hunk  information  also  tells  you  whether
  964. something was meant to load into chip memory, which immediately lets you know
  965. that it is probably graphics or sound data.
  966.  
  967. If a program has the debug symbols left in it,  it  makes  the  disassembling
  968. process  much  easier.  When the file is loaded, for each debug symbol found,
  969. if it is nine characters long, starts with "lb", and is followed by an  upper
  970. case "A", "B", "C", "L", or "W", at the point that the label is attached, the
  971. data type will immediately be set to ASCII, bytes, code, longwords, or words,
  972. respectively.  Additionally, local labels, of the "1$"  variety,  and  labels
  973. ending in "SUB" are recognized as code,  and  labels  ending  in  ".MSG"  are
  974. recognized as ASCII.
  975.  
  976. Thus, if you have to disassemble a program that you previously  disassembled,
  977. then  reassembled, most of the data types will be set for you, as the file is
  978. loaded.
  979.  
  980. There is one other type of file that can be  loaded  in  using  "PROJECT/Open
  981. load file", the ReSource data file, or ".RS" file.  It is discussed in detail
  982. in another section.
  983.  
  984. If  ReSource   cannot  load  the  file  as  an  Amiga®  load  file,  it  will
  985. automatically attempt to load it as a binary file, without looking for  hunk,
  986. relocation,  and debug symbol information.  If it is an Amiga® load file, but
  987. has been corrupted, ReSource will refuse to load it.  You can still load  it,
  988. however,  using the "PROJECT/Load binary file" function.  With this function,
  989. you can load any file that will fit into available memory.  This is handy for
  990. disassembling operating systems, or text files.  In the case of normal Amiga®
  991. load files, you may wish to examine the hunk information in them.
  992.  
  993. The "PROJECT/Restore" function will attempt to load the same  file  that  you
  994. loaded last, this is useful when you make a mess of things, and just want  to
  995. start again.  The restore function is only usable when you loaded a file, NOT
  996. when  you  disassemble  memory  directly,  or read tracks from a floppy disk.
  997. This will be fixed in a future version.
  998.  
  999. When you are asked to select a file using the file requester, you may  cancel
  1000. the  load  immediately,  and  retain the current file.  If you hit the "okay"
  1001. gadget, and the file is not successfully loaded, (perhaps because it  is  too
  1002. large  for  available  memory), you have lost your current file.  If, at this
  1003. time, you select "cancel", ReSource will give you the chance to quit, in case
  1004. you cannot or are unwilling to load any file.  If you  don't  quit,  ReSource
  1005. will  again  offer  the  file  requester,  where  you  may  select  a file to
  1006. disassemble.
  1007.  
  1008. About Data Files
  1009. The ReSource data file, or ".RS" file, is a file containing most of the  data
  1010. areas  internal  to  ReSource,  while any particular file is loaded.  This is
  1011. used to save your work, and later load it back  into  ReSource,  so  you  can
  1012. continue  disassembling a program some other time, without losing any of what
  1013. you have already done.  You could even send this file to a  friend,  assuming
  1014. that  he/she  has  purchased ReSource.  This should be particularly useful in
  1015. disassembling  the   Amiga®   operating   system,  (Kickstart(TM)),   as  the
  1016. Kickstart(TM) ".RS" file does not contain any copyrighted  material,  and  so
  1017. can be legally distributed.  This is only true for Kickstart(TM) ".RS" files.
  1018. The  executable  must  be  cleared  before  you distribute ".RS" files of any
  1019. program that is not in the Public Domain.  See "PROJECT/O'lay  binary  image"
  1020. in the reference section.  Be aware that you will require at least  two  megs
  1021. of  fast memory to load a Kickstart(TM) ".RS" file.  Even the cursor position
  1022. is saved in a .RS file, making it easy for you  to  remember  what  you  were
  1023. doing  last when you saved the ".RS" file.  The ".RS" file is only recognized
  1024. with "PROJECT/Open load file", not the "PROJECT/Open binary  file",  although
  1025. you may load it as a binary image if you want.
  1026.  
  1027. It is the content of the file that allows ReSource to recognize a ".RS" file,
  1028. not  the  name  of  the  file.  However, the file should have an extension of
  1029. ".RS", so it is immediately recognizable by humans as a ReSource data file.
  1030.  
  1031. To save your work (it doesn't matter how you loaded it), select "PROJECT/Save
  1032. .RS", and select a filename to save to.
  1033.  
  1034. About Output
  1035. Eventually, after disassembling a program, you will probably want to save  it
  1036. as  a  text  file,  that  you  will  later assemble, perhaps after doing some
  1037. modifications.  By using the "SAVE/Save .asm" function, the entire  file  can
  1038. be  saved  as  a text file, exactly as you see it on the screen.  If you only
  1039. wish to save part of the file, use "SAVE/Save .asm/Partial".
  1040.  
  1041. Another output function is "SAVE/Save binary image".  One use for this is  to
  1042. perform modifications to a file, by overwriting the current information.  For
  1043. example,  if  you  have  a  program that has some annoying feature, you could
  1044. quickly find the offending code with ReSource, then simply overwrite it  with
  1045. "NOP"  instructions.   You  may  use  "SPECIAL  FUNCTIONS/Zap" to enter "NOP"
  1046. opcodes as "'Nq" or "$4E71".  Look up the hex values  of  any  other  opcodes
  1047. that you may need.  Once this has been done, select "SAVE/Save binary image",
  1048. and  you  can  use  the  file immediately, without going through the complete
  1049. disassemble/re-assemble/link process.
  1050.  
  1051. To find out how large the output .asm file will be,  you  can  select  "SAVE/
  1052. Calculate .asm size/ALL".  This will tell you the output size, in bytes, K's,
  1053. and as a percentage of a floppy disk (which may be larger than 100%).  If you
  1054. change any of the options, it will most probably have some effect on the size
  1055. of the output file.  To make the output .asm file smaller, most things in the
  1056. "OPTIONS"  menu  should be switched OFF, except for "DCB instructions", which
  1057. if used, can shrink the size of a .asm file considerably, especially if there
  1058. are large data areas.  Either real tabs (ASCII value 9) or spaces may be used
  1059. in the output file.  Selecting  "SAVE/Tabs/Real  tabs"  will  also  make  the
  1060. output file size smaller, as will "DISPLAY/Blank lines/None".  If the size of
  1061. the output file is not a problem, then set these options to suit your tastes.
  1062. Another way to deal with limited space for .asm files, is to save them as two
  1063. or more partial files using "SAVE/Save .asm/Partial" repeatedly.
  1064.  
  1065. Before  leaving  this section, a brief look at how ReSource achieves its fast
  1066. screen output is in order.  All  text  that  is  displayed  on  the  ReSource
  1067. screen,  except  that  which  is  done  for the menus by Intuition, uses text
  1068. rendering routines internal to ReSource.  This makes text rendering extremely
  1069. fast, but also means that  the  font  can't  be  easily  changed.   The  text
  1070. rendering routines were  originally  inspired  by  Warptext  II.   The  major
  1071. difference here is that four characters instead of one are  rendered  in  the
  1072. main  loop.   This  has the obvious benefit of increasing speed of rendering,
  1073. but is also the reason why the start and end of hilited areas  are  sometimes
  1074. displaced by up to 3 characters.  For efficiency, large cleared  areas  (such
  1075. as  the  first  tab  in  a  line)  are handled by separately.  The blitter is
  1076. currently not explicitly used in ReSource at all. 
  1077.  
  1078. About Symbols
  1079. When you create a symbol, unless you have set "SAVE/Symbol table" to  "None",
  1080. the  symbol  and  its  value  will  be  stored, so that a symbol table can be
  1081. created at the beginning of the output source code file.  This  symbol  table
  1082. can take the form of an equate table, e.g.:
  1083.  
  1084.      AG_OpenLib      EQU     $00030000
  1085.      AO_DOSLib       EQU     $00008007
  1086.      AT_Recovery     EQU     $00000000
  1087.      _LVOAlert       EQU     $FFFFFF94
  1088.      _LVOClose       EQU     $FFFFFFDC
  1089.      _LVOCreateProc  EQU     $FFFFFF76
  1090.      _LVOCurrentDir  EQU     $FFFFFF82
  1091.  
  1092. Alternatively, it can take the form of an "XREF" table, e.g.:
  1093.      
  1094.                      XREF    AG_OpenLib
  1095.                      XREF    AO_DOSLib
  1096.                      XREF    AT_Recovery
  1097.                      XREF    _LVOAlert
  1098.                      XREF    _LVOClose
  1099.                      XREF    _LVOCreateProc
  1100.                      XREF    _LVOCurrentDir
  1101.  
  1102. The symbol table is also stored in a ".RS" file.  When it is time  to  create
  1103. the  .asm  file,  you can select either "EQU" or "XREF" as the type of symbol
  1104. table to create.  Even though you may create many symbols with the same name,
  1105. the symbol table will contain only one entry for each symbol.  Thus, it  will
  1106. correctly assemble with most assemblers.  If you select the "None" option, no
  1107. symbol table will be generated.
  1108.  
  1109. Display Preferences
  1110. To  cater  to  different  tastes,  the  manner  in  which  ReSource  displays
  1111. information  may  be varied dramatically.  Overlong lines may or may not wrap
  1112. around, code may be shown in upper case, or lower  case.   Data  declarations
  1113. may  be  shown  in upper case or lower case.  You may have blank lines appear
  1114. after conditional branches, after all branches, after system calls,  or  none
  1115. at  all.   Any  number may be shown in hexadecimal, decimal, binary, or ASCII
  1116. if within the required range.  Leading zeroes may be  suppressed,  or  shown.
  1117. Numbers  below 10 in value, or below 16 in value may be globally converted to
  1118. decimal, or there may be no conversion.  Each line that doesn't start with  a
  1119. label  may  instead  show  the  current  offset.  Section statements, the END
  1120. statement, labels, hidden labels, symbols, and  two  types  of  comments  may
  1121. individually be set ON or OFF at any time.  The settings of these options can
  1122. be  made permanent by selecting the required functions in Macro #19 (the last
  1123. local macro), and saving the macro table as "S:RS.macros".  See  the  section
  1124. on macros for more information.  Selecting  "OPTIONS 1/Labels/Off"  does  NOT
  1125. remove  any  labels,  it simply stops them from being shown, until you select
  1126. "OPTIONS 1/Labels/On".  For example, you might wish to search for "lbC" as  a
  1127. string inside a comment, and unless you turn labels off,  you  will  have  to
  1128. spend  a  long  time searching for the real target, as many labels will start
  1129. with "lbC".
  1130.  
  1131. About Searches
  1132. ReSource has some very powerful search functions.   You  may  select  from  a
  1133. normal search, or a pattern search.  You may  search  forward, backward, or a
  1134. special  combined  search, that searches in both directions at the same time,
  1135. which will find the "nearest" occurrence of the search string.   For  use  in
  1136. macros, you can also search just the current line, or the accumulator.
  1137.  
  1138. The text that you see on the display will be the text that is searched.   For
  1139. the purpose of searches, tabs are set to real tabs, not spaces.  Thus, if you
  1140. wish to search for:
  1141.  
  1142.              MOVE.L  #100,D0
  1143.  
  1144. you would press "tab" where you see spaces in the above line.  When using the
  1145. pattern search, the wildcards are  those  used  in  all  ARP  programs.   For
  1146. completeness, they are repeated here.
  1147.  
  1148. ARP and Wildcards
  1149. ARP has an extensive set of wildcards, and most ARP programs allow them to be
  1150. used.  ARP supports ALL of the AmigaDOS(TM) set of wildcards, as well as  the
  1151. more  standard  Unix style of wildcards.  ARP supports the following wildcard
  1152. characters.  Note that these are valid inside or out of quotes:
  1153.  
  1154.  
  1155.      (a|b|c)   Will match one of a, b or c.  These can be patterns.
  1156.  
  1157.      ? Matches any single character
  1158.      #<pat>   Pattern repeated 0 or more times,
  1159.               in particular, #? matches anything.
  1160.  
  1161.      [char]   A set of characters, for example,
  1162.               [abc] or [a..c] specify the same set.
  1163.  
  1164.      [^char]   Match everything but this set of characters.
  1165.  
  1166.      *         0 or more occurrences of any character.
  1167.  
  1168. These can be used in combination, of course, so that *.(c|h) or  *.[ch]  will
  1169. match  any  filenames  ending  in  either .c or .h proceeded by any number of
  1170. characters, including no characters.
  1171.  
  1172. For example, if you want to search for "JSR"  or  "BSR",  you  could  specify
  1173. "?SR"  as  the  search pattern, and you would use the pattern search, not the
  1174. normal search.  Here are some more examples:
  1175.  
  1176.   lb[ABCWL] would find any occurrence of "lbA", "lbB", "lbC", "lbW", or "lbL"
  1177.   "lbM" would NOT constitute a valid match.
  1178.  
  1179.   J(MP|SR)  -$????*(A6*) would get a match on the following lines:
  1180.  
  1181.   JMP  -$00C6(A6)
  1182.   JSR  -$00C6(A6)
  1183.   JSR  -$01FE(A6)
  1184.   JMP  -$FFFF(A6)  but not on the following lines:
  1185.  
  1186.   JMP  $00C6(A6)
  1187.   JSR  -$00C6(A5)
  1188.   JSR  $1FE(A6)
  1189.   JMP  (A6)
  1190.  
  1191. Note that a  real tab  character  was  used  above,  between  "J(MP|SR)"  and
  1192. "-$????*(A6*)".  During a search, it is unimportant whether tabs are  set  to
  1193. real tabs or spaces.
  1194.  
  1195. Reference Section
  1196.  
  1197. 2.1.1       PROJECT/Abort:
  1198. Use this to abort searches and macros.  This is the only function in ReSource
  1199. which should NOT be bound to a different key.  It  is  permanently  bound  to
  1200. right-Amiga A, for "Abort".
  1201.  
  1202. 2.1.2       PROJECT/Open load file:
  1203. ReSource will present the ARP file requester.  When you  either  double-click
  1204. on  a  file  name,  select  a file and press "return", or click on the "okay"
  1205. gadget, ReSource will attempt to load the file as an  executable,  or  "load"
  1206. file.   If  there  are  any  debug  symbols  in the executable, these will be
  1207. stored, and will become  labels  at  the  appropriate  places  in  the  file.
  1208. Relocation  is  performed where required.  If the file has overlays, ReSource
  1209. will attempt to load  the  root  hunk.   Each  debug  symbol  encountered  is
  1210. attached  to  the  appropriate  byte in the file, and for those debug symbols
  1211. (labels) that are nine characters long,  and  start  with  "lb",  immediately
  1212. followed by 'A', 'B', 'C', 'L', or 'W', the data type at the appropriate byte
  1213. will  be  set  to  ASCII,  Bytes,  Code,  Longwords,  or Words, respectively.
  1214. Additionally, local labels, of the "1$" variety, and labels ending  in  "SUB"
  1215. are  recognized as code, and labels ending in ".MSG" are recognized as ASCII.
  1216. Any BSS hunks or uninitialized data areas found are expanded fully.  You  may
  1217. hilite  areas  where  relocation  has  been  performed by selecting "DISPLAY/
  1218. Hiliting/Reloc32".
  1219.  
  1220. You are limited to files smaller than 16 Megabytes, and  further  limited  by
  1221. how  much  memory  you  have.   To  disassemble a 100K file, you will require
  1222. approximately 850K of memory, of which at least 400K must be contiguous.   If
  1223. the  file  has  large  BSS  hunks,  this  will  greatly  increase  the memory
  1224. requirements.  If you intend to load a file, do some zaps, then save  it  and
  1225. later run it, use "PROJECT/Open binary file" instead, otherwise the file will
  1226. get saved with the loader information stripped out of it.
  1227.  
  1228. 2.1.3       PROJECT/Open binary file:
  1229. Similar to "PROJECT/Open load file", except that no translation of  the  file
  1230. is  performed; the file is read in "as-is". This allows you to see the loader
  1231. information in executables, object files, etc.  You can  also  load  in  text
  1232. files,  data  base files, in fact any file whatsoever, memory permitting.  If
  1233. you select "PROJECT/Open load file" for a non-executable file, the file  will
  1234. be  loaded as a binary image instead, therefore "PROJECT/Open binary file" is
  1235. not really required except when you wish to force  an  "as-is"  load  for  an
  1236. executable  file.   If  you  wish to do some zaps (small modifications) to an
  1237. executable file, (or an ".RS" file, for that matter)  without  going  through
  1238. the disassemble/edit/reassemble/link cycle, you could load the file with this
  1239. function,  do  the  zaps  (see  "SPECIAL FUNCTIONS/Zap"), then use "SAVE/Save
  1240. binary image/All" to save the modified program.
  1241.  
  1242. 2.1.4       PROJECT/Restore file:
  1243. Useful only when the current buffer was  loaded  using  "PROJECT/Open  binary
  1244. file" or "PROJECT/Open load file". This function will attempt to load a file,
  1245. with  the  same name as the current file, using the same function that loaded
  1246. the current file originally.  Do not use this function if the current  buffer
  1247. was loaded from tracks, or directly from memory.
  1248.  
  1249. 2.1.5       PROJECT/Dismble memory:
  1250. Disassembles a block of memory directly.  You will be asked to supply a start
  1251. and end address for the memory region to be disassembled.  The memory is  NOT
  1252. copied  to a separate buffer, it is disassembled "as-is", which means that if
  1253. you hold down the left mouse button, in some areas you  can  see  the  memory
  1254. being  dynamically  updated.   It  also  means  that  you  can  modify memory
  1255. directly.  Anywhere.  For each address that you supply, if the number  starts
  1256. with  a "$", the number is assumed to be hexadecimal.  If it starts with "%",
  1257. it is assumed to be a binary number.  If neither, decimal is assumed.  If you
  1258. wish to work on a COPY of a block of memory, to avoid modifying the original,
  1259. or perhaps because the original will not be around for long, disassemble  the
  1260. memory  directly,  and  save  the  data with the "PROJECT/Save .RS" function.
  1261. Then use "PROJECT/Open load file" to load the ".RS" file normally.
  1262.  
  1263. 2.1.6       PROJECT/Read tracks:
  1264. You will be asked to supply the parameters for the track to read.  The  first
  1265. parameter  must  be  either  "DF0:", "DF1:", "DF2:", or "DF3:" (lower case is
  1266. okay).  This represents the drive that holds the disk to be read  from.   The
  1267. second  parameter  is  the number of the cylinder to start reading from.  The
  1268. third parameter is the number of the last cylinder to be read, plus one.  For
  1269. example, if you wanted to read the first cylinder from the disk in DF0:,  the
  1270. parameters  would  be  "DF0:  0  1".   The  fourth parameter is optional, and
  1271. represents the number of extra sectors to read.  For example, if  you  wished
  1272. to read only the very first sector from DF1:, the parameters would be "DF1: 0
  1273. 0  1".   If  you  wished to read the first sector from the directory track of
  1274. DF2:, the parameters would be "DF2: 40 40 1".  The fifth  parameter  is  also
  1275. optional,  and  it  represents  the  sector  offset,  to start the read.  For
  1276. example, if you wished to read sectors nine and ten on  cylinder  79  of  the
  1277. disk in DF3:, the parameters would be "DF3: 79 79 2 9".
  1278.  
  1279. 2.1.7       PROJECT/O'lay binary image:
  1280. This function prompts you for a filename.  ReSource will attempt to open  the
  1281. file,  and  read  the contents, overlaying the current file.  This is NOT the
  1282. same as opening a file normally,  as  all  labels,  symbols,  comments,  data
  1283. types,  etc.,  stay  as they are.  Only the actual contents of the executable
  1284. itself are overwritten.  For example, you may wish to pass on a ".RS" file to
  1285. someone, but because the program you have disassembled  is  copyrighted,  you
  1286. cannot  legally  distribute  the  normal  ".RS"  file,  as  it  contains  the
  1287. executable.  By  using  this  function,  and  inputting  a  filename  of  "*"
  1288. (asterisk),  ReSource will completely clear the executable within the current
  1289. file.  You may then save to a ".RS" file,  which  may  then  be  distributed,
  1290. devoid  of  the  executable.   If another person has previously purchased the
  1291. program that you have disassembled, they may load it into ReSource,  and  use
  1292. "SAVE/Save  binary  image/All",  to save the executable to a file.  They then
  1293. load the special ".RS" file which you created.  Next, they then use "PROJECT/
  1294. O'lay binary image", supplying as a filename, the name of the file previously
  1295. saved with the "SAVE/Save binary image/All" function.  This effectively  puts
  1296. the  executable  back into the ".RS" file.  The other save functions may then
  1297. be used, to save to a .asm file, for example.
  1298.  
  1299. Please make sure the executable section IS cleared  before  you  share  ".RS"
  1300. files that are disassemblies of copyrighted material.  Failure to do this may
  1301. result in your meeting many new people - mostly lawyers.
  1302.  
  1303. 2.1.8       PROJECT/Save .RS:
  1304. Use this function to save what you are currently working  on,  regardless  of
  1305. how  far you have gotten in disassembling it.  EVERYTHING is saved, even your
  1306. current position within the file.  Actually, if you  disassemble  the  Amiga®
  1307. operating  system  directly,  the ".RS" file that you create will NOT contain
  1308. the executable, therefore the ".RS" files can be legally distributed, as they
  1309. contain no copyrighted material.  This is not the case for other ".RS" files,
  1310. as the executable will be saved along with  other  information.   Please  see
  1311. "PROJECT/O'lay binary image", above.
  1312.  
  1313. 2.1.9       PROJECT/About:
  1314. Get information about the version number, author,  agents,  and  people  that
  1315. helped in the development of ReSource.
  1316.  
  1317. 2.1.10      PROJECT/Quit:
  1318. Asks you for confirmation, then quits without saving.  If  this  function  is
  1319. used within an executing macro, it will NOT ask the operator for confirmation.
  1320.  
  1321. 2.2.1.1     DISPLAY/Hiliting/None:
  1322. Use the hiliting functions to select attributes for which the data with those
  1323. attributes will be shown  with  the  foreground/background  colors  inverted.
  1324. Selecting this function will disable all types of hiliting.
  1325.  
  1326. 2.2.1.2     DISPLAY/Hiliting/BSS hunks:
  1327. Data within BSS hunks and uninitialized data areas will be hilited.
  1328.  
  1329. 2.2.1.3     DISPLAY/Hiliting/Data hunks:
  1330. Data within data hunks will be hilited.  Data hunks often will  contain  only
  1331. data constants, but may also contain code.
  1332.  
  1333. 2.2.1.4     DISPLAY/Hiliting/Code hunks:
  1334. Data within code hunks will be hilited.  Code hunks often will  contain  only
  1335. code, but may also contain data constants.
  1336.  
  1337. 2.2.1.5     DISPLAY/Hiliting/Chip load hunks:
  1338. Data within code or data hunks that MUST be loaded into  chip  memory  (only)
  1339. will be hilited.  Data falling into this category will usually be graphics or
  1340. sound data, to be accessed directly by the blitter, copper or DMA.
  1341.  
  1342. 2.2.1.6     DISPLAY/Hiliting/Fast load hunks:
  1343. Similar to the above function, except that the data is forced  to  load  into
  1344. FAST memory only.
  1345.  
  1346. 2.2.1.7     DISPLAY/Hiliting/Reloc32:
  1347. Being able to see where relocation has been  performed  is  extremely  useful
  1348. when disassembling a program.  If it were not for the relocation information,
  1349. disassembling  programs  would  be  many times harder.  ReSource makes use of
  1350. this information internally, especially when filling in data types.
  1351.  
  1352. 2.2.1.8     DISPLAY/Hiliting/Symbol scan:
  1353. When you use the "LABELS/Create single/Label -  fwd  ref"  or  "LABELS/Create
  1354. multiple/All",  all  data scanned for references are marked as being scanned.
  1355. Use this function to hilite data falling into this category.
  1356.  
  1357. 2.2.1.9     DISPLAY/Hiliting/Data type uncertain:
  1358. For most labels that ReSource creates automatically, it  is  certain  of  the
  1359. data  type  that  it  assigns.  Sometimes though, it cannot be 100% sure, and
  1360. this function will hilite all lines that fall into this category.
  1361.  
  1362. 2.2.1.10    DISPLAY/Hiliting/Data type known:
  1363. Similar to above function, only the lines where the ReSource WAS  certain  of
  1364. the  data  type, will be hilited.  This will also include lines that YOU have
  1365. set using "DISPLAY/Set data type/" (see below).
  1366.  
  1367. 2.2.1.11    DISPLAY/Hiliting/Internally produced refs:
  1368. All lines which have a label  that  was  created  by  ReSource,  rather  than
  1369. directly by the user, will be hilited.
  1370.  
  1371. 2.2.2       DISPLAY/Set data type/:
  1372. When you are certain of which type of data that you are  looking  at,  select
  1373. from one of the sub-menu items: Code, ASCII, Bytes, Words, Longwords.
  1374.  
  1375. 2.2.3       DISPLAY/Set numeric base/:
  1376. By default, all numbers are shown in hexadecimal (base 16).  You  can  change
  1377. this  to  ASCII,  DECIMAL,  BINARY,  or  back  to  HEXADECIMAL on any line by
  1378. selecting from the appropriate  sub-item.   It  is  possible  to  change  the
  1379. default  to  decimal  for  numbers  less  than 16, or less than 10, using the
  1380. decimal conversion function (see below).
  1381.  
  1382. The function "DISPLAY/Set  numeric  base/ASCII"  will  enable  virtually  any
  1383. number  at  all  to  be  shown  as  ASCII,  providing that no non-valid ascii
  1384. characters are present.  Be aware that the following lines:
  1385.  
  1386.             dc.l    $4E
  1387.             dc.l    $4E00
  1388.             dc.l    $4E004E00
  1389.             dc.l    $4E4E00
  1390.             dc.l    $4E000000
  1391.             dc.l    $444F53
  1392.             dc.l    $444F5300
  1393.             dc.l    $4B49434B
  1394.  
  1395. will, by using the ASCII numeric base, be shown as:
  1396.  
  1397.             dc.l    'N'
  1398.             dc.l    'N'<<8
  1399.             dc.l    $4E004E00
  1400.             dc.l    'NN'<<8
  1401.             dc.l    'N'<<24
  1402.             dc.l    'DOS'
  1403.             dc.l    'DOS'<<8
  1404.             dc.l    'KICK'
  1405.  
  1406. Note that the third line contained a  non-valid  ASCII  character.   Although
  1407. some  others  contained zeroes in the lower byte(s), they can be safely shown
  1408. as being an ASCII value shifted 8/16/24 to the left.
  1409.  
  1410. 2.2.4       DISPLAY/Decimal conversion/:
  1411. By default, all numbers are shown in hexadecimal.  You can have numbers  less
  1412. than  16,  or  numbers less than 10, shown in decimal throughout the file, by
  1413. selecting one of the appropriate sub-items.
  1414.  
  1415. 2.2.5       DISPLAY/Blank lines/:
  1416. To better define subroutines, and logical blocks of code, ReSource can insert
  1417. blank lines in the source code.  You may  select  whether  a  blank  line  is
  1418. inserted  after  each  conditional  branch,  unconditional branch, return, or
  1419. system call.
  1420.  
  1421. You may select more than one, in which case a blank line  will  appear  after
  1422. any  line which falls into any of the selected categories.  A line will never
  1423. be followed by more than one blank line,  regardless  of  how  many  selected
  1424. categories it falls into.
  1425.  
  1426. 2.2.6.1     DISPLAY/Cursor address/Relative:
  1427. The cursor address will be shown in the title bar, as  a  hexadecimal  offset
  1428. from the start of the file.
  1429.  
  1430. 2.2.6.2     DISPLAY/Cursor address/Absolute:
  1431. The cursor address will be shown in the title bar, as a hexadecimal  absolute
  1432. machine  address.   This  allows  you  to quickly find the cursor position in
  1433. memory with other utilities, such as MetaScope, perhaps to  carry  out  large
  1434. scale modifications.
  1435.  
  1436. 2.2.7.1     DISPLAY/Titlebar info/Filename:
  1437. Information is displayed in the title bar in several fields.  From the  left,
  1438. the  first is the program name.  The second is a decimal number, representing
  1439. the cursor position relative to the file size, and is a percentage.  The next
  1440. field is a hexadecimal number, representing the cursor position, and  can  be
  1441. shown  either  as  an  offset  from  the start of the file, or as an absolute
  1442. memory location.  The next field is the one that this  function  relates  to.
  1443. By  selecting  this  function,  the current file name will be shown.  If user
  1444. feedback is ON, informative messages will sometimes be shown  in  this  field
  1445. also.
  1446.  
  1447. 2.2.7.2     DISPLAY/Titlebar info/Attributes:
  1448. The second field of the title bar will display information  representing  the
  1449. current  attributes of the cursor byte.  This information is NOT required for
  1450. general program usage, and was originally  included  for  debugging  purposes
  1451. only, and left in to satisfy those that want to know how the attributes table
  1452. in  ReSource  works.   The  attributes  table  is  four times the size of the
  1453. current file, plus 16 bytes.  It is used internally as  a  large  bitmap,  to
  1454. store  information about each and every byte in the current file.  Because it
  1455. is four times the file size, 32 bits are  available  for  each  byte  in  the
  1456. current file.  For each character in the string displayed, if lower case, the
  1457. bit  that  that character represents is clear, if upper case, the bit is set.
  1458. Going from the left, the bit definitions are:
  1459.  
  1460.             S:      Start of a line of code/data
  1461.             B:      Bss hunk
  1462.             D:      Data hunk
  1463.             C:      Code hunk
  1464.             R:      Reloc32 area
  1465.             F:      First byte of reloc32 area
  1466.             L:      Label attached to this byte
  1467.             S:      Symbol attached to this byte
  1468.             F:      Full-line comment attached to this byte
  1469.             E:      End-of-line comment attached to this byte
  1470.             P:      Parsed previously (symbol scan)
  1471.             I:      Internally referenced
  1472.             L:      Low priority.  The data type has been set, but can be overridden by
  1473.                     internal routines.  The data type can always be overridden by the
  1474.                     user.  This bit was generally set when ReSource had to decide on a
  1475.                     data type to set for a byte, but when it did so, it wasn't really
  1476.                     sure that it was correct.
  1477.             A:      Show numeric operands as ASCII if possible.  Decimal conversion
  1478.                     is on a higher priority than this bit.
  1479.             B:      Show numeric operands as Binary.  Decimal conversion is on a higher
  1480.                     priority than this bit.
  1481.             D:      Show numeric operands as Decimal if possible.
  1482.             F:      Data in this hunk is to be loaded into FAST memory only.
  1483.             C:      Data in this hunk is to be loaded into CHIP memory only.
  1484.              :      [Next 4 bits are reserved for future use]
  1485.             U:      User should check the data type that has been set, as ReSource wasn't
  1486.                     really sure that it chose the correct one.  Use "CURSOR/Relative/Next
  1487.                     uncertain D/T" to find the next occurrence.  If such a line is already
  1488.                     the current line when you use that function, it will clear this bit.
  1489.             H:      High priority.  The data type has been set either by the user, or by
  1490.                     ReSource when it was quite certain that it set the data type
  1491.                     correctly.  This does not mean that it cannot make mistakes, it
  1492.                     simply means that if some operation attempts to set the data type for
  1493.                     this byte, it will NOT override the currently set data type.  This
  1494.                     will not ever stop the user from redefining the data type, however.
  1495.             C:      This line is code.
  1496.             dddd:   Data type hasn't been set yet
  1497.             ddDd:   Data type is bytes
  1498.             dDdd:   Data type is words
  1499.             dDDd:   Data type is longwords
  1500.             Dddd:   Data type is bytes, within a BSS hunk or uninitialized data area.
  1501.             DddD:   Data type is ASCII.
  1502.             DDDd:   Data type is words, within a BSS hunk or uninitialized data area.
  1503.             DDDD:   Data type is longwords, within a BSS hunk or uninitialized data area.
  1504.  
  1505. 2.2.7.3     DISPLAY/Titlebar info/Accumulator:
  1506. The third field of the title bar will display  information  representing  the
  1507. contents  of  the  ACCUMULATOR.  This is a 240 byte buffer, used as a central
  1508. number and string processor, which will find most of its uses within  macros.
  1509. Only  the  first 30 characters or so can be shown in the title bar.  However,
  1510. often the string will not be longer than that anyway.  For  more  information
  1511. on the accumulator, see the functions within the "STRINGS" menu.
  1512.  
  1513. 2.2.8       DISPLAY/Wrap/:
  1514. With wrap on, any lines longer than the current display width will  be  shown
  1515. on  several  lines, much the same way that text editors allow you to use word
  1516. wrap.  Otherwise, any lines longer than the current  display  width  will  be
  1517. truncated.
  1518.  
  1519. 2.2.9       DISPLAY/Block-fill:
  1520. Some background information is required here:  ReSource  internally  keeps  a
  1521. stack of cursor locations.  The current cursor location is "pushed" onto this
  1522. stack with any use of the following functions:
  1523.  
  1524.             CURSOR/Remember
  1525.             CURSOR/Absolute/End of file
  1526.             CURSOR/Absolute/Start of file
  1527.             CURSOR/Absolute/Forward reference
  1528.             CURSOR/Absolute/Second forward reference
  1529.             CURSOR/Absolute/Backward reference
  1530.  
  1531. To "pop" a cursor location, you use  the  function  "CURSOR/Absolute/Previous
  1532. location".   The stack is cleared when you load a new file.  The stack is NOT
  1533. stored within ".RS" files.
  1534.  
  1535. Block-fill uses the cursor location stored on the top of this location stack,
  1536. finds out what the data type at that location has been  set  to,  and  copies
  1537. that  data  type  to  all  locations  between  there  and  the current cursor
  1538. location.  It has several disadvantages, and should be used only when special
  1539. display effects are required.  For example, if you wish to display a file  as
  1540. bytes  throughout,  even  though  much  of it is actually code or ASCII, this
  1541. function may come in handy.
  1542.  
  1543. 2.2.10      DISPLAY/Fill-in data types:
  1544. This function has several uses, and will be one of the  most-used  functions.
  1545. To  understand  what  this  function does, you will need to know how ReSource
  1546. keeps track of data types.  Suffice it to say, when you  set  the  data  type
  1547. anywhere  within  a  file, that data type is immediately echoed forward, to a
  1548. maximum of several hundred bytes, but will not change any other places  where
  1549. the  data  type  has  already  been set, or where there is a label on a line.
  1550. Where there is large areas of a file where the data type has  not  been  set,
  1551. this  function  attempts  to set the data type appropriately.  All of this is
  1552. done on the first pass.  On the second pass, the length of each line is  set.
  1553. This  is  particularly  useful  where  there  are large areas of ASCII.  This
  1554. function should always be used before saving a file as source code.
  1555.  
  1556. 2.2.11      DISPLAY/Fill-in D/T Fwd:
  1557. Similar to the above function, except that both passes will  start  from  the
  1558. current  cursor location, and NOT the start of the file.  Also, the action of
  1559. this function will stop at the end of the current section, OR the end of  the
  1560. file, whichever occurs first.  Useful if you need to make changes to data and
  1561. BSS areas towards the end of the file.
  1562.  
  1563. 2.2.12      DISPLAY/Set counter:
  1564. If cursor address has been set to "relative", the current offset in a file is
  1565. shown in the title bar, in hexadecimal.  This is normally zero at  the  start
  1566. of the file.  You can change this, so that it is zero at somewhere other than
  1567. the  start of the file, by using this function.  You may use this function to
  1568. measure the size of a hunk, for example.  To "reset"  the  counter,  use  the
  1569. function  "DISPLAY/Reset  counter".   If  cursor  address  has  been  set  to
  1570. "absolute", it will correctly display the  current  address  of  the  cursor,
  1571. regardless of this function.
  1572.  
  1573. 2.2.13      DISPLAY/Reset counter:
  1574. Similar to the above function, except that the cursor position is assumed  to
  1575. be at the start of the file.
  1576.  
  1577. 2.2.14      DISPLAY/Flip case - code:
  1578. If code is currently being displayed using upper case,  it  will  be  instead
  1579. shown  in  lower  case,  and  vice  versa.   Note  that all searches are case
  1580. sensitive.
  1581.  
  1582. 2.2.15      DISPLAY/Flip case - data:
  1583. If data is currently being displayed using upper case, it will be instead  be
  1584. shown in lower case, and vice versa.
  1585.  
  1586. 2.3         SYMBOLS 1/:
  1587. Some background information is required here: When you  assemble  a  program,
  1588. you  will  use  symbols  such   as   "_LVOAllocMem",   "MEMF_CHIP",   "Open",
  1589. "MODE_OLDFILE", etc.  When you  disassemble  a  program,  you  see  only  the
  1590. numbers  that  equate to the symbols that you used.  To convert these numbers
  1591. back into strings, you basically tell ReSource what the "symbol base" is, and
  1592. it will do the rest.  For example, in the following line:
  1593.  
  1594.             JSR     -$0228(A6)
  1595.  
  1596. the number "-$0228" could be interpreted in  many  different  ways.   If  you
  1597. happened  to  know  that  the  A6  register  at that point in the program was
  1598. pointing to the Exec library base, you would interpret that line as:
  1599.  
  1600.             JSR     _LVOOpenLibrary(A6)
  1601.  
  1602. To make ReSource do this automatically, you would scroll so  that  this  line
  1603. became  the  cursor  line, and then select the function "SYMBOLS 1/Libraries/
  1604. Exec", or "SYMBOLS 2/E-G/Exec library".  There are hundreds of  other  symbol
  1605. bases  that  are  available,  including   libraries,   devices,   structures,
  1606. parameters, and error code names.
  1607.  
  1608. 2.3.1       SYMBOLS 1/Set Source/dest/:
  1609. Examine the following line of code:
  1610.  
  1611.             MOVE.L  #-$0228,$0022(A6)
  1612.  
  1613. If you wished to create a symbol for the second number on this line, "$0022",
  1614. you should first select "Destination".  The setting of "Set Source/dest" will
  1615. go back to "Source" with virtually  any  function  you  use,  therefore  when
  1616. creating  a symbol for the second field in a line of code, use "SYMBOLS 1/Set
  1617. Source/dest/Destination" only just prior to actually creating the symbol.
  1618.  
  1619. 2.3.2       SYMBOLS 1/Object/:
  1620. By default the number, or object, used to find the string will come from  the
  1621. cursor  line.   You  can  instead  have  ReSource  get  the  number  from the
  1622. accumulator, by selecting "Accumulator".  In this  case,  the  output  string
  1623. will be placed back into the accumulator.  To set it back, select "Cursor".
  1624.  
  1625. 2.4         SYMBOLS 2/:
  1626. Some special symbol bases are in  the  "SYMBOLS  1"  menu,  mostly  different
  1627. library  bases.   The  remainder are in alphabetical order in the "SYMBOLS 2"
  1628. menu.
  1629.  
  1630. 2.5.1       CURSOR/Remember:
  1631. ReSource keeps a stack of cursor locations internally.  Using  this  function
  1632. will  "push"  the  current cursor location onto the top of this stack.  Other
  1633. functions that call this function are:
  1634.  
  1635.             CURSOR/Remember
  1636.             CURSOR/Absolute/End of file
  1637.             CURSOR/Absolute/Start of file
  1638.             CURSOR/Absolute/Forward reference
  1639.             CURSOR/Absolute/Second forward reference
  1640.             CURSOR/Absolute/Backward reference
  1641.  
  1642. To "pop" a cursor location, you use  the  function  "CURSOR/Absolute/Previous
  1643. locations". The stack is cleared when you load a new file, or when you select
  1644. "CURSOR/Clear loc stack". The stack is NOT stored within ".RS" files.
  1645.  
  1646. 2.5.2       CURSOR/Clear loc stack:
  1647. See above function.
  1648.  
  1649. 2.5.3.1     CURSOR/Relative/Next byte:
  1650. The cursor location is incremented.  If  at  the  last  location  within  the
  1651. current file, a macro "fail" will result.
  1652.  
  1653. 2.5.3.2     CURSOR/Relative/Previous byte:
  1654. The cursor location is decremented.  If at  the  first  location  within  the
  1655. current file, a macro "fail" will result.
  1656.  
  1657. 2.5.3.3     CURSOR/Relative/Next line:
  1658. Scroll forward one line of code/data.  If at the last line  of  code/data  in
  1659. the file already, a macro "fail" will result.  The speed at which this scroll
  1660. is done is set by the "CURSOR/Scrolling speed" settings.
  1661.  
  1662. 2.5.3.4     CURSOR/Relative/Previous line:
  1663. Scroll backwards one line of code/data.  If at the first line of code/data in
  1664. the file already, a macro "fail" will result.  The speed at which this scroll
  1665. is done is set by the "CURSOR/Scrolling speed" settings.
  1666.  
  1667. 2.5.3.5     CURSOR/Relative/Next label:
  1668. Move cursor to the next location that has a label attached  to  it.   If  one
  1669. cannot be found, a macro "fail" will result.
  1670.  
  1671. 2.5.3.6     CURSOR/Relative/Previous label:
  1672. Move cursor to the previous location that has a label attached to it.  If one
  1673. cannot be found, the start of the file will become the new cursor position.
  1674.  
  1675. 2.5.3.7     CURSOR/Relative/Next symbol:
  1676. Move cursor to the next location that has a symbol attached to  it.   If  one
  1677. cannot  be found, a macro "fail" will result.  Note that this location may be
  1678. in the middle of a line of code.  Where the actual  operand  is  stored  will
  1679. become the new cursor position.
  1680.  
  1681. 2.5.3.8     CURSOR/Relative/Previous symbol:
  1682. Move cursor to the previous location that has a symbol attached  to  it.   If
  1683. one  cannot  be  found,  the  start  of  the  file will become the new cursor
  1684. position.  Note that this location may be in the middle of a  line  of  code.
  1685. Where the actual operand is stored will become the new cursor position.
  1686.  
  1687. 2.5.3.9     CURSOR/Relative/Next section:
  1688. Move cursor to the start of the next section (hunk).  If  this  is  the  last
  1689. section in the file, a macro "fail" will result.
  1690.  
  1691. 2.5.3.10    CURSOR/Relative/Previous section:
  1692. Move cursor to the start of this section (hunk). If already at the start of a
  1693. section, move to the start of the previous section.
  1694.  
  1695. 2.5.3.11    CURSOR/Relative/Next reloc32:
  1696. Move cursor to the start of the next relocated longword.  If  one  cannot  be
  1697. found,  a macro "fail" will result.  Note that this may be in the middle of a
  1698. line of code.
  1699.  
  1700. 2.5.3.12    CURSOR/Relative/Previous reloc32:
  1701. Move cursor to the start of the previous relocated longword.  Note that  this
  1702. may be in the middle of a line of code.  If one cannot be found, the start of
  1703. the file will become the new cursor position.
  1704.  
  1705. 2.5.3.13    CURSOR/Relative/Next page:
  1706. Move cursor forward 24 lines.
  1707.  
  1708. 2.5.3.14    CURSOR/Relative/Previous page:
  1709. Move cursor backwards 24 lines.
  1710.  
  1711. 2.5.3.15    CURSOR/Relative/Skip forward:
  1712. Move cursor forward approximately 4K.
  1713.  
  1714. 2.5.3.16    CURSOR/Relative/Skip backward:
  1715. Move cursor backward approximately 4K.
  1716.  
  1717. 2.5.3.17    CURSOR/Relative/Next unparsed code:
  1718. Move cursor forward to the next location that satisfies both of the following
  1719. conditions:
  1720.  
  1721.   1. The data type has been set to CODE
  1722.   2. This location has NOT been scanned for forward references previously.
  1723.  
  1724. This function is useful when combined with the  "LABELS/Create  multiple/All"
  1725. function.
  1726.  
  1727. 2.5.3.18    CURSOR/Relative/Next D/T change:
  1728. Move cursor to the next location that has its data type set differently  than
  1729. the data type at the current cursor location.
  1730.  
  1731. 2.5.3.19    CURSOR/Relative/Previous D/T change:
  1732. Move cursor to the previous location that has its data type  set  differently
  1733. than the data type at the current cursor location.
  1734.  
  1735. 2.5.3.20    CURSOR/Relative/Next uncertain D/T:
  1736. Move cursor forward to the next location that has the "Uncertain" bit set  in
  1737. the  attribute table.  This bit indicates that ReSource really wasn't sure of
  1738. the data type of this byte.
  1739.  
  1740. 2.5.3.21    CURSOR/Relative/Next backward reference:
  1741. Once you have used the "CURSOR/Absolute/Backwards  reference"  function,  you
  1742. can use this function to get to other backward references.
  1743.  
  1744. 2.5.4.1     CURSOR/Absolute/End of file:
  1745. Move cursor to the start of the last line of the file.
  1746.  
  1747. 2.5.4.2     CURSOR/Absolute/Start of file:
  1748. Move cursor to the start of the file.
  1749.  
  1750. 2.5.4.3     CURSOR/Absolute/Forward reference:
  1751. If there is a reference to a position in the current file within the  current
  1752. line of code, move cursor to the location being referenced.  If there are two
  1753. forward references within the current line, the first is used.
  1754.  
  1755. 2.5.4.4     CURSOR/Absolute/Second forward reference:
  1756. If there are two references to a position with the current file,  within  the
  1757. current  line  of  code, move cursor to the second location being referenced.
  1758. If there are less than two forward references, a macro "fail" will result.
  1759.  
  1760. 2.5.4.5     CURSOR/Absolute/Backward reference:
  1761. Starting from the start of the file, search  for  references  to  the  cursor
  1762. location.  If there are several references, you can use "CURSOR/Relative/Next
  1763. backward reference" to get to successive references.
  1764.  
  1765. 2.5.4.6     CURSOR/Absolute/Previous location:
  1766. "Pop" the cursor location from the top of the cursor location stack.  If  the
  1767. stack is empty, a macro "fail" will result.
  1768.  
  1769. 2.5.4.7     CURSOR/Absolute/Specify offset:
  1770. You will be asked to supply an offset representing how far from the start  of
  1771. the  file,  the  cursor  location  should be.  The number may be specified in
  1772. hexadecimal, decimal, or binary.  If hexadecimal, the string must start  with
  1773. "$",  if  binary,  it must start with "%".  If the given offset is not within
  1774. the current file, this function will fail.
  1775.  
  1776. 2.5.4.8     CURSOR/Absolute/Specify label:
  1777. You will be asked to supply the name of a label.  If the label is used within
  1778. the current file, its location will become the  new  cursor  location.   Note
  1779. that this may be in the middle of a line of code.
  1780.  
  1781. 2.5.4.9     CURSOR/Absolute/Specify symbol:
  1782. You will be asked to supply the name of a symbol.   If  the  symbol  is  used
  1783. within  the  current  file, its location will become the new cursor location.
  1784. Note that this may be in the middle of a line of code.   Also  note  that  if
  1785. there  is  more than one symbol of that name, ReSource will pick the one that
  1786. was defined first.
  1787.  
  1788. 2.5.4.10    CURSOR/Absolute/Specify percentage:
  1789. You will be asked to supply a decimal percentage of the current  file,  where
  1790. the  cursor  will be positioned.  In this case 0 is the beginning of the file
  1791. and 99 is the end.  Note that this may be in the middle of a  line  of  code.
  1792. The  actual  positioning  will  not  be exact.  It will generally be placed a
  1793. little before the required percentage.
  1794.  
  1795. 2.5.5       CURSOR/Copy/:
  1796. 2.5.6       CURSOR/Paste/:
  1797. 2.5.7       CURSOR/Swap/:
  1798. Some background information is required here: ReSource has 3 internal  cursor
  1799. "clipboards".  You can copy a cursor location to any of these, and then later
  1800. "paste"  one of these locations, which in effect moves the cursor to where it
  1801. was when you used the "copy" function.  Also, you can swap cursor  locations,
  1802. between  the  current,  and  a stored cursor location.  The contents of these
  1803. cursor "clipboards" are cleared when you load a  new  file,  or  restore  the
  1804. current one.
  1805.  
  1806. 2.5.8       CURSOR/Scrolling speed/:
  1807. Whenever you use  either  "CURSOR/Relative/Next  line"  or  "CURSOR/Relative/
  1808. Previous  line"  functions,  the  text  on  the display will move N number of
  1809. display lines (NOT text lines) at a time.  This is  how  most  text  editors,
  1810. word processors, etc., scroll text.
  1811.  
  1812.      Scrolling   Lines
  1813.      Speed       Scrolled   Notes
  1814.      ---------   --------   -----
  1815.      Very fast      8       Exceptionally fast scrolling, good for scanning
  1816.                             through a file.
  1817.      Fast           4       Reasonably fast scrolling, allows scanning,
  1818.                             but difficult to read.
  1819.      Normal         2       Reasonably smooth scrolling, allowing you to
  1820.                             read text fairly easily WHILE it is scrolling.
  1821.      Slow           1       Extremely smooth scrolling, allowing you to
  1822.                             easily read text WHILE it is scrolling.
  1823.      Very Slow      1       w/delay Exceptionally smooth scrolling, and is
  1824.                             excellent for slowly browsing through a file.
  1825.  
  1826. 2.5.9.1     CURSOR/Normal search/Set search string:
  1827. You will be asked to supply a string, which will be used in future  searches.
  1828. Like  all  other  string  requests, you may instead supply a two byte string,
  1829. starting with escape, and followed by either another escape character,  or  a
  1830. letter  a-m,  representing  a string buffer where the string should be copied
  1831. from.  If you supply escape-escape as the string, the string currently in the
  1832. accumulator will be copied into the search string buffer.
  1833.  
  1834. 2.5.9.2     CURSOR/Normal search/Find next occurrence:
  1835. Using the currently defined  search  string,  search  forward  for  the  next
  1836. occurrence  of  that  string.   The  string  is searched for as-is, including
  1837. question marks, asterisks, etc., which in a pattern search  take  on  special
  1838. meaning.
  1839.  
  1840. 2.5.9.3     CURSOR/Normal search/Find previous occurrence:
  1841. Similar to the above function, except that the search proceeds backwards.
  1842.  
  1843. 2.5.9.4     CURSOR/Normal search/Find nearest occurrence:
  1844. Similar to the above function,  except  that  the  search  proceeds  in  both
  1845. directions at the same time.  The search is done line-for-line, and the first
  1846. line that contains the search string, whether it be before the current cursor
  1847. or  after,  will become the new cursor location.  This function is handy when
  1848. you know that a string is somewhere close, but you're not sure whether it may
  1849. be just past, or just before, the current cursor location.  Note that you may
  1850. NOT use this function to find the second occurrence of a string; it will keep
  1851. finding the same two closest occurrences.
  1852.  
  1853. 2.5.9.5     CURSOR/Normal search/Search this line:
  1854. This function is useful in macros, for determining whether a given string  is
  1855. within  the  current  line.  If the search string is not found in the current
  1856. line, a macro "fail" will result, and unless your macro has prepared for this
  1857. condition with an "End conditional" directive, the macro will abort.
  1858.  
  1859. 2.5.9.6     CURSOR/Normal search/Search accumulator:
  1860. Similar to the above function, except that the accumulator is searched.
  1861.  
  1862. 2.5.10      CURSOR/Pattern search/:
  1863. These functions are identical to their counterparts above, except  that  "Set
  1864. search  pattern"  is  used  instead  of  "Set search string" and ARP wildcard
  1865. characters are expanded (not used literally).
  1866.  
  1867. 2.6.1.1     LABELS/Create single/End-of-line comment:
  1868. You will be asked to supply a string of less than 240 characters, which  will
  1869. become a comment to be attached to the end of the cursor line.  Only one end-
  1870. of-line  comment  is  allowed  per line; if you create one on a line that has
  1871. already got one, it will replace the old comment.
  1872.  
  1873. 2.6.1.2     LABELS/Create single/Full-line comment:
  1874. You will be asked to supply a string of less than 240 characters, which  will
  1875. become  a  comment  to be attached to the start of the cursor line.  Multiple
  1876. full-line comments are allowed, and successive  comments  will  be  displayed
  1877. AFTER  previously  defined  full-line comments.  Normally, full-line comments
  1878. will be displayed starting with a semicolon (";"). However, if you start  the
  1879. string  with a semicolon, the logic is reversed, and it becomes an extra line
  1880. of code/data.  Thus, you can insert extra lines  of  code/data,  even  before
  1881. saving  the source code to a text file.  By creating a label that starts with
  1882. a semicolon for a given line, when that code is assembled, that line of code/
  1883. data is effectively treated as a comment only, therefore you can both  insert
  1884. and  effectively  remove  code/data  using  ReSource,  during the disassembly
  1885. process.
  1886.  
  1887. 2.6.1.3     LABELS/Create single/Label:
  1888. You will be asked to supply a string of less than 240 characters, which  will
  1889. become  a  label to be attached to the cursor line.  Duplicate labels are NOT
  1890. allowed, unless they start with a semicolon (";"), an asterisk  ("*"),  or  a
  1891. number  directly  followed  by  a "$".  This last case is useful for creating
  1892. local labels, but be careful.  They are not checked for  duplication  and  if
  1893. used  imprudently  may  make  your  assembler very unhappy.  In the first two
  1894. cases, they effectively make the  rest  of  the  line  a  comment.   If  this
  1895. function is used within a macro, duplicate labels WILL be accepted.
  1896.  
  1897. 2.6.1.4     LABELS/Create single/Label - fwd ref:
  1898. The current line of code will be searched for references to positions  within
  1899. the  current  file.  If any are found, ReSource will make a decision on which
  1900. type of data is at the position referenced.  It will then set the  data  type
  1901. (unless it has already been set), and create a label at that offset (unless a
  1902. label  has  already  been  defined for that location). This new label will be
  1903. immediately used for  all  references  to  that  location,  which  of  course
  1904. includes  the reference within the current line.  If there are no references,
  1905. or there is a reference, but it is outside of the range of the current  file,
  1906. then  this  function  will  do nothing.  Normally, this function will only be
  1907. used within macros, as it is easier and quicker to hold down  the  left-Amiga
  1908. key, while holding down the left mouse button, possibly while scrolling also.
  1909.  
  1910. 2.6.1.5     LABELS/Create single/Symbol:
  1911. You will  be  asked  to  supply  a  string,  which  will  replace  the  first
  1912. encountered  number  in  the  current line.  For example, if you supplied the
  1913. string "MyColdStartData", the following line:
  1914.  
  1915.             MOVE.L  D0,4(A0) would become:
  1916.  
  1917.             MOVE.L  D0,MyColdStartData(A0)
  1918.  
  1919. If there is more than one number mentioned in the current line, the first  is
  1920. used.   If  there  are  no  numbers  in the current line, a macro "fail" will
  1921. result.
  1922.  
  1923. 2.6.1.6     LABELS/Create single/Symbol - dest:
  1924. Similar to the above function, except that the second number in  the  current
  1925. line  will be replaced with the string that you supply.  If there is only one
  1926. number, or if there are no numbers in the current line, a macro  "fail"  will
  1927. result.
  1928.  
  1929. 2.6.2       LABELS/Edit single/:
  1930. Similar to their above counterparts, except that if there is already a label/
  1931. symbol/comment defined, you will have the chance to edit that string,  rather
  1932. than  type  the  entire  new string into the requester.  Note that, as far as
  1933. ReSource is concerned, in the example "$0022(A1)", "$0022" is a number, NOT a
  1934. symbol, unless YOU have defined it previously.  If you try to  edit  it,  you
  1935. will  be  presented with an empty requester.  Like all requests for a string,
  1936. you can use indirection, so that ReSource gets the  string  from  either  the
  1937. accumulator,  or  from  one  the buffers A-M.  See the section on the STRINGS
  1938. menu for more details.
  1939.  
  1940. 2.6.3.1     LABELS/Replace single/Label:
  1941. Create a "shop" label at the cursor position.  A "shop" label is one that  is
  1942. 9 characters long, begins with "lb", has the data type immediately following,
  1943. and  ends with the code offset.  It may also be of some other length, and end
  1944. with ".MSG".
  1945.  
  1946. 2.6.4.1     LABELS/Remove single/Label:
  1947. Removes the label from the cursor position.
  1948.  
  1949. 2.6.4.2     LABELS/Remove single/Symbol:
  1950. Removes any symbols in the current line.
  1951.  
  1952. 2.6.4.3     LABELS/Remove single/End-of-line comment:
  1953. Removes the end-of-line comment from the current line, if any.
  1954.  
  1955. 2.6.4.4     LABELS/Remove single/Full-line comment:
  1956. Removes the first full-line comment attached to the current line.
  1957.  
  1958. 2.6.4.5     LABELS/Remove single/All:
  1959. Removes any label, symbols, comments from the current line.  Also,  the  data
  1960. type for the current cursor position is set to 'undefined', and the 'start of
  1961. line'  bit  is  cleared.   This is useful when a bogus reference was made, as
  1962. when ReSource (or you) thought code was being scanned, and  it  was  actually
  1963. data or ASCII.
  1964.  
  1965. 2.6.5.1     LABELS/Create multiple/Reloc32:
  1966. For each reloc32 pointer within the current file, determine and set the  data
  1967. type  being  referenced,  and create a label at that location.  This function
  1968. will be called automatically whenever you load a load file that has at  least
  1969. one reloc32 pointer, unleass you override this option.
  1970.  
  1971. 2.6.5.2     LABELS/Create multiple/All:
  1972. Starting at the current address, the  "LABELS/Create  single/Symbol  -  dest"
  1973. function is executed, and if ReSource thinks that there was valid code in the
  1974. current  line,  the "CURSOR/Relative/Next line" function is executed, and the
  1975. entire  function   loops,   otherwise  the  "PROJECT/-=Abort=-"  function  is
  1976. executed.   This  function  can  make  the disassembly process very fast, the
  1977. disadvantage being that there is a very  slight  chance  that  what  ReSource
  1978. thinks is valid code is really ASCII, and invalid labels will be created.
  1979.  
  1980. 2.7         LOCAL MACROS/:
  1981. 2.8         GLOBAL MACROS/:
  1982. Much background information is required here: The macro facilities  available
  1983. in  ReSource are quite extensive.  There are a maximum of 38 macros available
  1984. on line at one time.  These are divided into two banks of 19  macros,  called
  1985. "LOCAL  MACROS"  and "GLOBAL MACROS".  The idea being that the 'local' macros
  1986. are for your own personal use, and global macros are meant to be  distributed
  1987. to others.  Therefore, you can load a 'global macros' file, and use them, but
  1988. still have access to your own personal macros.
  1989.  
  1990. The 19th local macro is special, in that it is executed when  you  first  run
  1991. ReSource,  after  the  first  file  is loaded.  This macro will often contain
  1992. functions to set the various options to your personal taste, but may  contain
  1993. anything you care to put into it.
  1994.  
  1995. When first creating a macro, you will be asked to supply a name for it.  This
  1996. name will be shown in the MACRO menu immediately after, and if you save  that
  1997. bank of macros to a file, the names of the macros are also saved.
  1998.  
  1999. The functions "LOCAL MACROS/Execute/-unused-"  and  "GLOBAL  MACROS/Execute/-
  2000. unused-" are used to give macros in either bank a name.  These names are also
  2001. saved when you save a bank of macros, and when you load the macro file later,
  2002. these  names  will  immediately appear in the menus, making it much easier to
  2003. remember what previously created macros did.
  2004.  
  2005. The size of a macro is limited only by how much memory you have.  To create a
  2006. macro, select one of the sub-items in "LOCAL MACROS/Create/End/"  or  "GLOBAL
  2007. MACROS/Create/End/".   If  the  current  name for the macro is "-empty-", you
  2008. will be asked to supply a new name for the macro.  If you create a  macro  of
  2009. zero  length,  the  name for that macro will revert to "-empty-".  To execute
  2010. the macro, simply select the appropriate sub-item in "LOCAL  MACROS/Execute/"
  2011. or "LOCAL MACROS/Execute/".
  2012.  
  2013. You have control over the speed at which macros execute.  The following chart
  2014. indicates whether there will be a delay, and for how long,  and  whether  the
  2015. display will be refreshed between executing functions within the macro.
  2016.  
  2017.      Speed Selected   Delay   Refresh
  2018.      --------------   -----   -------
  2019.        Very Fast      No        No
  2020.        Fast           No        Yes
  2021.        Slow           .1 sec    Yes
  2022.        Very Slow      .5 sec    Yes
  2023.  
  2024. To have complete control over execution of the macro, select  "LOCAL  MACROS/
  2025. Execution  speed/Wait  on  mouse".   With  this  selected, you must press and
  2026. release the left mouse button for each and every function within the macro to
  2027. be executed.  This is an excellent way to find bugs in a macro that  you  (or
  2028. someone else) has created.
  2029.  
  2030. Macros may be nested within macros, provided that the nesting depth does  not
  2031. exceed (approx.) 30.
  2032.  
  2033. While you are creating a macro, you might find that you have to execute  some
  2034. functions  to continue the macro definition, but you don't want them included
  2035. in the macro itself.  When this occurs, select "LOCAL  MACROS/Suspend  learn/
  2036. suspend",  select  the  various  functions  that need to be done, then select
  2037. "LOCAL MACROS/Suspend learn/Normal" to continue the macro definition.
  2038.  
  2039. There are many functions that will make a macro fail, when  it  is  executed.
  2040. For  example,  using  a  cursor movement function that would place the cursor
  2041. outside of the current file, will cause a macro 'fail'.  A failed search will
  2042. also cause a macro 'fail'.  When executing a macro,  if  ReSource  detects  a
  2043. macro  'fail', it searches forward in the macro definition for a "Conditional
  2044. end" directive.  Is none is found, all macro processing  aborts  immediately.
  2045. If  one  IS found, macro processing continues normally from that point in the
  2046. macro definition.  If, while searching for a "End conditional"  directive,  a
  2047. "Start  conditional"  directive  is  found,  the  next  "End  conditional" is
  2048. skipped.  Thus, conditional macro processing may be nested.
  2049.  
  2050. There are five macro labels available.   These  are  placed  into  the  macro
  2051. definition,  and  you  can  insert "goto previous macro label" and "goto next
  2052. macro label" directives into the macro definition,  which  when  found,  will
  2053. start  a  search either forward or backward, for the appropriate macro label.
  2054. When found, macro processing will proceed normally from that  point  forward.
  2055. Thus,  you can loop a macro.  If a search is made backwards for a macro label
  2056. that is non-existent, macro processing will continue from the  start  of  the
  2057. macro definition.  If a search is made forward for a macro label that is non-
  2058. existent,  the  macro  will  exit, possibly to another macro that called this
  2059. one.  For example, the following macro will continuously  scroll  forward  to
  2060. the  end of the file, then scroll backwards, one line at a time, to the start
  2061. of the file, then forward to the end of the file again,  etc.,  indefinitely,
  2062. stopping only when you select "PROJECT/Abort":
  2063.  
  2064.             LOCAL MACROS/Set macro label/#1
  2065.             CURSOR/Relative/Next line
  2066.             LOCAL MACROS/Previous macro label/#1
  2067.             LOCAL MACROS/Directives/End conditional
  2068.             LOCAL MACROS/Set macro label/#2
  2069.             CURSOR/Relative/Previous line
  2070.             LOCAL MACROS/Previous macro label/#2
  2071.             LOCAL MACROS/Directives/End conditional
  2072.             LOCAL MACROS/Previous macro label/#1
  2073.  
  2074. Notice that the directive "Start conditional" was not required in  the  above
  2075. example, as conditional sections were NOT nested.
  2076.  
  2077. When you are creating a macro, and you are asked for a string (even the  name
  2078. of  a  file  to load), if you select "okay" or press return after supplying a
  2079. string, the string will be stored in the macro definition, and will  be  used
  2080. when  the  macro  is  later executed, unless at the time that you execute the
  2081. macro, "LOCAL MACROS/Interactive/" has been set to "ON". In  this  case,  you
  2082. will  be  prompted for any strings that are requested during the execution of
  2083. the macro.  Normally, this will not be required, but it does  give  you  more
  2084. control  over  an  executing  macro,  especially if it was created by someone
  2085. other than yourself.
  2086.  
  2087. If, when creating a macro, you are asked for a string, and you want to  force
  2088. the  user  to  input  a  string during the execution of the macro, you should
  2089. select the "cancel" gadget in the string  requester.   Any  string  that  you
  2090. typed into the requester will still be used while creating the macro, however
  2091. when  the  macro  is  executed, the user is forced to input a new string each
  2092. time, even though 'Interactive' may be set to  "OFF".   Instead  of  actually
  2093. supplying  a  string  literal  to  a  string  requester,  you may instead use
  2094. indirection, to force the string to get copied from either  the  accumulator,
  2095. or from one of the buffers A-M.  For example, if the accumulator contains the
  2096. string  "MOVE", and you wish to create a label called "MOVE", select "LABELS/
  2097. Create single/Label", and when asked for the label name, press the escape key
  2098. twice, and select the "okay" gadget, or  press  "return".   If  the  required
  2099. string  was  in buffer C, instead of pressing the escape key twice, you would
  2100. press it once, followed immediately by "C".
  2101.  
  2102. Buffers A-M are simply 13 separate 240-byte string buffers, in which you  can
  2103. store  any  strings  that  you  like.  A more appropriate name might be 'text
  2104. registers'.  Buffers L and M are special, in that  if  you  select  "STRINGS/
  2105. Define  string/M",  if buffer L is not empty, the string contained in it will
  2106. be used as the prompt,  in  the  requester.   This  is  handy  during  macros
  2107. functions  where  you  want to get a string from the user.  The user can then
  2108. see what the string is required for.
  2109.  
  2110. Normally, every function you put into a macro definition  will  be  executed.
  2111. This  does  not  always  have to be the case.  The "LOCAL MACROS/Commentary/"
  2112. functions sets the commentary level.  When creating a macro, if you  set  the
  2113. commentary  level  to  "None", it is like specifying "The functions following
  2114. are absolutely essential to the execution of this macro".   If  you  set  the
  2115. commentary level to "Full" during the creation of a macro, you are specifying
  2116. "The  functions  following  are by no means required, they are simply running
  2117. commentary, perhaps explaining what is happening in the macro at this point".
  2118. Thus, by setting the commentary level during the creation of a macro, you are
  2119. letting ReSource know how important the  functions  are,  that  follow.   The
  2120. commentary  level  may be changed many times during a macro, and for tutorial
  2121. macros, such as showing someone how to disassemble/zap a particular  program,
  2122. the  commentary  level  should  be  set appropriately.  When it comes time to
  2123. execute the macro, if the commentary level is  set  to  "Full"  by  the  user
  2124. before  the  macro  starts  executing, ALL functions within the macro will be
  2125. executed normally.  If the commentary level was set to something  other  than
  2126. "Full", only those functions in the macro that were set to a commentary level
  2127. lower  than  that  presently  set, will be executed; the rest will be skipped
  2128. over.  Examine the following example macro:
  2129.  
  2130.             LOCAL MACROS/Commentary level/Full
  2131.             CURSOR/Relative/Next line
  2132.             LOCAL MACROS/Commentary level/Heavy
  2133.             CURSOR/Relative/Next line
  2134.             LOCAL MACROS/Commentary level/Normal
  2135.             CURSOR/Relative/Next line
  2136.             LOCAL MACROS/Commentary level/Light
  2137.             CURSOR/Relative/Next line
  2138.             LOCAL MACROS/Commentary level/None
  2139.             CURSOR/Relative/Next line
  2140.  
  2141. If you set the commentary level to "None" and execute this macro, the  cursor
  2142. will  move  down  one  line.  If you set the commentary level to "Light", and
  2143. execute this macro, the cursor will move down two  lines.   If  you  set  the
  2144. commentary  level to "Full" and execute this macro, the cursor will move down
  2145. five lines.  Using the "SPECIAL FUNCTIONS/Dos command" function, you can  use
  2146. the  "SAY"  command,  to  add  speech  to  macros,  to give excellent running
  2147. commentary to tutorial macros.
  2148.  
  2149. While executing a macro, if you have set the  execution  speed  to  "Wait  on
  2150. mouse", you can use other functions, perhaps to scroll backwards or forwards,
  2151. to  see  what  effect  the last function had on the file.  When you press the
  2152. left mouse button to single-step the next function in the macro,  the  cursor
  2153. address  is  restored in case you didn't return the cursor to the appropriate
  2154. place within the file.  If this was not  done,  macro  processing  would  not
  2155. proceed normally from that point on.
  2156.  
  2157. When you load a macro file, only one bank of  macros  is  affected.   If  the
  2158. macro file only contains one macro, then only the one macro in that bank will
  2159. be overwritten, and the rest will remain untouched.  Thus, it is possible for
  2160. a macro in the "LOCAL MACROS" bank to load other local macro files, giving an
  2161. "overlay" effect.
  2162.  
  2163. 2.9.1.1     STRINGS/Get/Label:
  2164. If there is a label defined at the cursor location, it will be copied to  the
  2165. accumulator.
  2166.  
  2167. 2.9.1.2     STRINGS/Get/Symbol:
  2168. Copy the first symbol on the current line to the accumulator.
  2169.  
  2170. 2.9.1.3     STRINGS/Get/Symbol - dest:
  2171. Copy the second symbol on the current line to the accumulator.
  2172.  
  2173. 2.9.1.4     STRINGS/Get/Symbol value:
  2174. Get the value of the first number on the current line, and write text to  the
  2175. accumulator,  representing  that  value in hex, decimal, or binary, as set by
  2176. the "STRINGS/Accumulator/" options.  The 'operand size' will be set  by  this
  2177. function.
  2178.  
  2179. 2.9.1.5     STRINGS/Get/Symbol value - dest:
  2180. Get the value of the second number in the current line, and write text to the
  2181. accumulator, representing that value in hex, decimal, or binary,  as  set  by
  2182. the  "STRINGS/Accumulator/"  options.  The 'operand size' will be set by this
  2183. function.
  2184.  
  2185. 2.9.1.6     STRINGS/Get/End-of-line comment:
  2186. Copy the end-of-line comment attached to the current line to the accumulator.
  2187.  
  2188. 2.9.1.7     STRINGS/Get/Full-line comment:
  2189. Copy the first  full-line  comment  attached  to  the  current  line  to  the
  2190. accumulator.
  2191.  
  2192. 2.9.1.8     STRINGS/Get/Search string:
  2193. Copy the current search string to the accumulator.
  2194.  
  2195. 2.9.1.9     STRINGS/Get/Filename:
  2196. Copy the current filename to the accumulator.
  2197.  
  2198. 2.9.1.10    STRINGS/Get/Save .asm name:
  2199. If the current file has already been saved as source code (to a ".asm" file),
  2200. copy the filename used to the accumulator.   If  the  current  file  has  not
  2201. already  been  saved, the name will be the same as the current filename, with
  2202. ".asm" appended.
  2203.  
  2204. 2.9.1.11    STRINGS/Get/Save .RS name:
  2205. If the current file has already been saved to a .RS file, copy  the  filename
  2206. used to the accumulator.  If the current file has not already been saved, the
  2207. name  will  be  the same as the current filename, with ".RS" appended, unless
  2208. ".RS" is already appended.
  2209.  
  2210. 2.9.1.12    STRINGS/Get/Macros filename:
  2211. Copy the current macros filename to the accumulator.
  2212.  
  2213. 2.9.1.13    STRINGS/Get/Keytable filename:
  2214. Copy the current keytable filename to the accumulator.
  2215.  
  2216. 2.9.1.14    STRINGS/Get/Cursor longword:
  2217. Write the data where the cursor is to the accumulator in  hexadecimal.   This
  2218. may be a byte, word, or longword, depending on the setting of 'operand size'.
  2219.  
  2220. 2.9.1.15    STRINGS/Get/Cursor offset:
  2221. The currently displayed cursor location is written into  the  accumulator  in
  2222. hexadecimal as a longword (the "operand size" is set to longwords).
  2223.  
  2224. 2.9.1.16    STRINGS/Get/Accumulator length:
  2225. The length of the string currently in the accumulator  is  written  into  the
  2226. accumulator  in hexadecimal.  The 'operand size' setting is not affected, but
  2227. is used to decide how many leading zeroes to use.
  2228.  
  2229. 2.9.1.17    STRINGS/Get/Partial save size:
  2230. The number representing the difference between the partial save end  and  the
  2231. partial  save  start  is  written  into  the  accumulator in hex, decimal, or
  2232. binary, as set by the "STRINGS/Accumulator/" options.  The 'operand size'  is
  2233. set to longwords.
  2234.  
  2235. 2.9.1.18    STRINGS/Get/File:
  2236. You will be asked to supply the name of a file, of which up to 240 characters
  2237. will be copied into the accumulator.  The data is copied "as-is", no  hex  to
  2238. ASCII translation is performed.
  2239.  
  2240. 2.9.1.19    STRINGS/Get/Attribute bits:
  2241. The attribute bits for the current location are copied into the  accumulator,
  2242. using  the  current  numeric  base  (hex/decimal/binary). The definitions for
  2243. these bits are described under "DISPLAY/Titlebar info/Attributes".
  2244.  
  2245. 2.9.2       STRINGS/Put label:
  2246. If the string within the accumulator is not used as a label  anywhere  within
  2247. the  current  file, it will be used as a label on the current line.  If it is
  2248. already used as a label, then a digit is appended to  it,  and  again  it  is
  2249. tested to see if a label already exists of that name.  This continues until a
  2250. unique  label  is  created,  then that label is attached to the current line.
  2251. This is a safe way of creating labels during macros.
  2252.  
  2253. 2.9.3       STRINGS/Put attributes:
  2254. If the accumulator contains a valid number, that number  will  overwrite  the
  2255. attributes  for  the  current  location.   The definitions for these bits are
  2256. described elsewhere.
  2257.  
  2258. 2.9.4.1     STRINGS/Edit functions/Clip start:
  2259. You will be asked to supply a string.  Starting from the left, each character
  2260. in the supplied string is compared to the character  in  the  accumulator  at
  2261. that  position, and if they are equal, the next character is compared, and so
  2262. on.  When either the end of one of the strings is found, or when  a  mismatch
  2263. is  found,  the  characters in the accumulator that matched are deleted.  The
  2264. question mark ('?') is used as a wildcard, and you can use the asterisk  once
  2265. only,  to  "delete  everything  until and including" the following character.
  2266. Examples follow:
  2267.  
  2268.      Accumulator    User-supplied string     Resulting accumulator
  2269.      -----------------------------------------------------------
  2270.      MOVE.L         M                        OVE.L
  2271.      MOVE.L         MUVE.L                   OVE.L
  2272.      MOVE.L         MOV.L                    E.L
  2273.      MOVE.L         move.l                   MOVE.L
  2274.      MOVE.L         M?V                      E.L
  2275.      MOVE.L         ???                      E.L
  2276.      MOVE.L         *.                       L
  2277.      MOVE.L         *M                       OVE.L
  2278.      MOVE.L         ?MOVE.L                  OVE.L
  2279.      _LVOAllocMem   _LVO                     AllocMem
  2280.      $00000004      $000000                  04
  2281.  
  2282. 2.9.4.2     STRINGS/Edit functions/Clip end:
  2283. Similar to the above function, except clipping is performed on the end of the
  2284. accumulator string.  The question mark is still used as a wildcard,  but  the
  2285. asterisk does not have a special meaning in this function.  Examples follow:
  2286.  
  2287.      Accumulator    User-supplied string     Resulting accumulator
  2288.      -----------------------------------------------------------
  2289.      MEMF_PUBLIC    ?PUBLIC                  MEMF
  2290.      MEMF_PUBLIC    ???                      MEMF_PUB
  2291.      MEMF_PUBLIC    ?LC                      MEMF_PUBLI
  2292.      meMcollAOVL_   OVL_                     meMcollA
  2293.  
  2294. 2.9.4.3     STRINGS/Edit functions/Prepend:
  2295. You will be asked to supply a string, which will be prepended  to  (added  to
  2296. the  beginning of) the accumulator, providing that the resulting string is no
  2297. longer than 240 characters.  Examples follow:
  2298.  
  2299.      Accumulator    User-supplied string     Resulting accumulator
  2300.      -----------------------------------------------------------
  2301.      PUBLIC         MEMF_                    MEMF_PUBLIC
  2302.      AllocMemSUB    _                        _AllocMemSUB
  2303.      PUBLIC         CHIP                     CHIPPUBLIC
  2304.  
  2305. 2.9.4.4     STRINGS/Edit functions/Append:
  2306. You will be asked to supply a string, which will be appended to (added to the
  2307. end of) the accumulator, providing that the resulting  string  is  no  longer
  2308. than 240 characters.  Examples follow:
  2309.  
  2310.      Accumulator    User-supplied string     Resulting accumulator
  2311.      -----------------------------------------------------------
  2312.      PUBLIC         MEMF_                    PUBLICMEMF_
  2313.      AllocMemSUB    _                        AllocMemSUB_
  2314.      PUBLIC         CHIP                     PUBLICCHIP
  2315.      AllocMem       SUB                      AllocMemSUB
  2316.  
  2317. 2.9.4.5     STRINGS/Edit functions/Reverse:
  2318. The contents of the accumulator are reversed.  Examples follow:
  2319.  
  2320.      Accumulator    Resulting accumulator
  2321.      ----------------------------------------
  2322.      PUBLIC         CILBUP
  2323.      AllocMemSUB    BUSmeMcollA
  2324.      AllocMem       meMcollA
  2325.  
  2326. 2.9.4.6     STRINGS/Edit functions/Lower case:
  2327. Any upper case characters in the accumulator are changed to their lower  case
  2328. counterparts.  Examples follow:
  2329.  
  2330.      Accumulator    Resulting accumulator
  2331.      ----------------------------------------
  2332.      PUBLIC0123     public01243
  2333.      All0cMemSUB    all0cmemsub
  2334.      All0cMem       all0cmem
  2335.  
  2336. 2.9.5       STRINGS/Operand size/:
  2337. Some background information is required  here:  Some  functions  in  ReSource
  2338. require  to  know  whether to work at the byte, word, or longword level.  For
  2339. example, "STRINGS/Get/Cursor value" could get a byte, word, or longword  from
  2340. the  cursor  position,  and this is your way of specifying at which level you
  2341. wish those functions to work.   Generally,  they  specify  the  size  of  the
  2342. numeric  operand  in  the  accumulator.   Some functions that write a numeric
  2343. value into the accumulator will set the operand size themselves, others  that
  2344. get the value out of the accumulator need to know the operand size.
  2345.  
  2346. 2.9.6       STRINGS/Accumulator/:
  2347. Options control whether to write the results of any maths  functions  to  the
  2348. accumulator in hex, decimal, or binary.
  2349.  
  2350. 2.9.7.1     STRINGS/Maths functions/Increment:
  2351. Some background information is required here: All maths functions  make  some
  2352. change  to  the  number  within  the  accumulator.   If the string within the
  2353. accumulator is not a valid number (hex, decimal or binary), the function will
  2354. fail.  Some functions are immediate, others will ask the user for a  required
  2355. operand, such as what to add to the accumulator.
  2356.  
  2357. The increment function adds one to the accumulator.  If the resulting  number
  2358. develops  a  carry  (using  the  current  operand  size), a macro 'fail' will
  2359. result.  Thus, loops in macros can exit after a given number  of  iterations,
  2360. rather than a failed search, etc.
  2361.  
  2362. 2.9.7.2     STRINGS/Maths functions/Decrement:
  2363. Similar to the above  function,  except  that  one  is  subtracted  from  the
  2364. accumulator.   If a carry results, a macro 'fail' will occur.  Thus, loops in
  2365. macros can exit after a given number of  iterations,  rather  than  a  failed
  2366. search, etc.
  2367.  
  2368. 2.9.7.3     STRINGS/Maths functions/Add:
  2369. You will be asked for a number, to be added to the accumulator.  If  a  carry
  2370. results, a macro 'fail' will occur.
  2371.  
  2372. 2.9.7.4     STRINGS/Maths functions/Subtract:
  2373. You will be asked for a number, to be subtracted from the accumulator.  If  a
  2374. carry results, a macro 'fail' will occur.
  2375.  
  2376. 2.9.7.5     STRINGS/Maths functions/Multiply:
  2377. You will be asked for a number, to be multiplied by  the  number  within  the
  2378. accumulator.   If  a  carry  results, a macro 'fail' will occur.  Full 32-bit
  2379. multiplies are supported, however the setting of 'operand size' is used  when
  2380. determining the size of the operands.
  2381.  
  2382. 2.9.7.6     STRINGS/Maths functions/Divide:
  2383. You will be asked for a number.  The contents  of  the  accumulator  will  be
  2384. divided by the number that you specify.  The divide function does NOT operate
  2385. on  32-bit  operands,  but  otherwise  will work at the currently set operand
  2386. size.  If the current operand size is set to longwords, the  divide  will  be
  2387. performed on the lower 16 bits only.
  2388.  
  2389. 2.9.7.7     STRINGS/Maths functions/Negate:
  2390. The number within the accumulator is negated, using the currently set operand
  2391. size.  If the result is zero, a macro 'fail' will result.
  2392.  
  2393. 2.9.7.8     STRINGS/Maths functions/Logical NOT:
  2394. The number within the accumulator is NOT'd  in  bitwise  fashion,  using  the
  2395. currently  set  operand  size.   If  the  result is zero, a macro 'fail' will
  2396. result.
  2397.  
  2398. 2.9.7.9     STRINGS/Maths functions/Logical AND:
  2399. You will be asked to supply a number, which will be bitwise  AND'd  with  the
  2400. contents  of  the  accumulator,  and  the  result  is  stored  back  into the
  2401. accumulator.  If the result is zero, a macro 'fail' will result.
  2402.  
  2403. 2.9.7.10    STRINGS/Maths functions/Logical OR:
  2404. You will be asked to supply a number, which will be  bitwise  OR'd  with  the
  2405. contents  of  the  accumulator,  and  the  result  is  stored  back  into the
  2406. accumulator.  If the result is zero, a macro 'fail' will result.
  2407.  
  2408. 2.9.7.11    STRINGS/Maths functions/Exclusive OR:
  2409. You will be asked to supply a number, which will  be  bitwise  exclusive-OR'd
  2410. with  the contents of the accumulator, and the result is stored back into the
  2411. accumulator.  If the result is zero, a macro 'fail' will result.
  2412.  
  2413. 2.9.8       STRINGS/Define string/:
  2414. These functions allow to you define the contents of either  the  accumulator,
  2415. or  one of the string buffers A-M.  Whenever you are asked for a string using
  2416. the simple string requester (NOT the large file requester),  you  can  either
  2417. type in a string literal, or input an escape character (just press the escape
  2418. key),  followed by either another escape character, or one of the letters A-M
  2419. inclusive.  If the second character is the escape character, the string being
  2420. requested will be  copied  from  the  accumulator  instead.   If  the  second
  2421. character  that  you typed (after the escape character) is one of the letters
  2422. A-M, then the  string  being  requested  will  instead  be  copied  from  the
  2423. appropriate buffer A-M.  This applies even when you are defining the contents
  2424. of  one  of  the  string buffers.  This method of using indirection should be
  2425. particularly handy in sophisticated macros.
  2426.  
  2427. The maximum string length in any buffer (including the  accumulator)  is  240
  2428. characters.
  2429.  
  2430. 2.9.9       STRINGS/Swap with buffer/:
  2431. The contents of the accumulator is swapped with the contents  of  the  buffer
  2432. that you select.
  2433.  
  2434. 2.9.10      STRINGS/Input buffer/:
  2435. The Input and Output buffers  can  be  used  to  buffer  textual  information
  2436. between  a file and the accumulator within ReSource.  To transfer information
  2437. into ReSource, you load the input buffer, using "Load", and transfer  a  line
  2438. at  a  time to the accumulator, using "Read line".  Each time you read a line
  2439. from  the  input  buffer,  it  replaces  the  contents  of  the  accumulator.
  2440. Successive  uses  of  "Read  line"  will  get successive lines from the input
  2441. buffer.  A line means all text up to  a  line  feed,  to  a  maximum  of  240
  2442. characters.   The  line  feed  is  NOT  transferred, as the line will be null
  2443. terminated within the accumulator.  To start reading lines from the start  of
  2444. the  buffer again, use "Restart".  For example, you may have a list of labels
  2445. that you wish to put into the current file.  Use "Load" to get  the  list  of
  2446. labels into the input buffer, then create a macro something like:
  2447.  
  2448.             CURSOR/Relative/Next label
  2449.             STRINGS/Input buffer/Read line
  2450.             STRINGS/Put label
  2451.             LOCAL MACROS/Previous macro label/#1
  2452.  
  2453. The first function will advance the cursor to the  next  label.   The  second
  2454. function  reads  the  next  label  to  use  into  the accumulator.  The third
  2455. function will replace the current label with the one in the accumulator.  The
  2456. last function ("LOCAL MACROS/Previous macro label/#1") is optional.  It  will
  2457. make  the  function repeat for the entire file, or the entire list of labels,
  2458. whichever ends first.
  2459.  
  2460. 2.9.11      STRINGS/Output buffer/:
  2461. The output buffer is used to hold information that  you  wish  to  save  from
  2462. ReSource.   The  idea here is that you append the contents of the accumulator
  2463. to the end of the output buffer, and eventually save the entire  contents  of
  2464. the output buffer to a file.  For example, you might wish to create a list of
  2465. labels  for  the  current file (see "STRINGS/Input buffer/:").  The following
  2466. macro will do this:
  2467.  
  2468. Note: Prior to actually running this macro, you should ensure that the cursor
  2469. is at the start of file, and use the function "STRINGS/Output  buffer/Clear",
  2470. to ensure the output buffer is empty.
  2471.  
  2472.             CURSOR/Relative/Next label
  2473.             STRINGS/Get/Label
  2474.             STRINGS/Edit functions/Append
  2475.             STRINGS/Output buffer/Append accumulator
  2476.             LOCAL MACROS/Previous macro label/#1
  2477.  
  2478. The first line will move the cursor to the  next  label  in  the  file.   The
  2479. second  function  will put the current label into the accumulator.  The third
  2480. function will prompt you for a string to append to the accumulator.   A  line
  2481. feed  (ASCII  value  10) is required here, to do this, first click inside the
  2482. requester string gadget, hold down the ctl key, and  press  "J",  then  press
  2483. return  or  click on the "OKAY" gadget.  The fourth function, "STRINGS/Output
  2484. buffer/Append accumulator", will add the current contents of the  accumulator
  2485. to  the  end  of  the Output buffer.  Memory is dynamically allocated for the
  2486. output buffer, so maximum size is only determined  by  how  much  memory  you
  2487. have.   The  fifth function is optional, use it if you want the macro to loop
  2488. until all labels in the current file are added to the  list.   Once  this  is
  2489. done,  use  "STRINGS/Output  buffer/Save" to save the current contents of the
  2490. output buffer.  You will be asked for a filename to use.  In  practice,  most
  2491. people will probably combine several pieces of information for each line that
  2492. gets  appended  to  the  output buffer, such as label, followed by its offset
  2493. from the start of the file, or its data type, etc.
  2494.  
  2495. 2.10.1      SPECIAL FUNCTIONS/Repeat last command:
  2496. Repeat the last menu function used.  Functions bound  to  keys  may  be  used
  2497. without  resetting the last menu function.  For example, suppose you access a
  2498. symbol base from the "SYMBOLS 2" menu.  You then define  some  labels,  using
  2499. whatever  KEY  that  function is bound to.  Finally, you use the "Repeat last
  2500. command" KEY.  This  will  invoke  the  "SYMBOLS  2"  function,  rather  than
  2501. repeating  the  last  KEY  used.  Cursor movement functions are NOT repeated,
  2502. except the search functions.  This  function  should  be  bound  to  a  high-
  2503. priority key, such as the space bar, for best effect.
  2504.  
  2505. 2.10.2      SPECIAL FUNCTIONS/Dos Command:
  2506. You will be asked for a string, which will be given as the operand to the Dos
  2507. "execute" function.  Anything that you normally type into a CLI  window,  you
  2508. can  give  as a command.  Any output will go to the CLI window from which you
  2509. started ReSource, unless  you  redirect  the  output  elsewhere.   The  "Run"
  2510. command must be in your C: directory.
  2511.  
  2512. 2.10.3      SPECIAL FUNCTIONS/Zap:
  2513. You will be asked for a number/string, which will  overwrite  the  byte/word/
  2514. longword/characters  at the cursor position.  The current setting of 'operand
  2515. size' is used.  Using PROJECT/Open binary file, then this function,  followed
  2516. by  "SAVE/Save  binary  image/ALL", you can quickly modify a program, without
  2517. having to go through the  disassemble/edit/reassemble/link  cycle.   However,
  2518. when  using this method of modification, you are restricted as to the size of
  2519. changes that may be legally made.  For example, you cannot insert extra  code
  2520. or data, nor can you delete it.  You may "NOP" it instead, though.
  2521.  
  2522. If the string that you supply starts with a single quote ("'"), the following
  2523. characters are treated as a string, and are copied  to  the  cursor  position
  2524. "as-is".
  2525.  
  2526. If the string that you supply  starts  with  "$",  the  following  number  is
  2527. assumed  to  be  hexadecimal.  If the string that you supply starts with "%",
  2528. the number that follows is assumed to be binary, otherwise it is  assumed  to
  2529. be a decimal number.
  2530.  
  2531. 2.10.4      SPECIAL FUNCTIONS/Screen/:
  2532. "Front" moves ReSource's screen in front of all other screens.  "Back"  moves
  2533. ReSource's screen behind all other screens.
  2534.  
  2535. 2.10.5      SPECIAL FUNCTIONS/Set task priority:
  2536. You will be asked for a number, representing the priority at which to set the
  2537. current task.  For example, if you have a  program  being  assembled  in  the
  2538. background, and you don't want it to slow down the operation of ReSource, you
  2539. might  set  the  task  priority  to  one  or  two.   Negative numbers are not
  2540. supported.  Sorry!  However, "$FF"  will  effectively  mean  "-1"  with  this
  2541. function.
  2542.  
  2543. 2.10.6      SPECIAL FUNCTIONS/Origin/:
  2544. There is sometimes a requirement to disassemble a block of code, as if it  is
  2545. loaded  to some particular area of memory, other than that to which it is now
  2546. loaded.  For example, if you disassemble Kickstart(TM), and save  the  binary
  2547. image,  then  later load this into ReSource, it will not disassemble properly
  2548. unless ReSource "thinks" that its origin is $FC0000.  To do  this,  load  the
  2549. file,  then  use  the "Specify" option.  Both the "Specify" and "Set" set the
  2550. origin to an absolute address; the "Set" option is  the  same  as  "Specify",
  2551. except that it assumes that the current loading address is to be used.  These
  2552. options  are  really  only useful if the file is loaded as a binary image, or
  2553. from track, or memory.  If loaded from an executable, the reloc32 information
  2554. will ensure that proper relocation is done where needed.  It  is  because  no
  2555. reloc32  information  is  available when loading files other than load files,
  2556. that this function is required.  To  remove  the  origin,  so  that  it  uses
  2557. whatever actual address the file is loaded to, use the "Clear" option.
  2558.  
  2559. 2.10.7      SPECIAL FUNCTIONS/Convert xx(A4) EA's/:
  2560. These functions were specifically designed to be used when disassembling  'C'
  2561. programs,  in which the A4 register is frequently used as a base register for
  2562. accessing data, throughout all or most of the program.  Let's use an  example
  2563. program here:
  2564.  
  2565.             SECTION test000000,CODE
  2566.             LEA     lbB00011E,A4             ;scanning has already been done
  2567.             LEA     0(A4),A1
  2568.             MOVE.L  $000C(A4),D0
  2569.             ...                              ;rest of code
  2570.  
  2571.             SECTION test00011E,DATA
  2572.  lbB00011E  dc.b    'dos.library',0
  2573.             dc.l    $00010001
  2574.             END
  2575.  
  2576. In the above example program, the A4 register points to the start of the data
  2577. segment.  There are three ways to tell ReSource where the A4 register points;
  2578. in the above example, the "This operand" function  could  be  used  with  the
  2579. cursor  at  start  of file, or the "This address" function could be used with
  2580. the cursor at offset $00011E,  or  the  "Specify"  function  could  be  used,
  2581. supplying  a  parameter  of  "$11E".   Basically,  with this function you are
  2582. telling ReSource where the  A4  register  can  be  assumed  to  be  pointing,
  2583. relative  to  the  start  of  the  program.  After you do this, any effective
  2584. address that involves a word  offset  to  the  A4  register,  will  be  shown
  2585. symbolically.   If  you  have  selected  "Convert  xx(A4) EA's/Absolute", the
  2586. effective addresses will be shown as absolute addresses.  Thus,  the  example
  2587. program above will appear as:
  2588.  
  2589.             SECTION test000000,CODE
  2590.             LEA     lbB00011E,A4
  2591.             LEA     lbB00011E,A1
  2592.             MOVE.L  lbL00012A,D0
  2593.             ...                              ;rest of code
  2594.  
  2595.             SECTION test00011E,DATA
  2596.  lbB00011E  dc.b    'dos.library',0
  2597.  lbL00012A  dc.l    $00010001                ;This label will be created after
  2598.             END                              ;left-Amiga mouse-button is used.
  2599.  
  2600. On the other hand, if you had selected "Convert  xx(A4)  EA's/Relative",  the
  2601. effective  addresses would be shown as symbolic word offsets, and our example
  2602. program would look like this:
  2603.  
  2604.             SECTION test000000,CODE
  2605.             LEA     DT,A4                    ;Note the new base label "DT"
  2606.             LEA     lbB00011E-DT(A4),A1
  2607.             MOVE.L  lbL00012A-DT(a4),D0
  2608.             ...                              ;rest of code
  2609.  
  2610.             SECTION test00011E,DATA
  2611. DT
  2612. lbB00011E   dc.b    'dos.library',0
  2613. lbL00012A   dc.l    $00010001                ;This label will be created after
  2614.             END                              ;left-Amiga mouse-button is used.
  2615.  
  2616. The advantage here is that labels can automatically  be  created  where  they
  2617. could not before.  After more iterations, our code could look like this:
  2618.  
  2619.             SECTION test000000,CODE
  2620.             LEA     DT,A4
  2621.             LEA     DOSName-DT(A4),A1
  2622.             MOVE.L  Mem_Parms-DT(a4),D0
  2623.             ...                              ;rest of code
  2624.  
  2625.             SECTION test00011E,DATA
  2626.  DT
  2627.  DOSName    dc.b    'dos.library',0
  2628.  Mem_Parms  dc.l    MEMF_CLEAR!MEMF_PUBLIC
  2629.             END
  2630.  
  2631. If this conversion process is not used, it is likely that  the  program  will
  2632. not  successfully  re-assemble,  as  different  assemblers  assemble the same
  2633. source code into different  opcodes.   For  example,  the  assembler  that  I
  2634. normally  use  does  virtually no optimizing, and so the resulting program is
  2635. often larger than the original, even if I did not  modify  the  source  code.
  2636. For example:
  2637.  
  2638.             MOVE.L  4,A6
  2639.  
  2640. If absolute long addressing is used, the instruction above will  be  6  bytes
  2641. long,  whereas  if absolute short addressing is used, it will be only 4 bytes
  2642. long.  Where you wish to do EA conversions in only a portion  of  a  program,
  2643. you can set the lower and upper limits.
  2644.  
  2645. Changing to absolute EA's will increase the size of  the  resulting  program,
  2646. unless  you  convert  back to relative addressing, within the source code.  I
  2647. believe that one of the features of BLINK (from the Software Distillery)  can
  2648. help to make this conversion, during the link process.
  2649.  
  2650. 2.10.8      SPECIAL FUNCTIONS/Convert specific EA's/:
  2651. Please read  and  understand  the  "SPECIAL  FUNCTIONS/Convert  xx(A4)  EA's"
  2652. functions  first!  Where  you  want  to  do  specific  EA (Effective Address)
  2653. conversions, use "Set base #1" (or #2, or #3), when the cursor is the same as
  2654. where the base register (whatever that is, it does not have  to  be  A4  this
  2655. time)  can  be assumed to point to.  Assuming that you set base #1, and it is
  2656. the A5 register that is being used as a base register, you will then use  the
  2657. "Convert W/Base #1" function to convert lines like:
  2658.  
  2659.             MOVE.L  $0032(A5),A6 into:
  2660.  
  2661.             MOVE.L  lbL0014AC(A5),A6
  2662.  
  2663. Note here that there has not actually been an EA conversion, but a label  has
  2664. been created, the data type at label "lbL0014AC" has been determined and set,
  2665. and  a  symbol ("lbL0014AC") has been created for this line.  It is up to you
  2666. then to make the necessary changes to  the  resulting  source  code,  if  re-
  2667. assembling  is required.  Whereas the "Convert xx(A4) EA's" function converts
  2668. immediately and automatically, you must use the "Convert W/Base #1"  function
  2669. on  each  line that you want converted.  If you wish to convert a destination
  2670. address, use the "SYMBOLS 1/Set Source/dest/Destination" function first.
  2671.  
  2672. 2.10.9      SPECIAL FUNCTIONS/Data type set/:
  2673. These functions affect how  the  "SPECIAL  FUNCTIONS/Convert  specific  EA's"
  2674. functions  work.  When the data type must be determined, it can be automatic,
  2675. or you can force it to be set to Bytes, Words, Longwords, ASCII, Code.
  2676.  
  2677. 2.10.10     SPECIAL FUNCTIONS/Convert to../:
  2678. The setting here will determine the type of symbol created when the  "SPECIAL
  2679. FUNCTIONS/Convert  specific  EA's"  functions are used, either an Absolute or
  2680. Offset value.
  2681.  
  2682. 2.10.11     SPECIAL FUNCTIONS/Reloc32/:
  2683. Use these functions to specifically delocate or relocate  the  current  file.
  2684. This  is  only  useful  if  file was loaded from an executable, where reloc32
  2685. information is present.  Be aware that relocation  is  performed  immediately
  2686. after  the  "PROJECT/O'lay  binary  image"  function, when a file is actually
  2687. loaded.
  2688.  
  2689. 2.11.1      SAVE/O/P Directory:
  2690. You will be asked to supply the name of a directory.  Whenever you are  asked
  2691. to  supply the name of a file to save source code to, the name will have this
  2692. directory name prepended to it.  For example, if you supply the string "RAM:"
  2693. as the output directory name, and the current filename is "c:stack", when you
  2694. select "SAVE/Save .asm/ALL", the new name to save to will be "RAM:stack.asm".
  2695.  
  2696. 2.11.2.1    SAVE/Partial save/Set start:
  2697. For any partial saves, the current cursor position (as it  is  NOW)  will  be
  2698. where  the  save will start from.  By default, this position is equivalent to
  2699. the start of the file.
  2700.  
  2701. 2.11.2.2    SAVE/Partial save/Set end:
  2702. For any partial saves, the current cursor position will  be  where  the  save
  2703. will  end.  If this happens to be the last line in the file, any partial save
  2704. will include the last line.  Normally, the partial save will NOT include  the
  2705. line where the partial save end is set.
  2706.  
  2707. 2.11.3      SAVE/Save binary image/:
  2708. Save the current buffer contents "as-is", to a file.  If the file was  loaded
  2709. with "PROJECT/Open load file", and was NOT loaded as a binary image file, the
  2710. resulting  saved file will NOT be the same as that originally loaded, because
  2711. the loader information, and relocation information, has  been  stripped.   If
  2712. you  wish to load a file, and then save it exactly as it was loaded, you must
  2713. use "PROJECT/Open binary file".  Even though you may have disassembled memory
  2714. directly, or read tracks from a floppy disk, it does NOT stop you from saving
  2715. the binary image.  Once something is loaded into ReSource, it can be saved as
  2716. source code, as a binary image file, directly to memory, or it can be written
  2717. directly to a floppy disk,  to  a  specific  sector  or  track.   This  gives
  2718. fantastic  flexibility  for general hacking, for as little as one byte of the
  2719. current buffer can be saved to memory, to a binary image file, or  as  source
  2720. code.   Track writes must be in multiples of 512 bytes.  However the clipping
  2721. is done for you.
  2722.  
  2723. Save "Partial" is similar to the above function, except only the data between
  2724. the partial save start and the partial save end is saved.
  2725.  
  2726. 2.11.4      SAVE/Save .asm/:
  2727. You will be asked to supply the name of a file to save source  code  to,  for
  2728. the  entire  current buffer contents.  The output will be very similar to how
  2729. you see it on the display.
  2730.  
  2731. Save "Partial" is similar to the above function, except  only  the  code/data
  2732. between the partial save start and the partial save end is disassembled.
  2733.  
  2734. 2.11.5.1    SAVE/Calculate .asm size/ALL:
  2735. Calculates the size of the source code file that would result if you had used
  2736. the "SAVE/Save .asm/ALL" function.
  2737.  
  2738. 2.11.5.2    SAVE/Calculate .asm size/Partial:
  2739. Calculates the size of the source code file that would result if you had used
  2740. the "SAVE/Save .asm/Partial" function.  "Start" and "End" must have been  set
  2741. previously.
  2742.  
  2743. 2.11.6      SAVE/Save to memory/:
  2744. You will be asked to supply a memory address to  save  the  contents  of  the
  2745. current  buffer.   The  buffer will be saved "as-is"; it is NOT disassembled.
  2746. Care should be taken with this function, as a system crash will likely result
  2747. if you supply the wrong address.  By finding out where the current buffer  is
  2748. in  memory,  it is possible to copy one part of the current buffer to another
  2749. part.
  2750.  
  2751. Save "Partial" is similar to the above function, except that  only  the  data
  2752. between the partial save start and the partial save end is saved.
  2753.  
  2754. 2.11.7      SAVE/Save tracks/:
  2755. You will be asked for a string representing where to  start  writing  tracks.
  2756. The  first  parameter  you  give  must  be  either "DF0:", "DF1:", "DF2:", or
  2757. "DF3:". The second parameter is the starting cylinder to save to.  The  third
  2758. parameter  is optional, and represents an offset, in sectors, where the track
  2759. write is to start.  For example, to save the sector #3 on cylinder 5 on DF2:,
  2760. the parameters required would be "DF2: 5 3".  To save to the first sector  on
  2761. DF0:,  the  parameters  required would be "DF0: 0".  Whole sector writes ONLY
  2762. are done, clipping is performed automatically.
  2763.  
  2764. Save "Partial" is similar to the above function, except that  only  the  data
  2765. between  the  partial  save  start  and  the  partial  save  end  is   saved.
  2766. Furthermore, only even multiples of 512 bytes will be written.  For  example,
  2767. if the partial save size is 1027 bytes, only two sectors (1024 bytes) will be
  2768. written to the disk.
  2769.  
  2770. 2.11.8      SAVE/Tabs/:
  2771. Use to select between real tabs (ASCII value 9) and spaces being used in  the
  2772. output source code as separators.
  2773.  
  2774. 2.11.9      SAVE/Symbol table/:
  2775. When creating symbols, either automatically or manually, if  the  setting  of
  2776. this  function  is  to something other than "None", the value and name of the
  2777. symbol is stored, so that when the source code is saved, an equate table,  or
  2778. XREF  table  can be generated.  If this function is set to "EQUate", a symbol
  2779. table similar to the following will precede the source  code  in  the  output
  2780. file:
  2781.  
  2782.      AG_OpenLib     EQU      $00030000
  2783.      AO_DOSLib      EQU      $00008007
  2784.      AT_Recovery    EQU      $00000000
  2785.      _LVOAlert      EQU      $FFFFFF94
  2786.      _LVOClose      EQU      $FFFFFFDC
  2787.      _LVOCreateProc EQU      $FFFFFF76
  2788.      _LVOCurrentDir EQU      $FFFFFF82
  2789.  
  2790. If, instead, this function is set to "XREF", a symbol table  similar  to  the
  2791. following will preceed the source code in the output file:
  2792.  
  2793.                     XREF     AG_OpenLib
  2794.                     XREF     AO_DOSLib
  2795.                     XREF     AT_Recovery
  2796.                     XREF     _LVOAlert
  2797.                     XREF     _LVOClose
  2798.                     XREF     _LVOCreateProc
  2799.                     XREF     _LVOCurrentDir
  2800.  
  2801. 2.12.1      OPTIONS 1/Show offsets/:
  2802. For lines displayed without labels, the current  offset  (relative  from  the
  2803. start  of  the  file) will be displayed where the label is usually displayed.
  2804. If "DISPLAY/Set counter" is used, offsets  will  be  relative  to  where  the
  2805. counter was set.
  2806.  
  2807. 2.12.2      OPTIONS 1/Display beep/:
  2808. Many functions demand attention from the user, and a display beep is used for
  2809. this purpose.  Normally, this will make the screen flash.   However,  if  you
  2810. have  run  the program "addbeep", or a similar DisplayBeep() replacement, you
  2811. will hear an audible "beep" instead.  If you don't appreciate the beep,  then
  2812. switch it off.
  2813.  
  2814. 2.12.3      OPTIONS 1/User feedback/:
  2815. Many functions will give informative messages, to let the user know  what  is
  2816. happening  internally.   If you don't appreciate the feedback, then switch it
  2817. off.
  2818.  
  2819. 2.12.4      OPTIONS 1/Feedback Delays/:
  2820. If you have User feedback set to "OFF", then the setting of this function  is
  2821. irrelevant.   If  feedback  is  ON,  you  may occasionally find that feedback
  2822. message are being  displayed  too  fast  for  you  to  read  them.   This  is
  2823. especially  so  when opening a load file, since as many as thirty informative
  2824. messages can be displayed in between raster scans, which means that you don't
  2825. actually get to see any of the messages at all.   If  normal  text  rendering
  2826. were used, rather than using the special rendering routines in ReSource, this
  2827. would  probably  not be a problem, as the writing of the text itself would be
  2828. done much slower, and you would probably get time to read at  least  some  of
  2829. the messages.  If you set feedback delays to "ON", there will be a one second
  2830. delay after each message is displayed, which should be plenty of time to read
  2831. each  message.   While  you  hold the menu button down, feedback messages are
  2832. skipped altogether.
  2833.  
  2834. 2.12.5      OPTIONS 1/Labels/:
  2835. If this option is set to ON, labels will be displayed.  This is the default.
  2836.  
  2837. 2.12.6      OPTIONS 1/Hidden labels/:
  2838. If this option is set to ON, hidden labels (labels attached to a byte in  the
  2839. middle of a line of code/data) will be displayed.  This is the default.
  2840.  
  2841. 2.12.7      OPTIONS 1/Symbols/:
  2842. If this option is set to ON, symbols will be displayed.  This is the default.
  2843.  
  2844. 2.12.8      OPTIONS 1/End-of-line comments/:
  2845. If this option is set to ON, end-of-line comments will be displayed.  This is
  2846. the default.
  2847.  
  2848. 2.12.9      OPTIONS 1/Full-line comments/:
  2849. If this option is set to ON, full-line comments will be displayed.   This  is
  2850. the default.
  2851.  
  2852. 2.12.10     OPTIONS 1/Chip-load info/:
  2853. If this option is set to ON, where a section statement is displayed, and that
  2854. section either is forced to load into chip memory, or is forced to load  into
  2855. fast  memory, a ",CHIP" or ",FAST" will be appended to the section statement.
  2856. Not all assemblers support this parameter for the section statement,  so  you
  2857. may want to switch this option OFF if your assembler can't handle it.
  2858.  
  2859. 2.12.11     OPTIONS 1/Section statements/:
  2860. If this option is set to ON, section statements will be displayed.   This  is
  2861. the default.
  2862.  
  2863. 2.12.12     OPTIONS 1/End statement/:
  2864. If this option is set to ON, the "END" statement will  be  displayed  as  the
  2865. last line in the file.  This is the default.
  2866.  
  2867. 2.12.13     OPTIONS 1/DCB statements/:
  2868. If this option is set to  ON,  "dcb"  type  statements  will  be  used  where
  2869. appropriate.  This is NOT the default.  For example, the following data:
  2870.  
  2871.             dc.b    0
  2872.             dc.b    0
  2873.             dc.l    7
  2874.             dc.l    8
  2875.             dc.l    8
  2876.             dc.l    8
  2877.             dc.l    8
  2878.             dc.l    8
  2879.             dc.l    8
  2880.  
  2881. will be shown as:
  2882.  
  2883.             dcb.b   2,0
  2884.             dc.l    7
  2885.             dcb.l   6,8
  2886.  
  2887. This is useful for shrinking the required .asm file  size,  especially  where
  2888. there are large areas of zeroes.
  2889.  
  2890. 2.12.14     OPTIONS 1/Reference recognition/:
  2891. If this option is set to  ON,  references  to  memory  locations  within  the
  2892. current file are recognized.  For example, assuming that the absolute address
  2893. of  the start of the current file is at $200000, the following lines might be
  2894. displayed with Reference recognition ON:
  2895.  
  2896.             dc.l    $48638335
  2897.             dc.l    START+$1097
  2898.             dc.l    START+$3086
  2899.  
  2900. whereas if reference recognition was OFF, it would be displayed as:
  2901.  
  2902.             dc.l    $48638335
  2903.             dc.l    $201097
  2904.             dc.l    $203086
  2905.  
  2906. Reference recognition is ON by default.  If any pointer (32  bits)  is  in  a
  2907. reloc32  area,  the reference will be recognized regardless of the setting of
  2908. this option.
  2909.  
  2910. 2.13.1      OPTIONS 2/ASCII longs/:
  2911. If this option is set to ON, where longword operands are  recognized  as  all
  2912. ASCII  characters,  such  as 'KICK', they will be displayed as such.  This is
  2913. the default.  By using the "DISPLAY/Set numeric base/ASCII", lines such as:
  2914.  
  2915.             MOVE.L  #'DOS'<<8,(A2)
  2916.             MOVE.L  #'KICK',(A2)
  2917.  
  2918. or virtually any lines containing valid ASCII characters may be independently
  2919. displayed as ASCII, despite the setting here.
  2920.  
  2921. 2.13.2      OPTIONS 2/Short branches/:
  2922. If this option is set to ON, any short branches will be  displayed  as  such,
  2923. with  the  ".S" appended to the opcode.  This is the default.  Note that this
  2924. option will NOT show you all POSSIBLE short branches,  only  those  that  are
  2925. already present in the code that's being disassembled.
  2926.  
  2927. 2.13.3      OPTIONS 2/Separate labels/:
  2928. Under normal conditions, if a label is  longer  than  20  characters,  it  is
  2929. broken  at  that  point,  and  the remainder is shown on the next line.  This
  2930. option forces the entire label to be shown on one line.
  2931.  
  2932. 2.13.4      OPTIONS 2/Label colons/:
  2933. This option will display colons ,":", after all labels.
  2934.  
  2935. 2.13.5      OPTIONS 2/Leading zeroes/:
  2936. Use these options to specify whether or not you wish the  leading  zeroes  on
  2937. hex values to be shown, e.g., "$0000003A" versus "$3A".
  2938.  
  2939. 2.13.6      OPTIONS 2/Assembler/:
  2940. Use these options to  specify  for  which  assembler  the  output  should  be
  2941. suitable.   Metacomco  output currently works with CAPE(TM) as well, although
  2942. smaller files will result with CAPE(TM) output.  Currently,  "dc.b"  will  be
  2943. shown  as "db", "dc.w" is shown as "dw", and "dc.l" is shown as "dl", if CAPE
  2944. is chosen.
  2945.  
  2946. 2.14        KEY BINDINGS/:
  2947. Every function in ReSource can be found in the menus.  You do not need to use
  2948. any keys at all, but you probably will want to.  You can bind any function to
  2949. any key, however there is just one function that makes no  sense  to  rebind,
  2950. and that is the "PROJECT/Abort" function.  Both Amiga-keys are supported, you
  2951. may use shift, alt, ctrl, lAmiga, rAmiga, shift-alt, shift-ctrl, alt-ctrl, or
  2952. shift-alt-ctrl  in  combination with any non-qualifier key, as a distinct key
  2953. to which to bind a function.  Thus, you have complete control over which keys
  2954. do what.  After re-binding some keys, you will  probably  want  to  save  the
  2955. keytable.   If  you  save  the keytable as "S:RS.keytable", it will be loaded
  2956. every time you run ReSource.  You  may  want  to  create  several  keytables,
  2957. suitable  for  doing  differing  program  types  (C,  assembler,  etc.). If a
  2958. keytable file is loaded, ALL current key bindings will be overwritten by  the
  2959. bindings  present  in  the  keytable.   If  you  don't load any keytable, and
  2960. ReSource couldn't find "S:RS.Keytable" when you first ran it, some keys  will
  2961. still be bound:
  2962.  
  2963.             right-Amiga Q      PROJECT/Quit
  2964.             right-Amiga O      Open load file
  2965.             up arrow           CURSOR/Relative/Next line
  2966.             down arrow         CURSOR/Relative/Previous line
  2967.             right arrow        CURSOR/Absolute/Fwd reference
  2968.             left arrow         CURSOR/Absolute/Previous location
  2969.             shift-up arrow     CURSOR/Relative/Previous page
  2970.             shift-down arrow   CURSOR/Relative/Next page
  2971.  
  2972. To rebind a key, select "KEY BINDING/Rebind key", and follow the  prompts  in
  2973. the title bar.
  2974.  
  2975. Index
  2976.  
  2977. [The index is only in the printed manual.  Sorry!  JL]
  2978.  
  2979. *****************************************************************************
  2980.  
  2981. Bug Fixes and Changes Since V3.05
  2982. ---------------------------------
  2983. V3.06 (April 1989): The "LABELS/Create multiple/Reloc32" function  is  called
  2984. automatically after every "Open load file", unless there was no reloc32 table
  2985. in  the file, and providing that this is not overridden by the new "OPTIONS2/
  2986. Auto labels/OFF" option.  It may be stopped by pressing rAmiga-A, anyway.
  2987.  
  2988. Attempts to set the data type to ASCII or CODE in a BSS or  unitialized  data
  2989. area  will now instead set the data type to BYTES.  Regardless of the setting
  2990. of the attributes bits, data in a BSS hunk or in  an  unitialized  data  area
  2991. will *always* show as "ds.b", "ds.w" or "ds.l".
  2992.  
  2993. Holding down the left mouse button during macro execution no longer temporar-
  2994. ily sets the execution speed to "Slow".  This  was  previously  causing  some
  2995. minor multitasking difficulties.
  2996.  
  2997. Previously, where code, words or longwords started very close to the end of a
  2998. section (this includes the end of the file), sometimes it would extend  right
  2999. across  the  section start, preventing the section statement from being disp-
  3000. layed.  Where this occurs, the data type at the first byte is now changed  to
  3001. bytes,  and  disassembly  is restarted from the same address.  This continues
  3002. until the section statement is no longer hidden.
  3003.  
  3004. When a data type other than code is set manually, previously this would some-
  3005. times cause reloc32 areas to be shown as bytes or words.  This will no longer
  3006. happen.
  3007.  
  3008. The second pass of "Fill-in data types" determines the line lengths.  Much of
  3009. this is now done on-the-fly, during normal disassembly.  This is most notice-
  3010. able when strings are displayed.
  3011.  
  3012. When a line is disassembled, if a  reloc32  starts  the  line,  it  will  now
  3013. *always*  show as a longword.  Previously, it sometimes showed as code, until
  3014. the first "Fill-in data types" was done.
  3015.  
  3016. If a line is displayed such that a reloc32 longword will overlap to the  next
  3017. line, the data type at the start of that line is changed to words, effective-
  3018. ly preventing the overlap.
  3019.  
  3020. It is now possible to abort from a "Save .asm", by using the normal abort key
  3021. sequence (rAmiga-A).  The file will still be created,  but  no  further  text
  3022. will be saved to it.
  3023.  
  3024. When the left mouse button is held down, as well as the ctl key, symbols  and
  3025. full-line  comments are now temporarily disabled.  This allows you to quickly
  3026. see the value of any symbols present in code.
  3027.  
  3028. When a user-defined label is created, the "internally produced"  bit  in  the
  3029. attributes table is now cleared.
  3030.  
  3031. While using the mouse to scroll, if the left Amiga key is held  down,  labels
  3032. are  created  using  forward  references.   Now,  if the left mouse button is
  3033. pressed while the pointer is within 3 pixels  of  the  right  screen  border,
  3034. ReSource  will assume that you are holding the left-Amiga key down, until you
  3035. let the left mouse button go.  This makes it easy to  create  labels  single-
  3036. handed.   You  don't  have  to keep the pointer on the right while scrolling,
  3037. only its position when you actually press the LMB is important.
  3038.  
  3039. The "DISPLAY/Block fill" function had some severe limitations, namely:
  3040.  
  3041.   1> Changing the data type for a byte or area with an  area  that  had  been
  3042.      block-filled, was extremely difficult, as it had to be done for each and
  3043.      every byte.
  3044.   2> After a block fill, ASCII was not displayed correctly.
  3045.   3> Scrolling backwards through an area that  had  been  block-filled  would
  3046.      give an inconsistent display.
  3047.   4> The wait pointer should have been displayed, especially for large fills.
  3048.  
  3049. These problems have been fixed.
  3050.  
  3051. It is now possible to abort from an "Open load file" operation.
  3052.  
  3053. If the workbench screen is using interlace, ReSources' screen will  now  also
  3054. use  interlace.  Previously, ReSource tried to open a screen of the same size
  3055. as the Workbench screen, but didn't pick up the fact that interlace  was  on.
  3056. Thanks to Brian Jackson and Darren M. Greenwald for reporting this bug.
  3057.  
  3058. The "SAVE/Save .asm" functions now give you a profile of the source  code  as
  3059. it  is  saved.   This  may be disabled by selecting the new "OPTIONS2/Verbose
  3060. saves/OFF" function.  Each entry in the displayed table is  counted  as  that
  3061. particular  condition  occurs  during  the save, and the totals are displayed
  3062. continuously.  It is now possible to get a printout of  this  and  any  other
  3063. screen in ReSource, using the new "SAVE/Save screen" function (see below).
  3064.  
  3065. There is a new function, "SAVE/Save screen".  It will prompt you for the name
  3066. of a file.  If the file can be opened, it will save the  currently  displayed
  3067. text  to  that file.  Use this to send a screen dump to the printer, or other
  3068. file.  Note that this can be used at the completion of a "save .asm", to  get
  3069. a printout of the source code profile.
  3070.  
  3071. When scrolling, the display used to "jump" when the top line on  the  display
  3072. had  any  full-line  comments, hidden labels, or a trailing blank line.  This
  3073. has been eliminated.
  3074.  
  3075. Tab characters in full-line comments are now supported and will be  displayed
  3076. as they should, on-screen, in a screen printout, and in any saved source code.
  3077.  
  3078. There is a new symbol base, "String control".  This is meant to be  used  for
  3079. ASCII control characters, such as DEL ($7F), BS (8), etc.
  3080.  
  3081. The "LABELS/Create multiple/Reloc32" function  now  checks  the  validity  of
  3082. reloc32 pointers before attempting label creation.
  3083.  
  3084. It is now possible to append to files when saving, rather than simply replac-
  3085. ing them.  To do this, the filename that you supply  must  start  with  "*>".
  3086. For example, if you wish to append information to the file "ram:MySavedFile",
  3087. when requested for a filename, you would type "*>ram:MySavedFile".   This  is
  3088. valid for *any* file save, including screen saves, binary image saves, etc.
  3089.  
  3090. On extreme rare occasions, when creating labels or  symbols,  ReSource  would
  3091. corrupt memory, the obvious symptoms being that most labels and symbols would
  3092. display  random  characters.   The  bug would only appear if a "Save .RS" was
  3093. performed immediately prior to more memory being  allocated  for  the  string
  3094. buffer.  Fixed.
  3095.  
  3096. When the result of a "STRINGS/Maths functions/Logical OR" was zero,  a  macro
  3097. fail should have resulted, but didn't.  Fixed.
  3098.  
  3099. If a label longer than 19 bytes was displayed as a "hidden" label,  a  system
  3100. crash was likely.  Fixed.
  3101.  
  3102. When creating "shop" ascii labels, if no valid text can be found  to  use  in
  3103. the label name, instead of creating a label starting with "lbA", ReSource now
  3104. creates the label "ascii.MSG", or "ascii.MSG0", or "ascii.MSG1", etc.
  3105.  
  3106. During the creation of a macro, if an attempt to create some other macro  was
  3107. initiated,  the  resulting  macro  often  caused  a system crash.  Now, if an
  3108. attempt is made to create a macro while already creating a macro, it will  be
  3109. ignored.
  3110.  
  3111. It was sometimes difficult to abort from an executing  macro,  especially  if
  3112. the macro execution speed was set to "wait on mouse".  Fixed.
  3113.  
  3114. Whenever functions within a macro are being executed, a very small  group  of
  3115. pixels within the title bar are constantly changed.  This is the only visible
  3116. feedback  that  you will see while executing a macro when the execution speed
  3117. is set to "Very fast".  This is also done during searches, etc.
  3118.  
  3119. When quitting, if any new macros have been defined, without being saved to  a
  3120. macro file, this fact will now be mentioned in the quit requester.
  3121.  
  3122. During the creation of a macro,  the  responses  within  requesters  are  now
  3123. "STORE"  and  "USE"  instead of "OKAY" and "CANCEL" as a better indication of
  3124. how ReSource responds to text input during a macro creation.
  3125.  
  3126. References to the  START+$FFFFFFFC  and  START+$FFFFFFF8  are  now  shown  as
  3127. "ProgStart-4"  and  "ProgStart-8"  respectively.  If the label "ProgStart" is
  3128. not defined anywhere, it will be displayed as a label attached to  the  first
  3129. byte  of  the  current file.  You can still have some other label attached to
  3130. the start of the file.
  3131.  
  3132. When using "xx(A4)" type Effective Address conversions, the  label  "DT"  has
  3133. always  been  assumed  to be defined.  Now, if it is not defined by the user,
  3134. ReSource will define it for you.  It will be attached to the last  data  hunk
  3135. in the file, or if no data hunks exists, the last CODE hunk.
  3136.  
  3137. Using the "SAVE/Save binary image/" functions would sometimes save less  than
  3138. what  it  should  have saved.  This would happen if there was at least 4 null
  3139. bytes at the end of the current file.  Fixed.
  3140.  
  3141. The double-quote character ($22) was not being recognized as  a  valid  ASCII
  3142. character.  These will now be displayed in ASCII strings, just like any other
  3143. valid ASCII characters.
  3144.  
  3145. The "SPECIAL FUNCTIONS/Convert xx(A4)  EA's/This  operand"  previously  would
  3146. only work for lines following the pattern "LEA START+$xxxxxx,A4".  Now, lines
  3147. such as "MOVE.L #START+$xxxxxx,A4" will also work.
  3148.  
  3149. There is a new option; "OPTIONS 2/Assembler/CaPatch".  Source  code  produced
  3150. for  this  assembler  uses  the  "DX"  directive, to support unitialized data
  3151. areas.  This is the extra space at the  end  of  data  or  code  hunks,  that
  3152. appears  to be BSS, but is actually attached to the data or code hunk.  Other
  3153. assemblers would use the "DS" directive instead, which  makes  the  resulting
  3154. program much larger than the original.  This was previously only available to
  3155. "C" programmers.
  3156.  
  3157. There is a new hilite option; "Unitialized data".  When selected, any uninit-
  3158. ialized data areas will be hilited.
  3159.  
  3160. When the selected assembler type  is  "Cape"  or  "CaPatch",  the  directives
  3161. "bnryonly", "exeobj" and "objfile" are used where appropriate.
  3162.  
  3163. When supplying a string that will become a label, symbol, or comment, you may
  3164. now use indirection to include in that  string,  some  other  already-defined
  3165. label, symbol, or comment.  Indirection must start with an "escape" character
  3166. (decimal  value  27,  just  hit  the "escape" key), and must be followed by a
  3167. decimal digit between zero and three inclusive.   This  is  how  you  specify
  3168. which type of string that you require:
  3169.  
  3170.   0 = Label
  3171.   1 = Symbol
  3172.   2 = Full-line comment (the first one only)
  3173.   3 = End-of-line comment
  3174.  
  3175. This should be immediately followed by a  hex,  decimal,  or  binary  number,
  3176. specifying  the  offset  in  the  current  file  where the required string is
  3177. attached to.  Another escape character is required immediately following  the
  3178. number,  as  a  delimiter.   You are then free to either supply more "normal"
  3179. text, or you may  use  indirection  several  times  within  a  single  string
  3180. specification.
  3181.  
  3182. Because the escape character  is  not  normally  displayable,  the  following
  3183. example  will  use a "^" character where the escape character is really meant
  3184. to be:
  3185.  
  3186.      lbW000140   dc.w    6
  3187.                  dc.w    8
  3188.                  dc.w    12
  3189.  
  3190.      lbC000146:  RTS
  3191.  
  3192.      lbC000148:  MOVEQ   #0,D0
  3193.                  RTS
  3194.  
  3195.      lbC00014C:  MOVEQ   #1,D0
  3196.                  RTS
  3197.  
  3198. In the above program, the word values at label "lbW000140" correspond to the
  3199. distance between "lbC000146" and "lbW000140" on the first line (6), the
  3200. distance between "lbC000148" and "lbW000140" on the second line (8), and the
  3201. distance between "lbC00014C" and "lbW000140" on the third line (12).  This is
  3202. what is commonly referred to as a "jump table".  In order to make the program
  3203. assemble properly, the values 6, 8, and 12 should be changed to symbols
  3204. specifying their true meaning, rather than just the value that they happen to
  3205. be when the program was last assembled/compiled:
  3206.  
  3207.      lbW000140   dc.w    lbC000146-lbW000140
  3208.                  dc.w    lbC000148-lbW000140
  3209.                  dc.w    lbC00014C-lbW000140
  3210.  
  3211.      lbC000146:  RTS
  3212.  
  3213.      lbC000148:  MOVEQ   #0,D0
  3214.                  RTS
  3215.  
  3216.      lbC00014C:  MOVEQ   #1,D0
  3217.                  RTS
  3218.  
  3219. It has been possible to use the  "SPECIAL  FUNCTIONS/Convert  specific  EA's"
  3220. functions  to  make  the  creation of these symbols easy.  However, there has
  3221. always been  a  problem;  if  you  later  change  the  label  "lbC000148"  to
  3222. "ClearValue", or any other label, the symbol "lbC000148-lbW000140" will cause
  3223. an  assembly  error.  Now, by using dynamic indirection, whenever the symbols
  3224. at label "lbW000140" are displayed, it will use whatever labels are in use at
  3225. that moment.  For example, for the line:
  3226.  
  3227.      lbW000140   dc.w    lbC000146-lbW000140
  3228.  
  3229. instead of creating  the  symbol  "lbC000146-lbW000140",  you  would  instead
  3230. specify "^0$146^-^0$140^" when requested by the "LABELS/Create single/Symbol"
  3231. function  (remember  that  the "^" is actually an escape character, press the
  3232. escape key).
  3233.  
  3234. This dynamic indirection is now also used internally in  ReSource,  where  it
  3235. seems  required.  For example, the "SPECIAL FUNCTIONS/Convert specific EA's/"
  3236. functions now use dynamic indirection when creating symbols.
  3237.  
  3238. Functions that access labels, symbols, and  comments  will  normally  support
  3239. dynamic indirection in strings, unless the option "OPTIONS 1/Symbols/" is set
  3240. to  "OFF".   In  this case, the raw string will be used.  Dynamic indirection
  3241. was meant to be used in symbols.   It  is  possible  to  use  in  labels  and
  3242. comments, however some problems may arise if care is not taken.  For example,
  3243. duplicate  labels can easily be created if dynamic indirection is used in the
  3244. specification for a label.  It should be quite safe in any comments, however.
  3245. Symbols containing dynamic indirection will not be stored in  the  EQUate  or
  3246. Xref tables.  It is expected that most strings using indirection are symbols,
  3247. that refer to labels, and therefore do not require to be EQUated or XREF'd.
  3248.  
  3249. In revision 5, a macro fail resulted if an attempt was  made  to  display  an
  3250. operand  as  ASCII,  if  an  invalid  ascii  character was encountered.  This
  3251. created a problem when macro execution speed  was  set  to  "Very  fast",  as
  3252. displaying  was  disabled  at  the  time the ASCII attribute was set, and the
  3253. macro fail did not result until some later time, perhaps  when  running  some
  3254. other macro.  When invalid ascii characters are encountered in an operand, it
  3255. will still show as hex, but a macro fail will no longer result from this.
  3256.  
  3257. When the user defines or redefines the data type, the "Uncertain  data  type"
  3258. attribute  bit  is now cleared.  This bit is now also cleared when a label is
  3259. removed.
  3260.  
  3261. When using "SAVE/Save .asm/Partial"  or  "SAVE/Calc  .asm  size/Partial",  no
  3262. EQUate or Xref table will be created.
  3263.  
  3264. When a file with overlays is loaded, only the root node is loaded.  When this
  3265. happens, the user is now notified of this, and  must  select  "okay"  on  the
  3266. requester before ReSource will continue.
  3267.  
  3268. If data type "word", "longword" or "code" is selected at an  odd  address,  a
  3269. display beep is now generated.
  3270.  
  3271. During the functions "SAVE/Calculate .asm size/" and "SAVE/Save  .asm/",  for
  3272. any  lines  which  create code or data which will not assemble correctly (odd
  3273. address, "START+" references, invalid code "????"), an address will be pushed
  3274. onto the cursor stack, representing the start of each of these lines.   Thus,
  3275. after  using  one of these functions, use "CURSOR/Absolute/Previous location"
  3276. to go directly to each of these erroneous lines.  This is an excellent way to
  3277. quickly ensure that the source code that you create will assemble properly.
  3278.  
  3279. ReSource now remembers the presence of any  "AFLINE"  macros,  after  saving/
  3280. reloading a ".RS" file.
  3281.  
  3282. The "CURSOR/Absolute/Forward reference" and  "CURSOR/Absolute/Second  forward
  3283. reference" functions normally allow you to reference a label only.  It is now
  3284. possible  to  forward-reference on a symbol, even if the symbol is actually a
  3285. combination of two or more labels, and even if it was created  using  dynamic
  3286. indirection.
  3287.  
  3288. If the user creates a symbol which is currently also defined as  a  label,  a
  3289. display beep will be generated.
  3290.  
  3291. When creating labels from forward references,  if  ReSource  detects  that  a
  3292. reference  to  an  odd  address  is  coming from code, a display beep will be
  3293. generated, and also a  macro  fail  will  result.   If  using  "LABELS/Create
  3294. multiple/All", the scan will stop.
  3295.  
  3296. When supplying a parameter for the "SPECIAL FUNCTIONS/Zap" function,  if  the
  3297. string  you  supply starts with ".l", ".w" or ".b", the number following will
  3298. be treated as a longword, word, or byte, respectively.   In  this  case,  the
  3299. accumulator  operand  size does not matter.  The case of the letter "l", "w",
  3300. or "b" may be upper or lower.
  3301.  
  3302. Several values in the "CIA Resource" symbol base were incorrect.  Fixed.
  3303.  
  3304. The "LABELS/Create multiple/All" function now uses a different algorithym  to
  3305. detect when it should stop creating labels.  The chance of it mistaking ascii
  3306. for code is now much decreased.
  3307.  
  3308. The function "LOCAL MACROS/Save local macros" has always  saved  all  macros,
  3309. and  not  just  the  local  ones.  It has been renamed "LOCAL MACROS/Save all
  3310. macros".
  3311.  
  3312. While a macro is  executing,  if  the  "CANCEL"  gadget  is  selected  for  a
  3313. requester, the macro will now abort.
  3314.  
  3315. To use the "Block fill" function, the start and end  addresses  must  now  be
  3316. specified  by  selecting  "DISPLAY/Block  fill/Set  start" and "DISPLAY/Block
  3317. fill/Set end" at the appropriate locations in the file.  The block-fill start
  3318. and end addresses will default to the actual start and end of the file.
  3319.  
  3320. The start and end for partial saves now default to the start and end  of  the
  3321. current  file.   There  is two new functions, "SAVE/Partial save/Reset start"
  3322. and "SAVE/Partial save/Reset end".  Selecting these will reselect the default
  3323. values.
  3324.  
  3325. The "DISPLAY/Fill-in data types" and "DISPLAY/Fill-in D/T Fwd" functions used
  3326. to perform many functions, one of which was to try to guess data type changes
  3327. where it seemed appropriate.   Because  other  functions  have  been  greatly
  3328. improved,  this  became  less  necessary, and even sometimes annoying when it
  3329. made the wrong choice.  The Fill-in data type  functions  have  been  greatly
  3330. simplified,  and  will no longer make any data type changes themselves.  As a
  3331. result of this, they take around half as much time as they used  to.   It  is
  3332. still a good idea to use "DISPLAY/Fill-in data types" before saving to either
  3333. a  ".asm"  or ".RS" file, however these are the only occasions when it should
  3334. be required.
  3335.  
  3336. A number of "SYMBOL" functions were giving bad symbols  when  the  value  for
  3337. which a symbol was required, was greater than $FFFFFF.  Fixed.
  3338.  
  3339. The "OPTIONS 2/Ascii longs/"  options  have  been  removed  from  the  menus.
  3340. Because  any  number  can  now  be shown as ascii individually (if within the
  3341. valid ascii range) these functions became obsolete.  If you press a key which
  3342. is bound to these functions, it will give the same result as if the  key  was
  3343. not bound to anything.
  3344.  
  3345. The functions "STRINGS/Output buffer/Append accumulator"  had  problems  when
  3346. more than 4K or information was put into it.  Fixed.
  3347.  
  3348. If ReSource's window is selected (activated) when the intuition pointer is on
  3349. the far left of the screen, a screen update  will  now  *not*  be  performed.
  3350. This  may be necessary after saving to a ".asm" file, when the source profile
  3351. information is to be saved to a file.
  3352.  
  3353. When  using   the  functions  "CURSOR/Absolute/Label"  and  "CURSOR/Absolute/
  3354. Symbol",  if required label/symbol was at the start of the file, the function
  3355. used to fail.  Fixed.
  3356.  
  3357. =eof=
  3358.