home *** CD-ROM | disk | FTP | other *** search
/ Power Utilities / Power Utilities.iso / utility / pro190 / grabber.doc < prev    next >
Encoding:
Text File  |  1988-11-15  |  17.1 KB  |  385 lines
  1.  
  2.  
  3.                      GRABBER.COM   Ver. 3.2
  4.  
  5.                                and
  6.  
  7.                      GRFILTER.COM  Ver. 1.0
  8.  
  9.                     ------------------------
  10.  
  11.                    The Screen Capture Programs
  12.                     for the IBM PC/XT/AT and
  13.                   Color Graphics or Monochrome
  14.                          Display Adapter
  15.  
  16.                 DOCUMENTATION AND TECHNICAL NOTES
  17.                         November 15, 1988
  18.  
  19.                       Copyright (C) 1988 by
  20.                         Gerald A. Monroe
  21.                       All rights reserved.
  22.  
  23.  
  24.  
  25. GRABBER and GRFILTER are currently marketed as shareware
  26. programs.
  27.  
  28. This means you have the opportunity to use and evaluate them
  29. before you decide to buy.  If you find that they meet your
  30. expectations, then you are strongly encouraged to send your
  31. registration fee of $10.00 to me at the address given below.
  32.  
  33. That's a very reasonable price, I think, for the very unique
  34. and efficient utilities you've received in this package.  Whether
  35. you use your computer mainly for spreadsheet analysis, system
  36. development, PC consulting or just playing games, I'm sure
  37. you'll find GRABBER and GRFILTER very helpful tools.
  38.  
  39. From a programmer's perspective, GRABBER is a prime candidate
  40. for your AUTOEXEC.BAT file.  It takes advantage of some of
  41. DOS's most interesting characteristics to perform file I/O 
  42. safely and promptly whenever called upon.  GRABBER is fully
  43. compatible with Borland's Sidekick (tm), provided it is loaded
  44. before that program, and has tested reliably in some of the 
  45. most treacherous memory environments I could cook up.
  46.  
  47. Avid users, please send your $10.00 registration to:
  48.  
  49.             Jerry Monroe
  50.             1241 Bunts Road
  51.             Lakewood, Ohio 44107  U.S.A.
  52.  
  53. If you have any questions or comments concerning GRABBER.COM
  54. or GRFILTER.COM, and you have a modem, please leave a message 
  55. for Jerry Monroe on Norm Henke's PC-Ohio II BBS at (216) 291-3048.
  56. This is the official support BBS for GRABBER and its related
  57. video utilities.
  58.  
  59.  
  60. GRABBER.COM -- Documentation and Technical Notes      Page 2 of 8
  61.  
  62.  
  63.  
  64. PART I -- GRABBER
  65. ------------------
  66.  
  67.  
  68. GRABBER.COM, Ver. 3.2, is a memory-resident screen-capture 
  69. utility for the IBM Personal Computer and true compatibles.
  70.  
  71. Requirements:  IBM PC, XT, AT, PS/2 or compatible computer; one 
  72.                diskette drive; Color Graphics display adapter or
  73.                Monochrome Text adapter; PC- or MS-DOS Version
  74.                2.0 or greater.
  75.  
  76. Unlike any other resident screen-capture program of which the 
  77. author is yet aware, GRABBER Ver. 3.2 saves any text or 
  78. graphics screen produced by the Color Graphics Adapter (CGA),
  79. as well as text screens on the Monochrome Display Adapter (MDA),
  80. to an executable .COM file.  In order to restore the saved image
  81. to the screen, it is necessary only to execute the resulting 
  82. program file at the DOS command level.
  83.  
  84. To install the program in memory, type GRABBER d: or GRABBER /D
  85. at the DOS prompt.  The parameter is not optional; entering
  86. GRABBER by itself displays a brief help screen but does not
  87. activate the program.  If a valid drive parameter is specified
  88. (A: to Z:), all captured screens will be saved to program files 
  89. on that logical or physical drive.  If the /D parameter is given,
  90. GRABBER will save screens to whatever drive and path is currently
  91. the default.
  92.  
  93. GRABBER does not recognize subdirectory names on the command 
  94. line.  Users of DOS versions 3.10 and above, however, may use its
  95. very useful SUBST program to refer to any path in their hard disk 
  96. tree structures using a logical drive letter.  (In order to use
  97. SUBST, you may need to include a LASTDRIVE command in your
  98. CONFIG.SYS file; consult your DOS manual for details.)
  99.  
  100. To change the drive to which screens are saved during a session,
  101. simply run GRABBER again from the DOS prompt with the new parameter.
  102. For example, if your AUTOEXEC.BAT file includes the command
  103. GRABBER /D and you want to save all subsequent screens to a floppy
  104. diskette in drive A, issue the command GRABBER A: and the switch
  105. will be made instantly.
  106.  
  107. Beginning with Version 3.2, GRABBER may be removed from memory
  108. by entering GRABBER /U from the DOS prompt.  GRABBER is very
  109. tightly written in assembly language code, and therefore uses a
  110. small amount of memory -- about 2K of your RAM.  The uninstall
  111. option is provided for times when you want to free as much memory
  112. as possible for use by another application, or when GRABBER's
  113. trigger-key combinations conflict with another program.  GRABBER
  114. can be successfully uninstalled only under certain conditions,
  115. which are described below.
  116.  
  117.  
  118. GRABBER.COM -- Documentation and Technical Notes      Page 3 of 8
  119.  
  120.  
  121.  
  122. Once GRABBER is loaded, it monitors all keyboard activity,
  123. waiting for the key combinations of Ctrl-= (or Ctrl-1) before
  124. going to work.  These two keystroke combinations have different
  125. uses which are explained below.  When it detects the trigger,
  126. GRABBER steps in to create a .COM program file containing the
  127. current text or graphics image, either in the current default
  128. path or the prespecified path, as explained above.  Control is
  129. then returned to DOS or the interrupted application program.
  130.  
  131. If a capture request is made via the trigger keys and an error is 
  132. encountered while writing the "offspring" .COM file, the program 
  133. will signal the error condition by sounding three short beeps on 
  134. the PC's speaker.  The beeps mean that the image has not been 
  135. saved, and the user should correct the error condition and try 
  136. the capture again.  Common errors include trying to write to an 
  137. empty diskette drive, a write-protected or damaged disk, or a 
  138. disk whose directory or data space is already full.
  139.  
  140. *****      NEW WITH VERSIONS 3.X  --  MONOCHROME SUPPORT      *****
  141. *                                                                 *
  142. *  GRABBER now supports systems equipped with monochrome text     *
  143. *  display adapters (MDA's).  This means users with monochrome    *
  144. *  screens can now save 80x25 text images to disk.  GRABBER does  *
  145. *  support Hercules-compatible Monochrome Graphics Adapters, but  *
  146. *  currently only in text mode.  To capture screens on an MDA     *
  147. *  system, use only the Ctrl-= trigger.  Future versions of       *
  148. *  GRABBER will support the graphics capabilities of monochrome   *
  149. *  systems.                                                       *
  150. *                                                                 *
  151. *******************************************************************
  152.  
  153. As noted above, GRABBER responds to two key combinations: Ctrl-= 
  154. and Ctrl-1.  To capture any text image and most graphics images 
  155. to disk, use Ctrl-=.
  156.  
  157. In some situations where a graphics capture is required, it may 
  158. be necessary to use Ctrl-1 instead.  The graphics mode of Lotus 
  159. 1-2-3, Rel. 1 and 1A(*), is one such situation.  This program, 
  160. and others which you may encounter, employ custom video drivers
  161. to manipulate the display screen directly without using the PC's
  162. built-in video services, on which GRABBER normally relies.
  163.  
  164. If you are trying to capture a graphics image on a CGA system,
  165. but the offspring .COM program displays only garbage, this is a
  166. good indication that Ctrl-1 should be used with your program while
  167. it is running in graphics mode.  If this doesn't produce the
  168. desired result, and you're a registered user, please contact me
  169. to fix the problem.
  170.  
  171. To clarify things, 1-2-3 Rel. 2.0 and above use Ctrl-= in any 
  172. video mode.  Rel. 1 and 1A(*) use Ctrl-1 only in graphics mode, 
  173. and Ctrl-= in text mode.
  174.  
  175.  
  176. GRABBER.COM -- Documentation and Technical Notes      Page 4 of 8
  177.  
  178.  
  179. Uninstalling GRABBER
  180. --------------------
  181.  
  182.  
  183. Under certain conditions, GRABBER may be removed from memory
  184. without rebooting the system, by using the GRABBER /U command.
  185. Once GRABBER has been successfully uninstalled, the trigger key-
  186. strokes described above (Ctrl-= and Ctrl-1) will revert to their
  187. normal DOS defaults or to any application which requires them.
  188. Also, any drive parameters specified in previous installations
  189. will be erased.  To restart GRABBER after uninstalling it, simply
  190. enter GRABBER d: or GRABBER /D again from the DOS prompt or batch
  191. file and proceed as usual.  Offspring filenames will start again
  192. at SCREEN00.COM after GRABBER is uninstalled and reinstalled.
  193.  
  194. GRABBER may not be uninstalled if, after the last time it was
  195. loaded, you also loaded other memory-resident software which is
  196. activated by any of the same hardware or software interrupts which
  197. GRABBER uses.  Attempting the GRABBER /U option under such circum-
  198. stances will not work, and the program will exit with a message to
  199. this effect.
  200.  
  201. Also, do not attempt to uninstall GRABBER while on temporary leave
  202. from another application through a DOS shell, or while a secondary
  203. copy of COMMAND.COM is running.  Many programs, such as WordPerfect
  204. ("Shell") and Lotus 1-2-3 ("/System"), allow you to escape to the
  205. DOS prompt or run another program without really leaving the orig-
  206. inal program, and return to them quickly with an "EXIT" command.
  207. GRABBER may allow the use of the /U option under these circum-
  208. stances, but the results can sometimes be unpredictable.
  209.  
  210. If you wish to uninstall GRABBER and are not sure if the system is
  211. running under one of these secondary command processors, you can
  212. make sure by entering the "EXIT" command twice at the DOS prompt.
  213. If nothing appears to happen -- that is, you do not return to
  214. another application program, and the DOS prompt remains -- then
  215. it is safe to use the GRABBER /U command.
  216.  
  217.  
  218. GRABBER.COM -- Documentation and Technical Notes      Page 5 of 8
  219.  
  220.  
  221. PART II -- OFFSPRING
  222. ---------------------
  223.  
  224.  
  225. GRABBER's "offspring," i.e. the screen programs it creates, 
  226. are named sequentially, SCREEN00.COM, SCREEN01.COM, and so forth.  
  227. The filenames will start over again at SCREEN00 every time the 
  228. computer is rebooted, GRABBER is uninstalled/reinstalled, or
  229. after the one-hundreth snapshot in a session (SCREEN99) is taken.
  230. In order to prevent valued screen files from being overwritten by
  231. new screens with the same name, therefore, it is advisable to
  232. REName them at the first available opportunity to something more
  233. descriptive.  The renamed file must retain the .COM extension to
  234. be recognized by DOS as an executable program.
  235.  
  236. Suppose that you have created a bar graph using 1-2-3 and captured
  237. the image to disk, renaming the file GRAPH.COM.  Entering the com-
  238. mand GRAPH [/F] [/Tn] [keylist] at the DOS prompt will restore 
  239. the graphics image to the screen almost instantly.  (More on the 
  240. /F, /Tn and keylist options below.)  The GRAPH program then clears
  241. the keyboard buffer and pauses until a key is pressed.  At this
  242. point, the screen is cleared, the video mode and palette in effect
  243. when GRAPH.COM was invoked will be restored, and the cursor will
  244. reappear at the lower left-hand corner of the screen.
  245.  
  246. There are situations in which you might wish to load an image on
  247. the screen and return control to DOS immediately, without having
  248. to press a key first.  This is where the optional /F ("Fast")
  249. switch comes in.  In the example above, the command GRAPH /F
  250. alters program execution so that the image is displayed as
  251. before, but the cursor will be placed at the lower left corner
  252. of the screen right away and the DOS prompt will reappear there.
  253.  
  254. The /F ("Fast Display") option
  255. ------------------------------
  256.  
  257. The /F switch is recommended only for text images, since it may
  258. leave behind unattractive patterns on the screen when used with
  259. graphics images.  If you choose a fast display with a graphics
  260. image and need to clean things up afterward, the DOS command
  261. "MODE CO80" will set things right again.
  262.  
  263. Any text screen captured from a monochrome display can be dis-
  264. played on a color system as well.  Likewise, 80x25 text screens
  265. captured on a CGA system can be viewed on a monochrome display.
  266. However, 40x25 color text screens, and 320x200 or 640x200 CGA
  267. graphics images, cannot be displayed on monochrome systems.
  268.  
  269.  
  270. GRABBER.DOC -- Documentation and Technical Notes      Page 6 of 8
  271.  
  272.  
  273.  
  274. *****  NEW WITH VERSIONS 3.X  -- INTERACTIVE BATCH SUPPORT  ******
  275. *                                                                *      
  276. *  SCREENXX  [keylist]                                           *
  277. *                                                                *
  278. *  GRABBER now features support of DOS "errorlevel" functions,   *
  279. *  a great aid for those using GRABBER screens with DOS menu     *
  280. *  systems and "slideshow" programs driven by interactive batch  *
  281. *  files.                                                        *
  282. *                                                                *
  283. ******************************************************************
  284.  
  285. In addition to the /F command option, GRABBER offspring are now
  286. equipped to communicate with batch files using the DOS errorlevel
  287. facility.  To do this, include one or more "response keys" on the
  288. command line after the name of your offspring program.  The screen
  289. will be displayed, but only the press of a letter- or number-key
  290. on the keylist will exit the screen.  The program then passes to
  291. DOS an errorlevel value relative to that key's position in the
  292. keylist.  Your batch files can test this errorlevel and branch
  293. accordingly.
  294.  
  295. For example, say you have painted and captured (with GRABBER) a
  296. menu screen for your PC and called it MENU.COM.  The menu has
  297. three choices labeled (A), (B) and (C).  Include in your menu
  298. batch file this command:  MENU a,b,c
  299.  
  300. When run, the menu screen is displayed and waits for the user
  301. to make a choice.  If "A" or "a" is pressed, the screen exits
  302. and passes an errorlevel of 1.  Pressing "B" or "b" passes a 2,
  303. "C" or "c" gives a 3, and so forth.  Any other keypress is
  304. ignored, including spaces, commas, tabs or "/" slashes.  Entering
  305. "MENU 1,2,3,X" for instance, is the same as "123X", "1 2 3 X" or
  306. "1/2/3/X".
  307.  
  308. Note that an offspring screen with a keylist may be exited by
  309. pressing Ctrl-C or Ctrl-Break.  In such cases, an errorlevel
  310. of 255 will always be passed.
  311.  
  312. PLEASE NOTE:  GRABBER's /F and keylist options are not compatible
  313. with each other.  If a /F parameter is present anywhere on the
  314. command line, the program assumes that a fast display is desired
  315. and will ignore any keylist which may also be present.
  316.  
  317. Any alpha-numeric or function key may be used to exit a GRABBER
  318. offspring program entered without the /F or keylist parameters.
  319.  
  320.  
  321. GRABBER.COM -- Documentation and Technical Notes      Page 7 of 8
  322.  
  323.  
  324. The /Tn (Timer) option
  325. ----------------------
  326.  
  327. New with GRABBER Version 3.2 is the addition of an auto-exit
  328. option for offspring programs, activated by a /Tn parameter on
  329. the command line.  This option is especially useful for running
  330. slideshow demonstrations or similar batch-driven applications
  331. on an unattended computer, or whenever you wish to bypass the
  332. need for keyboard input.
  333.  
  334. When the /Tn timer option is used, the offspring program will
  335. display its image and wait for the number of seconds you specify
  336. (represented by n) before exiting to DOS or the calling batch file.
  337. The value of n may range from 1 to 999 seconds (about 16-1/2
  338. minutes), positive integers only.  When /Tn is used, it is not
  339. necessary to press a key to exit to DOS; in fact, all keystrokes
  340. except <Esc> will be ignored.  To exit an image before n seconds
  341. have elapsed, simply press <Esc>.
  342.  
  343. The /Tn option may be used together with the /F fast display
  344. option.  Like /F, however, the timer option is not compatible
  345. with the keylist option, and will override any keylist which may
  346. also be present on the command line.
  347.  
  348.  
  349. GRABBER.COM -- Documentation and Technical Notes      Page 8 of 8
  350.  
  351.  
  352. PART III -- GRFILTER.COM
  353. -------------------------
  354.  
  355.  
  356. GRFILTER is a new program accompanying GRABBER Vers. 3.X.  It may
  357. be used only with offspring files created by this or later versions
  358. of the GRABBER program.  Converting a GRABBER offspring from an
  359. earlier version to 3.0+ format is easy: simply display it and
  360. recapture it using Ctrl-=.
  361.  
  362. GRFILTER is a binary-to-ASCII file filter specifically for GRABBER
  363. offspring programs containing 80x25 or 40x25 text screens only.
  364. When run, it prompts the user for the name of a valid offspring
  365. program (.COM file), and a filename for the filtered ASCII output.
  366. Full pathnames are acceptable.
  367.  
  368. GRFILTER searches through the offspring program for the ASCII
  369. text data it contains, disregards any nonprintable binary
  370. information, and creates a pure-ASCII text file given the
  371. specified name and optional path.  As with any ASCII file, you
  372. may TYPE this output to the console, COPY it to the printer,
  373. edit it with your word processor or import it into a spreadsheet.
  374.  
  375. GRFILTER opens your offspring program file for reading only, and 
  376. does not alter the original file in any way.  You may pass it
  377. through GRFILTER as many times as you like, and it will always
  378. execute the same way, according to any optional parameters you
  379. may supply, which are described above.
  380.  
  381. GRFILTER can be run interactively without parameters, or you may
  382. supply the input and output files on the command line:
  383.  
  384.     GRFILTER [d:][path]SCREENXX.COM  [d:][path]SCREENXX.TXT
  385.