home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / tools / patches / patchsetfunc / patchsetfunc.doc < prev    next >
Encoding:
Text File  |  1996-03-29  |  6.0 KB  |  175 lines
  1. Documentation of PatchSetFunc V1.22
  2.  
  3.  
  4. 1. MOTIVATION
  5. -------------
  6.  
  7. This one was written as a support program, for my patch.library.  It patches the
  8. exec.library/SetFunction() to use patch.library instead of the normal
  9. OS-function.
  10.  
  11. Although I'm aware that there exist a couple of programs, which perform the same
  12. task quite well (e.g.:  SetManager by Nicola Salmoria, SaferPatches by Martin
  13. Adrian), I thought it would be nice, if more programs could use my
  14. patch.library.
  15.  
  16.  
  17.  
  18. 2. WHAT IT DOES
  19. ---------------
  20.  
  21. If you're not expert with the Amiga operating system, all you need to know about
  22. PatchSetFunc is that it will, under certain circumstances, avoid GURUs.
  23.  
  24. If you're an expert, here come the details.  There's a function in exec.library,
  25. whose name is SetFunction().  You know that Amiga libraries contain a 'jump
  26. table', where the address of every function in the library is stored.  Library
  27. functions are always executed via the jump table, and NEVER through absolute
  28. addressing.  SetFunction() allows the user to modify the jump table, in order to
  29. insert a custom routine in place of the standard one.  For example, one could
  30. modify the DisplayBeep() vector to play a sound instead of flashing the screen.
  31.  
  32. SetFunction() is a very useful feature of the Amiga operating system, but it has
  33. the major drawback that there's no system supervising of concurrent use of the
  34. same vector by different tasks.  Under certain circumstances, that can be
  35. deadly.  Before removing its custom vector, a program should check that it was
  36. not modified again.  However, very few do that, and so if you do not terminate
  37. such program in REVERSE order of when you executed them, you'll probably get a
  38. system crash.
  39.  
  40. Another fault of Kickstart 1.x is that the dos.library vectors cannot be
  41. modified by SetFunction(), because they do not follow the conventions
  42. established by Commodore itself.
  43.  
  44. All this could be fixed if all programmers would use the patch.library.
  45.  
  46. Unfortunately patch.library is quite new and many programs still use
  47. SetFunction().
  48.  
  49. So I wrote PatchSetFunc, which allows any program to take profit from
  50. patch.library.
  51.  
  52.  
  53.  
  54. 3. SYSTEM REQUIREMENTS
  55. ----------------------
  56.  
  57. - Any Amiga with any Kickstart version
  58. - patch.library v4+ must be installed in libs:
  59.  
  60.  
  61.  
  62. 4. INSTALLATION
  63. ---------------
  64.  
  65. The program 'PatchSetFunc' should be executed as the first command 
  66. in the startup-sequence after the SetPatch command.
  67. You must specify the full path, if you place the command in a directory
  68. other than c:.
  69. You may also want to redirect the output to nil:.
  70.  
  71. The patch.library should be copied to LIBS:.
  72.  
  73.  
  74.  
  75. 5. NOTES & WARNINGS & KNOWN BUGS
  76. --------------------------------
  77.  
  78. - Programs directly reading addresses from the jump-table, may fail to quit!
  79.   (This behavior is illegal and not supported by Commodore!)
  80. - In order to make patch.library to work with XOper a kludge has been
  81.   added, which stops PatchSetFunc the exec.library/Switch() function
  82.   (which in fact does the actual multitasking in the Amiga) of being patched
  83. - Some programs patch the Expunge() function of a library, to ensure that the
  84.   library won't get expunged, while a patch is active.
  85.   If the support program PatchSupervisor is active PatchSetFunc ignores
  86.   patches to the Expunge() function.
  87. - Programmers should use patch.library directly to ensure maximum safety, when
  88.   patching library functions
  89. - A developer package with full documentation and includes is available on
  90.   Aminet (util/libs/PatchLibV4.lha)
  91. - This software will show its full capabilities once the preferences editor
  92.   for the patch.library is available in the near future.
  93.   Programs can be excluded from using PatchSetFunc....
  94.  
  95.  
  96.  
  97. 6. COMPATIBILITY
  98. ----------------
  99.  
  100. In general PatchSetFunc should work together with all programs, that know about
  101. SetManager, because for these programs it will look like SetManager was active.
  102. (The public messageport 'SetMan' can be found via FindPort())
  103.  
  104. Other programs should be configured (if possible), not to check, if a patch was
  105. installed after its patch.
  106.  
  107. Program:    Change when using PatchSetFunc:
  108. XOper V2.x    turn SmartPatch OFF
  109.  
  110.  
  111.  
  112. 7. HISTORY
  113. ----------
  114.  
  115. V1.22    FIX: No longer patches the exec.library private functions Schedule() and
  116.     ExitIntr(). This caused ShapeShifter to crash on exit.
  117. V1.21    ENHANCEMENT: Now supports project management of patch.library V4
  118. V1.10    ENHANCEMENT: Now uses less stack
  119. V1.06    FIX:    The public message port was spelled 'Setman' instead of 'SetMan'
  120. V1.02    RELEASE:First public release
  121.  
  122.  
  123.  
  124. 8. LICENSE
  125. ----------
  126.  
  127. This material is © Copyright 1993-96 by Stefan Fuchs. All rights reserved.
  128.  
  129. It may be distributed freely as long as the following restrictions are met:
  130.  
  131. - The distributor may charge a fee to recover distribution costs.
  132.   The fee for diskette distribution should not be more than
  133.   the cost to obtain the same diskette from Fred Fish.
  134.  
  135. - The distributor agrees to cease distributing the programs and
  136.   data involved if requested to do so by the author.
  137.  
  138. - You may copy and distribute verbatim copies of the program's
  139.   executable code and documentation as you receive it, in any
  140.   medium, provided that you conspicuously and appropriately
  141.   publish only the original, unmodified program, with all
  142.   copyright notices and disclaimers of warranty intact and
  143.   including all the accompanying documentation, example files and
  144.   anything else that came with the original.
  145.  
  146. - If you are interested in including any of this material in a commercial
  147.   product, you should contact the author for his permission.
  148.  
  149. - The author will not be liable for any damage arising from the
  150.   failure of the programs or the library to perform as described,
  151.   or any destruction of other programs using the library residing
  152.   on a system. While I know of no damaging errors, the user of this
  153.   package uses it at his or her own risk.
  154.  
  155.  
  156. This package may be distributed in PD-series (e.g.: the Fred Fish library) or
  157. on the Aminet.
  158.  
  159.  
  160.  
  161. 9. CONTACT
  162. ----------
  163.  
  164.     To contact the author for bugreports, hints, ideas, donations, ....
  165.     write to:
  166.  
  167.  
  168.     Stefan Fuchs            E-Mail: snfuchs@sokrates.franken.de
  169.     Oskar-von-Miller-Str. 49    Fido:   Stefan Fuchs@2:2490/1901
  170.  
  171.     D - 90478 Nuernberg
  172.     GERMANY
  173.  
  174.  
  175.