+--- |-|_,_/ ----------------------------------------------------------+ | Arcostr. 10-12 | | Henning E. Weede 10587 Berlin | | Germany | | Voice: +49-30-3411280 / +49-30-314-25534 | | Fax: +49-30-314-22885 | | E-mail: hw@ocean.fb12.tu-berlin.de | +----------------------------------------------------------------------+ User's manual of the function key TSR H O T K E Y D E V I L V1.0 Copyright (C): Henning E. Weede, 1995 Contents 1. Purpose of this tool ................................. 1 2. Functions ............................................ 2 2.1 Copy from screen masks to a file .................. 2 2.2 Screenshot ........................................ 2 2.3 Logging ........................................... 3 2.4 Execute other programs ............................ 3 2.5 Help .............................................. 3 2.6 Unload ............................................ 3 3. Usage ................................................ 4 4. Configuration ........................................ 5 4.1 Effects of the configuration file HD.CNF .......... 5 4.2 Syntax rules of the configuration file HD.CNF ..... 5 4.2.1 Key names ...................................... 5 4.2.2 Functions and their parameters ................. 6 4.2.3 Description string ............................. 6 5. Error messages ....................................... 7 5.1 During loading .................................... 7 5.2 From the background ............................... 7 6. Terms and conditions ................................ 10 7. Technical data ...................................... 11 - 1 - 1. Purpose of this tool HOTKEY DEVIL flexibly allows to copy text from the screen to a file while any program is running. This adds an interface to software that lacks file output at all or whose file format is undocumented and thus worthless for software of other vendors. Some software vendors deliberately avoid interfaces to proven and cheap standard software for - say - accounting in order to sell their own expensive and poor accounting software as well. HOTKEY DEVIL contributes significantly to a solution of this problem. HOTKEY DEVIL can be configured for any kind of screen masks: it reads texts at defined locations on the screen, concatenates them to one line (data record) and adds them to a file. This makes a tabular file from consecutive screen masks. Alternatively to masks, screen output may be linewise and scrolling like a terminal. HOTKEY DEVIL can log this in a file. Additionally, HOTKEY DEVIL can execute other programs from a running application. HOTKEY DEVIL stays resident in memory after its termination and enhances the keyboard driver. While any program is running, HOTKEY DEVIL monitors the keyboard and runs one of is functions each time the corresponding key is pressed. As HOTKEY DEVIL reads characters from the screen, text mode (rather than graphic mode) is necessary. - 2 - 2. Functions 2.1 Copy from screen masks to a file The configuration file HD.CNF contains information on the number of screen mask fields, their positions on the screen and their lengths. If one hits the corresponding key, these fields are combined to one line and appended to the file, followed by a carriage return and a newline character. This action is acknowledged visually - the saved parts of the screen change their color for about half a second. Different function keys can be configured for different screen mask formats. Each function key has its own output file. 2.2 Screenshot All 25 rows and 80 columns of the screen are appended to the file. A carriage return and a newline character is added to each row. Tailing blanks are omitted. The screenshots are separated by dashed lines. This action is acknowledged visually - the screen changes its color for about half a second. 2.3 Logging This function can be switched on and off. If it is on, everything that appears linewise on the screen and scrolls when the screen is full is also written to the file. The scrolling part of the screen must extend all over the width, but not necessarily all over the height. Status lines at the top or bottom are not written to the file even if the cursor is busy there, e.g. to update a clock. - 3 - 2.4 Execute other programs The configuration file HD.CNF contains information on which key shall load and execute which program. The currently running application is interrupted and continues to run after termination of the secondary program. MS-DOS itself is called by COMMAND and terminates when EXIT is typed. 2.5 Help A tabular is displayed that shows which function key executes which function. The description of the function can be defined in the configuration file HD.CNF. The tabular disappears again at the next keystroke. This help information is also displayed when HOTKEY DEVIL is started. 2.6 Unload The interrupt vectors modified by HOTKEY DEVIL are re-established, and the memory occupied by HOTKEY DEVIL is freed. However, if after starting HOTKEY DEVIL another program has included these interrupt vectors in its interrupt chain, this would cause a system crash. In this case, HOTKEY DEVIL refuses to unload itself and asks the user to stop that other program first. - 4 - 3. Usage To start HOTKEY DEVIL, not only the executable file HD.EXE, but also the configuration file HD.CNF must be in one of the directories hold by the environment variable PATH. If there are several configuration files, it depends on the PATH variable which one is taken. If there is one in the working (current) directory, it is taken in any case. By hand or as a line in C:\AUTOEXEC.BAT, HOTKEY DEVIL is started with the command HD whereafter the help information appears and control goes back to MS-DOS. After that, the functions can be triggered by keystroke. Execution of secondary programs and file operations in the background only are possible during execution of application code rather than MS-DOS system code. Applications usually switch between both states very frequently. To bridge phases that don't allow file operations in the background, HOTKEY DEVIL has a buffer. This buffer suffers an overflow if MS-DOS system code is running permanently, e.g. because there is no program running other than COMMAND.COM. If the key to execute another program has no effect, one has hit it the wrong time, during execution of MS-DOS system code, and should try it again. - 5 - 4. Configuration 4.1 Effect of the configuration file HD.CNF When started, HOTKEY DEVIL looks for its configuration file HD.CNF in the directories hold by the environment variable PATH, beginning with the working (current) directory. Then it configures its function key assignments according to the contents of the configuration file. HD.CNF can be modified with an editor. Modifications will become effective when HOTKEY DEVIL is started next time. 4.2 Syntax rules of the configuration file HD.CNF Every valid line of HD.CNF assigns a function and parameters to a key. Invalid lines are ignored. Especially empty lines and comment lines beginning with # are invalid. The general syntax of a valid line is keyname function parameters "description" 4.2.1 Key names Valid key names are: F1 ... F10, s-F1 ... s-F10, c-F1 ... c-F10, a-F1 ... a-F10, a-a ... a-z, a-0 ... a-9, left, right, up, down, home, end, pgup, pgdn, ins, del, s--tab, c-left, c-right, c-home, c-end, c-pgup, c-pgdn, c-prn, a--, a-=. a- means "alt", s- means "shift" and c- means "ctrl". - 6 - 4.2.2 Functions and their parameters VIDEO filename (column,row,length); (column,row,length); ... Texts (screen mask fields) are read from the screen, assembled to one line (record) and appended to the file. Example: s-F7 VIDEO hd.out (0,0,40); (60,24,20); takes the first 40 characters of the first row and the last 20 characters of the last (24th) row and appends them to the file hd.out, followed by cr,nl, each time the user presses the shift-F7 key combination. The syntax of the numerical parameters is free, they merely must be groups of digits separated by non-digits. VIDEO filename Without numerical parameters a copy of the whole screen is appended to the file ("screenshot"). LOG filename Switches logging on and off. If text is written linewise and scrolls, this option copies it to the file. Prerequisite: the text must be written with the cursor, and the scrolling area must be 80 characters wide. But not necessarily 25 lines, head and foot lines are allowed. DOS command MS-DOS executes that command. HELP Displays function keys and their meaning. As meaning the description string from HD.CNF is taken. QUIT Restores the interrupt vectors and frees the memory occupied by HOTKEY DEVIL, or reports why this is not yet possible. 4.2.3 Description string If the line ends with something in quotation marks, this is included in the help text which is displayed at start and when the help key is pressed. It is not necessary to mention filenames in the description because they are shown automatically. If the description of any key is missing, HOTKEY DEVIL displays a default text. - 7 - 5. Error messages 5.1 Error messages during start These messages are displayed on the standard error output. HD.EXE has been loaded already This message can be ignored unless you modified the configuration file. You forgot to press the key to unload before re-starting the tool. The configuration file HD.CNF is missing. It is missing indeed or the environment variable PATH doesn't contain the directory where HD.CNF can be found. Not enough free memory When attempting to allocate some few bytes for the function key parameters, e.g. screen mask definition, even these few bytes weren't available. This message is very unlikely to appear. 5.2 Error messages from the background These error messages are displayed as a white-on-red window and disappear upon keystroke. +----------------------------------------------------------------------+ | Error in HOTKEY DEVIL | | (DOS-command): not enough core | +----------------------------------------------------------------------+ You hit the key to execute another program, but there isn't enough free memory. Unload other TSRs and try again. - 8 - +----------------------------------------------------------------------+ | Error in HOTKEY DEVIL | | (filename): no such file or directory | +----------------------------------------------------------------------+ The filename, as defined in HD.CNF, is illegal. +----------------------------------------------------------------------+ | Error in HOTKEY DEVIL | | HD.HLP: (error message) | +----------------------------------------------------------------------+ May happen when a temporary file for the help text is created. +------------------------------------------------+ | File buffer overflow. The software presently | | running in the foreground doesn't allow | | the function key tool | | HOTKEY DEVIL | | to flush its file buffer in the background. | | The buffer is cleared. | +------------------------------------------------+ The program running in the foreground didn't switch from MS-DOS system code execution to its own application code execution during the last 8000 bytes you attempted to write to disk with HOTKEY DEVIL. This foreground program is not suitable for HOTKEY DEVIL, like it's the case with COMMAND.COM. If you really need HOTKEY DEVIL from COMMAND.COM, execute any application program from time to time to give HOTKEY DEVIL a chance to flush its buffer. This error condition switches terminal logging off. - 9 - +---------------------------------------------------------+ | The software presently running in the foreground | | doesn't allow the function key tool HOTKEY DEVIL to | | start a program from the background. | +---------------------------------------------------------+ If you hit the key to execute another program three times, and always HOTKEY DEVIL refused because some MS-DOS system code rather than application code was executing, this message appears. It means that the program running in the foreground is more or less permanently in the MS-DOS system code and thus unsuitable for HOTKEY DEVIL. E.g. like COMMAND.COM. +------------------------------------------------+ | HOTKEY DEVIL | | cannot be unloaded. Its file buffer is not yet | | empty, and the software presently running in | | the foreground doesn't allow to flush it. | +------------------------------------------------+ Run any kind of application program that isn't permanently in the MS-DOS system code execution and thus allows HOTKEY DEVIL to flush its buffer. Hit any key to trigger buffer flushing. After that, you can unload HOTKEY DEVIL without loosing file contents. +-----------------------------------------------------------+ | HOTKEY DEVIL | | cannot be unloaded yet because the software running in the| | foreground still needs it (interrupt chain). Please stop | | this foreground software first. | +-----------------------------------------------------------+ Like HOTKEY DEVIL does, also this program's interrupt service routines call the interrupt service routines it found when it was loaded. These are the ones of HOTKEY DEVIL. If you remove them from memory, the system will crash. If you see this message although you stopped that program, it works improperly because it doesn't re-establish the interrupt vectors. - 10 - 6. Terms and conditions HOTKEY DEVIL is a software product consisting of a program, its documentation and a sample configuration file. It is protected by copyright law and remains property of its author, Henning E. Weede. The license fee is paid for the right to use the product rather than to own it. The product exists as shareware version free of charge and as licensed version to be paid for. The following is allowed: - to modify the configuration file, - to use the shareware versions for non-profit purposes, - to use the licensed version also for commercial purposes, - to multiply the shareware version and to distribute it to third parties free of charge. The following is not allowed: - to modify the program or its documentation, - to disassemble the program, - to achieve a profit by using or distributing the shareware version, - to hand the licensed version to third parties, - to install on hard disk more executable copies of the licensed version than paid for, - to make more copies of the licensed version than necessary for installation and backup. The author is not liable for - violations of contracts with third parties and - damages that may arise from running the program. There is the possibility that some other software products do not allow HOTKEY DEVIL to execute its functions when run parallely. It is the user's responsibility to investigate this with the shareware version before paying the license fee. Presently, in February 1995, the fee for the right to use the licensed version is 40.- US$ for each copy installed on a hard disk of a computer without network or attached to a local area network with not more than 20 computers. This includes the diskette and shipment or transmission by E-mail. For a surcharge a printed copy of this manual is available, as well as individual configuration files and adaptions of the program. Modifications of these terms can be agreed on within a written contract. Name and surface mail address of the author are as follows: First name: Henning Mid name: E. Last name: Weede Street: Arcostr. 10-12 City: 10587 Berlin Country: Germany The bank account the author is as follows: Country: Germany Name of bank: Commerzbank AG Berlin SWIFT code of bank: COBADEBBXXX From the U.S., remit via: Commerzbank New York Account # : 3702230 Credit cards not accepted. - 11 - 6. Technical data Product name, copyright: Product name: HOTKEY DEVIL Version number: 1.0 Autor, (C) Copyright: Henning E. Weede Scope of product, files: HD.EXE = executable program (modifications forbidden) HD.CNF = configuration file (modifications encouraged) HD.DOC = this manual (modifications forbidden) Hardware prerequisites: PC/AT/PS2 with Intel 8088 / 80286 ... 80486 / Pentium System software prerequisites: MS-DOS Version 5.0 or later Application software prerequisites (program running in the foreground): Video system: Text mode, 80*25 characters (BIOS mode # 3) Video RAM base address B800:0 (monochrome: B000:0) In terminal mode, cursor must follow linewise writing If scrolling: 80 columns wide, but not necessarily 25 rows high Others upon request Memory data: Required memory: 56K (shareware: 60K) plus 256 bytes environment Size of file buffer: 8192 bytes Modified interrupt vectors: 9h (keyboard hardware) 10h (video BIOS) 16h (keyboard BIOS) 28h (idle) Functionality: Maximum linelength in configuration file: 511 characters. Help text must fit on screen, from this follows: Maximum of functions defined the same time: 21, Length of filenames incl path: max. 55 characters, Key description without filename: max. 65 characters, Key description with filename: max. 56 characters minus filename. The author reserves the right of modifications.