home *** CD-ROM | disk | FTP | other *** search
/ Frostbyte's 1980s DOS Shareware Collection / floppyshareware.zip / floppyshareware / BOUT / SMARTUTL.ZIP / TSR.ZIP / TSR.DOC < prev    next >
Text File  |  1987-03-05  |  19KB  |  430 lines
  1. ****************************************************************
  2. *                       Version 2.2                            *
  3. *    The TSR package includes programs useful in managing      *
  4. *   DOS memory, and in particular managing memory-resident     *
  5. *  utilities. TSR stands for "Terminate and Stay Resident".    *
  6. *                                                              *
  7. ****************************************************************
  8.  
  9. A. MARK, FMARK and RELEASE
  10. ================================================================
  11.  
  12. MARK.COM and RELEASE.COM are used to remove memory-resident
  13. programs from memory, without requiring a system reboot, and
  14. without the usual problems of creating holes or leaving
  15. interrupts dangling. The two programs are used simply as follows:
  16.  
  17. 1) Run the program MARK.COM before installing any memory-
  18.    resident program that you may wish to deinstall later.
  19.    This marks the current position in memory and stores the
  20.    DOS interrupt vector table (all interrupts from 0 to FFH).
  21.  
  22. 2) Install whatever TSRs that you want to use, in the normal
  23.    way that you install them.
  24.  
  25. 3) When you want to deinstall all TSRs above the last MARK,
  26.    run the program RELEASE.COM. This will release all of the
  27.    memory above (and including) the last MARK, and restore
  28.    all interrupt vectors taken over by the memory resident
  29.    programs.
  30.  
  31. MARK and RELEASE can be "stacked" as many times as desired.
  32. RELEASE releases the memory above the last MARK call. MARK uses
  33. about 1600 bytes of memory each time it is called. This 1600
  34. byte region is also released when a RELEASE is done. MARK memory
  35. usage is dominated by the copies of the DOS interrupt vector
  36. table (interrupts 0..FFh) and the copy of the EMS page map
  37. (blocks 0..31 only) which MARK keeps when it goes resident.
  38.  
  39. ================================================================
  40.  
  41. MARK and RELEASE can optionally be called with a single command
  42. line parameter:
  43.  
  44.   MARK MarkName
  45.   RELEASE MarkName
  46.  
  47. In this way a particular mark is given a name. Calling RELEASE
  48. with the same name will release all memory above and including
  49. the mark of that name, also releasing any intermediate marks in
  50. the process. If no mark of the proper name is found, RELEASE
  51. will halt with a warning. A RELEASE call with no MarkName
  52. specified will release the last MARK, whether or not that MARK
  53. was named.
  54.  
  55. The MarkName can be any text string up to 126 characters in
  56. length. It may not contain embedded blanks or tabs. Case (upper
  57. or lower) is not important when matching MarkNames.
  58.  
  59. MarkName supports an additional feature. If the MarkName begins
  60. with ! (exclamation point), then the mark is called a "protected
  61. mark". That mark can be released *only* by an exact match to its
  62. name (including the exclamation point). A protected mark will
  63. NOT be released with an "unnamed" RELEASE. Any named or unnamed
  64. RELEASE will stop without releasing any memory if it encounters
  65. a protected mark that it does not match exactly.
  66.  
  67. ================================================================
  68.  
  69. As of version 1.4, MARK and RELEASE also control Expanded memory
  70. (Lotus/Intel/Microsoft EMS). They have been tested with READY!
  71. and with the TurboPower Software expanded memory disk cache, as
  72. well as with the device drivers used by the STB Expanded Memory
  73. Card.
  74.  
  75. WARNING: if a resident application allocates expanded memory at
  76. some time *after* going resident and after the last MARK made,
  77. that expanded memory will be released by a call to RELEASE. The
  78. current expanded memory manager (EMM) does not give us enough
  79. information to avoid this possibility. Fortunately, there are no
  80. known memory resident programs which perform this dynamic
  81. allocation of expanded memory. We hope that the EMM will be
  82. upgraded before such applications are designed.
  83.  
  84. ================================================================
  85.  
  86. As of version 1.6, RELEASE takes special precautions to allow it
  87. to release extra invocations of the DOS command processor. In
  88. the simplest form, an extra command processor is obtained by
  89. typing COMMAND at the DOS level. Many multitasking or switching
  90. utilities also utilize this feature of DOS, and these utilities
  91. can now be managed via MARK and RELEASE.
  92.  
  93. ================================================================
  94.  
  95. Due to the way DOS handles batch files, there are certain
  96. limitations on using RELEASE within batch. It is *not* possible
  97. to perform the following sequence of events successfully:
  98.  
  99. First, from the command line:
  100.  
  101.   MARK
  102.   SK      {SideKick, or any other resident program or programs}
  103.  
  104. Then, within a batch file:
  105.  
  106.   RELEASE {get rid of SK and MARK}
  107.   LOTUS   {run Lotus using the additional memory}
  108.   MARK    {put SK back in place}
  109.   SK
  110.  
  111. DOS allocates a small memory block prior to running any batch
  112. file. It does not allow that block to be deallocated from within
  113. the batch file without various errors occurring. As a result, in
  114. this case the MARK and SK memory blocks are effectively trapped
  115. until the batch file is completed, after which the memory will
  116. be reusable. Indeed, if you run the batch file presented above,
  117. you will get MARK and SK installed above a big hole in memory
  118. left by the previous images of MARK and SK.
  119.  
  120. As of version 1.9, RELEASE guards against this possibility. If
  121. it senses that you are attempting to release memory trapped by a
  122. "batch control block", it writes a warning message to that
  123. effect. It still releases the memory, but when it exits it
  124. passes back a return code of 1 rather than the usual value of 0.
  125.  
  126. It *is* possible to get the desired effect in either of at least
  127. two ways. First, you could make two batch files and call them
  128. one after the other:
  129.  
  130. Batch file #1:
  131.   RELEASE
  132.  
  133. Batch file #2:
  134.   LOTUS
  135.   MARK
  136.   SK
  137.  
  138. In this case, running RELEASE in batch file #1 has the same
  139. effect as running RELEASE from the command line. However,
  140. directly calling the second batch file from the first doesn't
  141. always seem to work either. The only sure bet appears to be the
  142. use of a keypoker like STACKEY, KEY-FAKE or PCED's KEYIN,
  143. modifying Batch #1 as follows:
  144.  
  145.   RELEASE
  146.   KEY-FAKE "batch2" 13
  147.  
  148. A better way to make these things happen is to use the public
  149. domain program CED, or its commercial upgrade PCED. These
  150. programs allow you to define "synonyms" for groups of commands.
  151. The commands execute one after the other just like a batch file.
  152. However, the synonyms do not create an extra batch control
  153. memory block which causes the problems just described.
  154.  
  155. Thus you could make two CED synonyms as follows. (We assume that
  156. the CED "chain character" is ^).
  157.  
  158. SYN LOADSK mark !sk^sk
  159.   {create a protected sidekick marker and load sidekick}
  160.  
  161. SYN RUNLOT release !sk^lotus^mark !sk^sk
  162.   {release sidekick if it's there, run lotus, then reload sidekick}
  163.  
  164. ================================================================
  165.  
  166. As of version 2.0, a new form of marking, called a "file
  167. mark", is also supported. The new mark has the advantage that it
  168. uses only about 150 bytes of memory rather than the 1600 of MARK.
  169.  
  170. The new mark is placed with the command
  171.  
  172.     FMARK [d:][directory]filename
  173.  
  174. The bulk of the vector table and EMS page map are stored in the
  175. file which you specify on the command line rather than in
  176. memory. Note that a command line parameter is *required* in this
  177. case. Otherwise FMARK will halt with an error. The file created
  178. by FMARK will be between 1000 and 2000 bytes in size, depending
  179. on usage of expanded memory.
  180.  
  181. If you will switch drives or directories after using FMARK, you
  182. should specify a complete pathname when FMARK is initially
  183. called. To avoid confusion, you may want to keep the FMARK files
  184. in the root directory, or in a separate directory defined just
  185. for this purpose.
  186.  
  187. The RELEASE program has been upgraded so that it can release
  188. either an in-memory mark (placed by MARK.COM) or a file mark
  189. (placed by FMARK.COM). Use of RELEASE with in-memory marks is
  190. the same as before. To use RELEASE with file marks, call it with
  191. the name of the mark file on the command line:
  192.  
  193.     RELEASE [d:][directory]filename
  194.  
  195. Note that in this case the filename must be specified on the
  196. command line, and that only a file mark exactly matching the
  197. command line will be released. If the specified mark file is not
  198. found, RELEASE will halt with an error message. When the memory
  199. is released, the mark file is also deleted from disk.
  200.  
  201. There is no direct equivalent of protected marks for FMARK. If
  202. an unnamed RELEASE finds an in-memory mark below a file mark,
  203. the file mark will be released in the process of the unnamed
  204. release. In this case, the mark file will not be deleted from
  205. disk.
  206.  
  207. ================================================================
  208.  
  209. Version 2.1 of RELEASE fixes a stupid bug in 2.0. This bug lead
  210. to reports of RELEASE printing its status message on the
  211. printer, and to some system crashes. The bug was caused by
  212. writing over the first two bytes of the DOS file handle table at
  213. offset 0018H in the PSP.
  214.  
  215. ================================================================
  216.  
  217. Version 2.2 of RELEASE adds a few new features. These features
  218. are activated by command line switches. The valid switches are
  219. as follows:
  220.  
  221.   /K    release memory above the specified MARK, but Keep the
  222.         MARK itself in memory. This switch is useful if you plan
  223.         to reinstall the released TSRs later.
  224.  
  225.   /R    Revector the 8259 interrupt controller(s) to powerup
  226.         state. This option is useful for TSRs that patch in to
  227.         the system at a very low level. Examples include network
  228.         operating system shells, multitaskers, etc. Use this
  229.         option with caution; that is, test it at some point when
  230.         no useful work has been loaded into memory.
  231.  
  232.   /?    Show a brief help screen and halt.
  233.  
  234. Any of these options are acceptable when preceded by a '-', for
  235. example, -K instead of /K.
  236.  
  237. The /R option now allows the release of DesqView, Windows, and
  238. TaskView from memory. We hope that it will allow the release of
  239. network shells, but have not been able to test it. DoubleDOS
  240. unfortunately cannot be released even with the /R option. (It
  241. apparently patches DOS itself when it is installed.)
  242.  
  243. Version 2.2 of RELEASE also restores a few additional memory
  244. locations from the MARK. It restores 8 bytes at 40:A8
  245. (associated with the EGA) and 16 bytes at 40:F0 (the
  246. interapplications communications area).
  247.  
  248.  
  249. B. MAPMEM and WATCH
  250. ================================================================
  251.  
  252. MAPMEM.COM is used to display the current DOS memory map. It shows
  253. the resident programs, how much memory they use, and what interrupt
  254. vectors each currently controls. MAPMEM also shows information
  255. about expanded memory when such a driver is installed. MAPMEM
  256. writes to the standard output -- thus the output can be printed
  257. or stored to a file by using DOS redirection.
  258.  
  259. MAPMEM shows MARKs and FMARKs so that you can look at them prior
  260. to a RELEASE. A MARK will show the owner name "MARK", and the
  261. mark name (if any) in the command line area. An FMARK will show
  262. "N/A" in the owner column (due to the minimal memory kept by an
  263. FMARK), and the name of the mark file in the command line area.
  264.  
  265. WATCH.COM is a resident program that watches other memory
  266. resident programs become resident. As a TSR goes resident,
  267. WATCH updates a small file that contains information about what
  268. interrupt vectors were taken over. This information can later be
  269. used by MAPMEM to show more details about interrupts than
  270. normally available. Installation of WATCH.COM is optional. All
  271. of the other TSR Utilities can be used whether or not WATCH is
  272. installed.
  273.  
  274. If you want to use it, WATCH.COM should be installed as the
  275. first TSR in your AUTOEXEC.BAT file. WATCH creates two files:
  276. \TSR.INI and \TSR.DAT (in the root directory of the default
  277. drive at boot time). TSR.INI contains a list of the interrupt
  278. vectors at the time WATCH was installed. TSR.INI is not
  279. currently used after it is created - it is a hook for future
  280. capabilities that may become part of the TSR Utilities. TSR.DAT
  281. is updated after each memory resident program is installed in
  282. your system. For each resident program, it contains a line
  283. similar to the following:
  284.  
  285.   0E40 14|0E40:005C 17|0E40:009C
  286.  
  287. All numbers are reported in hexadecimal. The first number is the
  288. segment at which the program became resident. Each group of
  289. characters following the segment shows an interrupt vector that
  290. was changed by the resident program. The first byte is the
  291. interrupt number and following the '|' is the segment:offset of
  292. the new value of the interrupt vector. Thus, by scanning TSR.INI
  293. and TSR.DAT, the status of the interrupt vector table can be
  294. recreated at any point in the TSR installation sequence.
  295.  
  296. At this time, TSR.DAT is used only to aid MAPMEM in one of its
  297. report modes.
  298.  
  299. As of version 2.2, MAPMEM supports the following command line
  300. options:
  301.  
  302.      /W [Watchfile]
  303.             Used in combination with WATCH.COM, this option
  304.             causes MAPMEM to show the vectors taken over when
  305.             each program went resident, not just those still
  306.             controlled when MAPMEM is run. If Watchfile is not
  307.             specified, the file \TSR.DAT is used.
  308.      /V     Verbose report.
  309.      /?     Write a brief help screen.
  310.  
  311. MAPMEM accepts either "/" or "-" to delimit the command line
  312. options.
  313.  
  314. On the Verbose report, the "Files" column shows the number of
  315. file handles that each resident block has kept open. Each block
  316. of memory reported by DOS is listed individually in verbose
  317. mode. This is useful in debugging problems, either with the TSR
  318. package itself, or perhaps with the resident programs that you
  319. are using.
  320.  
  321. By default, each "hooked vector" that MAPMEM reports shows only
  322. the current owner of the vector. Any previous owners now chained
  323. onto the list are not shown. Because of the technique used,
  324. MAPMEM may report some garbage hooked vectors (generally high
  325. numbered ones). When the /W option of MAPMEM is used, however,
  326. MAPMEM reads the TSR.DAT file and shows the vectors for which
  327. any TSR gains control as part of the chain. No garbage vectors
  328. should appear when the /W option is used. The optional filename
  329. for the /W option allows you to specify the TSR.DAT file on
  330. another drive.
  331.  
  332. The MAPMEM /W option may not work correctly if TSRs are released
  333. and reinstalled. Extra interrupt vectors will be reported in
  334. some cases. Solving this problem would greatly complicate
  335. WATCH.COM.
  336.  
  337. WATCH.COM may not work correctly on floppy-based systems where
  338. the disk in drive A: is changed during operation. WATCH creates
  339. \TSR.DAT when it is installed. When other programs go resident,
  340. WATCH assumes that \TSR.DAT already exists. If the file is not
  341. found, WATCH will not create it or update it, and MAPMEM /W
  342. reports will be incomplete.
  343.  
  344. Everything we know about DOS memory allocation is embodied in
  345. the source code for MAPMEM and RELEASE. We found this out by
  346. piecing together tips from friends and through many hours of
  347. snooping. Please don't call for an explanation.
  348.  
  349.  
  350. C. RAMFREE and EATMEM
  351. ================================================================
  352.  
  353. RAMFREE.COM supplies a quick way to determine the amount of free
  354. RAM (without going through CHKDSK). RAMFREE also reports the
  355. segment at which the free memory block begins.
  356.  
  357. EATMEM.COM is useful for program development work when you want
  358. to test software in an environment with a desired amount of
  359. available memory. Note that the memory used by EATMEM can be
  360. freed by using MARK and RELEASE. EATMEM is called with a single
  361. command line parameter, specifying the (decimal) number of
  362. KILOBYTES to eat up:
  363.  
  364.   EATMEM KiloBytesToEat
  365.  
  366. Note that EATMEM will happily allow you to eat up all system
  367. memory, leading to a crash when COMMAND.COM cannot be reloaded.
  368. Be sure to calculate how much memory to eat before calling
  369. EATMEM.
  370.  
  371.  
  372. D. The Story Behind the TSR Utilities
  373. ================================================================
  374.  
  375. These programs should work on any system running PCDOS or
  376. MSDOS 2.0 or later. They were developed on a Compaq Deskpro 286
  377. running Compaq DOS 3.0 and have subsequently been tested on a
  378. number of different systems. Complete source code is available
  379. in the file TSRSRC.ARC. MARK, FMARK, WATCH, RAMFREE and EATMEM
  380. are written in assembly language (CHASM), while MAPMEM and
  381. RELEASE are written in Turbo Pascal. TSRSRC requires that you
  382. have Turbo Pascal version 3. On CompuServe, TSRSRC is found in
  383. the Borland SIG (Go BOR-100) in data library 4 (DL4).
  384.  
  385. The programs have been released to the public domain for personal,
  386. non-commercial use only. You may use them yourself, give them to
  387. your friends or co-workers, or distribute them for a cost-based
  388. fee as part of a user's group or bulletin board service. If you
  389. wish to distribute these programs as part of a commercial package,
  390. please contact us for a license agreement.
  391.  
  392. These programs were originally developed as an exercise in
  393. understanding DOS memory management. They have been put in the
  394. public domain as a public service. We ask for no donation for
  395. this set of programs. If for some reason you want the latest
  396. version or need support, we will ask for $5 to cover the costs
  397. of shipping a new disk to you.
  398.  
  399. TurboPower Software is in the business of Turbo Pascal
  400. programming tools for serious developers. Our first product, the
  401. TurboPower Utilities, contains 9 programs including an
  402. intelligent cross-reference, a pretty printer, an execution
  403. profiler and several DOS file and text management tools. Our
  404. second product, Turbo EXTENDER, lets Turbo Pascal programs grow
  405. beyond 64K bytes in size via modular compilation and linking. It
  406. also provides a toolbox of routines for virtual array
  407. management, as well as analytical tools for overlayed
  408. programs. Our third product, T-DebugPLUS, is an expanded and
  409. fully supported version of the popular public domain program
  410. TDEBUG. It includes both a fully symbolic debugger integrated
  411. with the Turbo Pascal development environment, and also the
  412. ability to generate DOS standard MAP files for use with other
  413. external symbolic debuggers such as Periscope, Symdeb, and Atron.
  414.  
  415. The TSR Utilities were written by Kim Kokkonen, with thanks to
  416. Neil Rubenking for the original idea behind MARK and RELEASE.
  417. Also my thanks to Richard Wilson and Barry Simon at CalTech for
  418. the idea that lead to FMARK, and much useful correspondence
  419. about the TSR Utilities.
  420.  
  421. We can be reached at:
  422.  
  423.      TurboPower Software
  424.      3109 Scotts Valley Drive #122
  425.      Scotts Valley, CA 95066
  426.      408-438-8608
  427.      Compuserve: 72457,2131
  428.  
  429. Version 2.2 - 3/4/87
  430.