Phoenix CD 2.0

home *** CD-ROM | disk | FTP | other *** search

/ Phoenix CD 2.0 / Phoenix_CD.cdr / 01e / miscutil.zip / BURNOUT.DOC < prev next >

Wrap

Text File | 1987-12-14 | 32KB | 693 lines

BURNOUT II Documentation ------------------------ V2.30 14-Dec-1987 Function -------- BURNOUT is an enhanced version of the old screen blanking program of the same name; its primary purpose is to blank out your video display after a specified length of time. BURNOUT II is significantly enhanced over BURNOUT; not only does it allow you better control over its operations, but it is written as a virtual device driver so that you can control it directly from your own programs. V2.30 notes ------------ In hardware blanking mode (H+) this version will blank EGA and VGA adapters, and it will turn off the CGA text mode border. EGA owners should now use H+, because it will blank the screen in any video mode (including 43-line mode) and it won't affect communications, as H- mode does. If you select H+ mode via CONFIG.SYS (i.e., at boot time), BURNOUT 2.30 will use about 2K less memory than 2.20 did. You will not be able to use H- mode after booting, however. V2.20 Notes ----------- This version will blank CGA-compatible adapters in graphics modes. The R parameter has been added. This is of interest primarily to programmers. V2.10 Notes ----------- This version adds "on demand" screen blanking. By pressing the left shift key and <Ctrl> simultaneously, you can force the screen to blank. The key combination can be altered via the new F parameter. Installation ------------ To install BURNOUT, follow two steps: place the file BURNDEV.SYS in the root directory of your boot diskette or hard disk, and modify the CONFIG.SYS file to include the statement "device=burndev.sys". In case you are not familiar with CONFIG.SYS: this is a small text file that DOS reads when booting. It contains various pieces of information that DOS and other programs can use when setting themselves up. Look in the root directory of your boot disk for the file CONFIG.SYS. If no such file exists, just type: copy con \config.sys<Enter> device=burndev.sys<Enter> Then press F6 (you'll see "^Z") and <Enter>, and you're done. If you already have a CONFIG.SYS file (which is likely), you must edit it to include the statement "device=burndev.sys". Do this using your text editor or word processor in text mode (or Edlin). Retain all existing information, and add the new line. Now reboot your machine. If all goes well, it will boot as usual. There will be no indication that anything has happened. However, the screen should blank out after about ten minutes of inactivity. You can clear the screen instantly by pressing the left shift key and <Ctrl> simultaneously. After the screen has cleared, any keystroke and most video activity will restore it. BURNDEV uses about 2400 bytes of memory if installed in H+ mode, 4400 bytes if installed in H- mode (see below). BURNOUT parameters ------------------ There are several ways in which you can alter the operation of BURNOUT. There is a demo program called BURNOUT.COM that you can use for this purpose. Its syntax is as follows: BURNOUT [count] [V±] [H±] [C±] [Fn] [R] The parameters are as follows: COUNT: changes the number of clock ticks until the screen blanks (this is called the "reset count"). For example, BURNOUT 5000 sets the reset count to 5000. This means that if BURNOUT observes no keyboard or video activity within 5000 clock ticks, it will blank the screen. On the IBM PC, there are about 18.2 ticks per second, so this means that the screen will clear after about 5000/18.2 seconds (275 seconds, or about four and a half minutes). (The default value on powerup is 10800 ticks, or about 10 minutes). You can set the reset count anywhere from 1 tick (not highly recommended) to 65535 ticks (about an hour). If you set the reset count to 0, BURNOUT will be effectively "deinstalled" until you set a new nonzero count. This is useful for programs that don't get along with the screen blanker. V: This stands for Video, and tells BURNOUT whether you want it to monitor video activity in addition to keyboard activity. You can set either "V+" (monitor video), or "V-" (don't). Thus, BURNOUT 5000 V- sets the reset count to 5000 ticks, and not to monitor video. Why would you not want to monitor video? Primarily because some programs continuously update the display (e.g., with a ticking clock) even when they're not doing anything. If you use V+, the screen would never blank. The default setting is V+. H: This stands for Hardware, and tells BURNOUT whether you want it to blank the screen by manipulating the hardware (i.e., by turning off the video signal), or by software (which it does by temporarily changing screen attributes to black-on-black, or nondisplay). Some explanation is in order. The preferred method of blanking the screen is to do it by manipulating the PC's video controller. This method is very fast and in general has fewer problems than the software method. However, it does have two problems. First, it is nonportable: it doesn't work with all PC-compatibles. Second, there have been reports that this method (which is used by most screen blanking programs) can PHYSICALLY DAMAGE a few non-IBM video adapters, notably the Hercules and similar cards. DO NOT USE H+ IF YOU ARE USING A HERCULES OR SIMILAR VIDEO ADAPTERS!!! YOU HAVE BEEN WARNED!!! If you ARE using a standard IBM video adapter or the equivalent, try H+, with a setting of about 10 seconds, to make sure it works: BURNOUT 180 H+ The screen should blank in about 10 seconds. If it does not, you will have to use H- (which is the default [safe] setting). Reset BURNOUT to some reasonable period of time, of course, after you have tested. NOTE: in H- mode, BURNOUT won't clear a 43-line EGA screen fully, and it won't turn off the CGA border. C: This stands for Continuous Clear. If you are using H+, you can skip this one, because it is ignored in hardware blanking mode. As mentioned above, software blanking is achieved by simply changing all video attributes to nondisplay (black-on-black). Now, if you are running in V- mode (not monitoring video), or if you are running a program that achieves video output by writing data directly to screen memory, new data will begin to appear on the screen, even though it is blanked. Continuous Clear attempts to remedy this by simply resetting all the attributes to black-on-black every time the clock ticks (18 times per second). The new data will flash on the screen and disappear immediately. F: This stands for Forced clear. It allows you to alter the key combination that will clear the screen instantly. You will need these codes: Right shift: 1 Left shift: 2 Ctrl: 4 Alt: 8 Decide what keys you want to use (any combination is OK), and add up the codes. For example, if you want the screen to clear when you press both shift keys, add 1 + 2. Use the sum with the F parameter: BURNOUT F3 If you wish to disable forced blanking, use zero: BURNOUT F0 Note that the maximum valid parameter is 15 (1+2+4+8, meaning all four keys must be pressed). Any parameter above 15 will be ignored. R: this stands for Reset. It resets the current tick counter to the reset value (i.e., to the COUNT value, default 10800) and restores the screen if it is currently blanked. This is of interest primarily to programmers who want to prevent BURNDEV from blanking the screen during lengthy computations. * * * * BURNOUT parameters can be entered in any order; illegal parameters, capitalization, and separators are IGNORED. Thus, the following are all equivalent: BURNOUT 5000 V+ H- F6 BURNOUT F6v+h-5000 BURNOUT H+, F6, V-, 5000 BURNOUT 5000H-F6V+ Obviously, you cannot enter something like: BURNOUT F75000 to set the force keys to 7 and the count to 5000. You'd have to use "5000F7" or "5000 F7", etc. In particular, note that "F7 5000" will NOT work. When we said that separators are ignored, we meant ignored. "F7 5000" and "F75000" are identical insofar as BURNOUT is concerned. If you enter a COUNT greater than 65535, you're on your own. You won't get what you expect. If you don't like the way BURNOUT.COM works, you're free to "roll your own"; see the section on writing to BURNDEV. When BURNOUT is finished, it will display the current device status. For example: Status: 09994,10000, ,C-,V+,H+ The format of the status line is: Status: nnnnn,nnnnn,B,C+-,V+-,H+- The first number is the current number of clock ticks remaining till the next screen blank; the second is the reset count (in this case, the two numbers will be very close). The "B", if present, indicates that the screen is currently Blanked (you won't see this after running BURNOUT--it is part of the stantus report for the programmers' interface). The "C", "V", and "H" flags indicate the current status of Continuous Clear, Video monitoring, and Hardware clearing. If the parameter is active, the indicator will be followed by a plus sign (+), otherwise a minus sign (-). In the above example, then, the current count is 09994, the reset count is 10000, the screen is not blanked (naturally), Continous Clear is off, and Video monitoring and Hardware clearing are on. If you run BURNOUT without any parameters, it will simply display status without changing anything. Setting parameters via CONFIG.SYS --------------------------------- You can also include any of these parameters in the CONFIG.SYS file so that they will be set immediately when you boot. For example, device=burndev.sys 8000 H+ V- F5 If you set H+ mode via CONFIG.SYS, BURNOUT will use about 2K less memory. However, you will not be able to switch to H- mode after booting. (more precisely, BURNOUT will permit you to switch to H- mode, but the screen will never blank. Software blanking, hardware blanking, and hardware damage --------------------------------------------------------- As of this writing (December 13, 1987), the BURNOUT system has been available to the public for over four years. We know that it is installed on many thousands of systems, and we have NO knowledge that BURNOUT has ever harmed a video adapter. The warning above stems from our knowledge that the hardware blanking technique as used by a similar program has, in fact, been known to damage some Hercules graphics adapters. To the best of our knowledge, hardware blanking is entirely safe on all video adapters sold by IBM, and on all adapters that are fully compatible. We know for a fact that it is safe on IBM-manufactured monochrome, CGA, and EGA adapters. Software blanking is safe on all adapters. It does not manipulate the hardware at all; it merely changes all video attributes (colors) to black-on-black, causing text to become invisible. However, doing so is a time-consuming process (in computer terms), and it can cause problems for some programs. In particular, software blanking can create problems for communications programs during lengthy file transfers; if the screen blanks during a transfer, data will be lost and the transfer will probably fail. Also, software blanking will not work on anything other than an 80x25 screen. So, hardware blanking is to be preferred--if it's safe. The point of all this is, don't be panicked by the warnings contained herein. Some people have told us, "we don't use BURNOUT because it is dangerous; instead, we use program X." Well, chances are excellent that program X uses exactly the same technique--they just don't bother to tell you of the potential danger, and they don't provide the alternative (and safe) software blanking method. If you have an IBM adapter, use H+ with confidence. If you have a Hercules adapter, use H-. If you have something else, PLEASE don't call us. We can't help--we can't possibly purchase and test all of the adapters on the market because we derive no revenues from BURNOUT. Ask your dealer if the card's video signal can be disabled in the same manner as the CGA's video signal, i.e., by turning off bit 3 of port 3D8h. Using the BRNDEV device ----------------------- NOTE: you will only need to read this section if you are a programmer and are interested in controlling the BURNOUT system from your own programs. As mentioned above, the screen blanker is implemented as a virtual device. The advantage to this is that it can be interrogated or controlled very easily, from the DOS command line or from your own programs. In fact, BURNOUT.COM is a very simple program that takes your command line parameters, sends them to the BURNOUT device, reads the current status back from the device, and displays the results. This section explains how to do this. When DOS finds the "device=burndev.sys" line in config.sys, it loads and installs the burndev.sys program as a virtual device. What this means, practically speaking, is that there is now a new "device" attached to your PC. You already have several devices installed: CON, PRN, COM1 and COM2, AUX, your disk drives, and possibly a RAM (or virtual) disk if you have installed VDISK.SYS or another disk emulator. The new device is known to DOS by the name "BRNDEV" (note: this is NOT "BURNDEV", it's "BRNDEV", no U). Like other devices, you can write (send information) to the device, and you can read (receive information) from the device. BRNDEV is designed to accept certain very specific information (the BURNOUT parameters) when it is written to, and to return certain very specific information (the BURNOUT status) when it is read from. Writing to BRNDEV ----------------- NOTE: you will only need to read this section if you are a programmer and are interested in controlling the BURNOUT system from your own programs. How do you "write" to BRNDEV? There are many ways. The simplest is to do it right from the keyboard, at the DOS prompt: copy con brndev<Enter> @8000 V-#<Enter> ^Z<Enter> The "copy con brndev" command instructs DOS that you want to copy input from the console device to the BRNDEV device. The console input "@5000 V-#<Enter>" is copied to the BURNOUT device when you hit the Ctrl-Z (end of copy) and <Enter> (execute) keys. To prove it worked, type "BURNOUT" and look at the new parameters; they should reflect a reset count of 8000 and no video monitoring. (The significance of @ and # will be explained shortly.) Another way to write to the device would be to copy a small textfile to BRNDEV. As an example, type copy con brndemo.txt<Enter> @10000V+#<Enter> ^Z<Enter> You should now have a small textfile, the contents of which are "@10000V+#". To sen it to BRNDEV, just type copy brndemo.txt brndev or type brndemo.txt > brndev Run BURNOUT to prove that the parameters have changed. The purpose of the "@" at the beginning of the output to BRNDEV is to tell the device to flush or rewind its I/O buffers. BRNDEV just sees a sequence of characters coming from DOS; it has no particular way to know when it is getting a new sequence of command characters. The "@" tells it to get rid of any old, leftover junk and to start fresh. Make a habit of prefixing all BRNDEV commands with an @ symbol. The "#" is the "execute" character. It tells BRNDEV that it has received the whole parameter list. Only when BRNDEV sees the # will it examine the parameter list and execute the commands. Thus, "#" should be at the end of all BRNDEV commands; something like "@5000 C+H-" will have no effect at all. "#" also has a second purpose, which will be covered below. It is also possible, of course, to send commands to BRNDEV from high level languages or from assembler programs. Here's a BASIC example: 10 OPEN "BRNDEV" FOR OUTPUT AS #1 20 PRINT #1, "@5000 C+ H-#"; 30 CLOSE 1 And C (this is C86); you'd want to add some error detection: { FILE *burnout, *fopen(); static char command[] = "@5000 C+ H-#"; burnout = fopen("brndev","w"); fwrite(command, 1, strlen(command), burnout); fclose(burnout); } For an 8086 assembler example, see the source for BURNOUT.COM (BURNOUT.ASM), which is included in the BURNOUT library. Basically, you have to open the device (filename=BRNDEV, fomode 0 or 2), and use function 40H (FWRITE) to write bytes to the device using the returned handle. Remember that you can use the R parameter (write an "@R#" to the device) to restore a blanked screen and reset the BURNDEV counter with performing any video output. Reading from BRNDEV ------------------- NOTE: you will only need to read this section if you are a programmer and are interested in controlling the BURNOUT system from your own programs. Unfortunately, reading from BRNDEV is not quite as simple as writing to it. There's no way that I can think of to do it from the command line; you really need a program (I suppose you could CTTY BRNDEV and then reboot when the machine went crazy [just kidding, don't try it]). Also, there is a bug in DOS 2.x that prevents you from using BASIC for this purpose (fixed under 3.0, however). Under 3.0, the BASIC program would be: 10 OPEN "BRNDEV" FOR OUTPUT AS #1 20 PRINT #1, "@#"; 30 CLOSE 1 40 OPEN "BRNDEV" FOR INPUT AS #1 50 BSTAT$ = INPUT$(19,1) 60 CLOSE 1 70 PRINT "BURNOUT status is "; BSTAT$ Note that we always write an "@#" to the device before reading its status. The @'s function is described as above, to flush any unfinished I/O from BRNDEV's buffers. The # is used for a slightly different purpose, however. It still tells BRNDEV to execute any pending commands (but there are none, because the @ just flushed them). The second purpose of # is the key one here: it tells BRNDEV to prepare for a status request. When BRNDEV sees the #, it examines its current status and puts the data into a buffer, from which it will be retrieved when it gets the request. Without the preparatory #, you'll get old data. The significance of the "19" in the INPUT$ statement is that the BRNDEV status report is 19 characters long. Here's a C example: { FILE *burnout, *fopen(); static char command[] = "@#"; char status[30]; burnout = fopen("brndev","rw"); fwrite(command, 1, strlen(command), burnout); fread (status, 1, 255, burnout); fclose(burnout); printf("BURNOUT status is %s\n", status); } Note that we requested 255 characters. DOS, in general, will halt a device read when it encounters a carriage return from the input stream (unless the device is in "raw" or binary mode). BRNDEV makes a habit of sending a CR after the last byte of the status report, so this will terminate the read automatically; no need to worry about the true length of the report. BASIC, however, will just keep reading until it accumulates the requested number of characters, so you do have to be watchful there. The same trick (requesting too many characters) will also work in assembler programs (again, see BURNOUT.ASM). Now, about that bug in DOS 2.x. It turns out that DOS will mess up if you ever request a single byte from an installed character device, which is what BRNDEV is. (Technically: EOF is set on the device, and you will not be able to do any further reads unless you mess with IOCTL and explicitly reset EOF.) Thus, the following assembler code will NOT work under 2.x: mov cx,19 ; Loop for 19 bytes Label: push cx ; Save loop count mov ah,3FH ; Read from file mov bx,BHandle ; BRNDEV file handle (from FOPEN) mov cx,1 ; One byte at a time mov dx,offset buf ; Where to put the data int 21H ; Perform read (do something with the byte) pop cx ; Recover loop count loop label ; Loop till 19 bytes read The first byte will be read OK, but no further input will be received. You MUST read at least 2 bytes at a time. This bug can be overcome in assembler and C by simply requesting the full status report in one read. However, it appears that BASIC requests only one byte at a time, even if you use something like INPUT$(19,n). Reading the second byte then results in a READ PAST EOF error. Tricks ------ NOTE: you will only need to read this section if you are a programmer and are interested in controlling the BURNOUT system from your own programs. You can do neat stuff like waiting for the screen to burn out, then turning it back on: 1 REM DEMO PROGRAM TO WAIT UNTIL SCREEN BLANKS 2 REM 10 OPEN "BRNDEV" FOR OUTPUT AS #1 20 OPEN "BRNDEV" FOR INPUT AS #2 30 WHILE NOT BURNED.OUT 40 PRINT #1,"@#"; 50 A$ = INPUT$(19,2) 60 BURNED.OUT = (MID$(A$,13,1) = "B") 70 WEND 80 BEEP: PRINT "Burned out!" 90 CLOSE 1: CLOSE 2 The 13th character of the status report, "B", will appear in the report only when the screen is blanked. Also, your programs can cancel BURNOUT totally, if desired: 1 REM DEMO PROGRAM TO DISABLE BURNOUT 2 REM 10 OPEN "BRNDEV" FOR OUTPUT AS #1 20 PRINT #1,"@0#"; 30 CLOSE 1 (I am not a BASIC programmer, so if any of these demo BASIC programs are dumb, someone tell me.) Naturally, it would be possible (and friendly) to read in the BURNOUT parameters, modify them while your program is running, and restore the original parameters when you are done. You can test whether or not BRNDEV is installed in a batch file by using the IF EXIST function: if exist brndev (do something) If you use Seaware's Extended Batch Language, you can use this test instead: bat stateof BRNDEV bat if %r = 0 type BURNOUT IS INSTALLED | goto -A1 bat type BURNOUT IS NOT INSTALLED bat -A1 Personal REXX users can try: if dosdir('brndev') \= '' then say 'BURNOUT is installed' If you have a one-floppy machine, you can trick DOS and BAT into not checking the second logical drive (and stopping the batch to ask you to "Insert diskette for drive B") by using if exist a:brndev (in DOS batches) bat stateof A:BRNDEV (in EBL batches) DOS apparently doesn't care if you prefix a device name with a drive ID. Incompatibilities and Problems ------------------------------ I am aware of only a few problems and interactions with other programs. In order for BURNOUT to "see" keyboard and video activity, active programs must use ROM BIOS (or DOS, which itself uses BIOS) for their keyboard input and video output. A few progams use neither; hence BURNOUT never sees their activity, and the screen will be irrevocably blanked. These programs are mostly word processors; two that I know of are WordVision and some versions of XyWrite. You must disable BURNOUT before using either of these ("BURNOUT 0" will do the trick). Most people do this in a batch or a PCED synonym: (batch file) burnout 0 wv burnout 10000 (PCED) ced syn wv 'burnout 0^*wv^burnout 10000' There are also problems with some communications programs if you use software blanking. If you are performing an extended length file transfer the screen may blank during the transfer. Software blanking takes a little time, and communications input can be lost while it is being accomplished. This, of course, messes up the transfer. And Continuous Clear is even worse. The solution is to either use hardware blanking, or to disable BURNOUT while transfers are taking place. You MAY be able to get away with leaving BURNOUT enabled, but disabling Continuous Clear (C-). Note that the word "BRNDEV" becomes a reserved word to DOS. You cannot name any file BRNDEV (or even BRNDEV.TXT, or whatever). DOS won't let you do that. If you do succeed, you won't be able to erase it. This is why the driver is stored in a file named BURNDEV.SYS rather than BRNDEV.SYS. Tick chart ---------- To save wear and tear on your calculator, here are some approximate tick counts: Minutes Count ------- ----- 1 1100 2 2200 3 3275 4 4375 5 5450 6 6550 7 7650 8 8725 9 9825 10 10920 20 21850 30 32760 40 43680 50 54600 60 65520 Copyright/License/Warranty -------------------------- This document and the program files BURNOUT.COM, BURNOUT.ASM, and BURNDEV.SYS ("the software") are copyrighted by the author. The copyright owner hereby licenses you to: use the software; make as many copies of the program and documentation as you wish; give such copies to anyone; and distribute the software and documentation via electronic means. There is no charge for any of the above. However, you are specifically prohibited from charging, or requesting donations, for any such copies, however made; and from distributing the software and/or documentation with commercial products without prior permission. An exception is granted to not-for-profit user's groups, which are authorized to charge a small fee (not to exceed $7) for materials, handling, postage, and general overhead. NO FOR-PROFIT ORGANIZATION IS AUTHORIZED TO CHARGE ANY AMOUNT FOR DISTRIBUTION OF COPIES OF THE SOFTWARE OR DOCUMENTATION, OR TO INCLUDE COPIES OF THE SOFTWARE OR DOCUMENTATION WITH SALES OF THEIR OWN PRODUCTS. THIS INCLUDES A SPECIFIC PROHIBITION AGAINST FOR-PROFIT ORGANIZATIONS DISTRIBUTING THE SOFTWARE, EITHER ALONE OR WITH OTHER SOFTWARE, AND CHARGING A "HANDLING" OR "MATERIALS" FEE OR ANY OTHER SUCH FEE FOR THE DISTRIBUTION. NO FOR-PROFIT ORGANIZATION IS AUTHORIZED TO INCLUDE THE SOFTWARE ON ANY MEDIA FOR WHICH MONEY IS CHARGED. PERIOD. No copy of the software may be distributed or given away without this document; and this notice must not be removed. There is no warranty of any kind, and the copyright owner is not liable for damages of any kind. By using this free software, you agree to this and you acknowledge that you are aware that BURNDEV and similar programs can, in some modes, cause physical damage to some brands of display adapters. The software and documentation are: Copyright (C) 1985, 1986, 1987 by Christopher J. Dunford The Cove Software Group P.O. Box 1072 Columbia, Maryland 21044 (301) 992-9371 CompuServe 76703,2002 [IBMNET]