Power-Programmierung

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

/ Power-Programmierung / CD1.mdf / batch / library / stackey3 / stackey.doc < prev next >

Wrap

Text File | 1990-03-25 | 237.8 KB | 5,563 lines

SSSS TTTTTT AA CCCC KKK KK EEEEEEE YY YY (tm) SS SS T TT T AAAA CC CC KK KK EE E YY YY SSS TT AA AA CC KK KK EE E YY YY SSS TT AA AA CC KKKK EEEE YYYY SSS TT AAAAAA CC KK KK EE E YY SS SS TT AA AA CC CC KK KK EE E YY SSSS TTTT AA AA CCCC KKK KK EEEEEEE YYYY Version 3.0 CTRLALT Associates _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER TABLE OF CONTENTS Chapter I:INTRODUCTION....................................3 I.1 What It Does.......................................3 I.2 For the new user...................................4 I.3..Shareware Considerations..........................5 I.4 New in Version 3.0................................10 I.5 New in Version 2.0................................11 I.6 Files in the STACKEY package......................12 I.7 Loading and Using STACKEY.........................13 I.8 HELP!!............................................15 I.9 Errorlevel........................................15 Chapter II:PLACING KEYSTROKES IN THE BUFFER..............17 II.1 Stacking text....................................17 II.2 Two-character Codes..............................17 II.3 Status Toggles...................................21 II.4 Prompt metastrings...............................21 II.5 Decimal and Hex Codes............................22 II.6 Invoking special programs and keystrokes.........23 II.7 Simulating depression of shift keys..............25 II.8 Stacking real time beeps.........................25 II.9 Popup messages...................................26 II.10 Sending to standard output......................26 Appendix 1 to Chapter II. Two character codes.........27 Appendix 2 to Chapter II...SENDing to STDOUT..........30 Chapter III:COMMANDS TO THE RESIDENT PORTION.............36 III.1 Overview........................................36 III.2 Repeats.........................................36 III.3 Delays..........................................37 III.4 Scanning........................................38 III.5 The phony keystroke.............................40 III.6 Hotkeys.........................................40 III.7 Pauses for keystrokes...........................42 III.8 Multiple STACKEY commands.......................42 III.9 Patient, impatient and smart processing.........43 III.10 Flushing and Quitting..........................45 III.11 Enlarging the Buffer...........................46 III.12 The SKRES program..............................47 III.13 Test mode......................................48 III.14 Continue mode..................................48 III.15 Pushing, popping and querying the flags........49 Chapter IV:SETTING COLORS................................50 IV.1 Color Basics: Introduction.......................50 IV.2 Color Basics: Graphics modes.....................50 IV.3 Color Basics: CGA color choices..................51 IV.4 Setting colors on the CGA........................52 IV.5 Color Basics: EGA color slots and palettes.......54 IV.6 Color Basics: EGA color labelling................54 IV.7 Color Basics: EGA borders........................56 IV.8 Color Basics: EGA hardware considerations........56 IV.9 Setting colors on the EGA or VGA.................57 IV.10 Setting permanent colors on the EGA/VGA.........59 IV.11 Controlling the blinking bit....................60 Chapter V:UTILITIES MODE.................................62 V.1 Overview of Utilities Mode........................62 V.2 Waits.............................................64 V.3 Switching Monitors and Ports......................67 V.4 Turning off PrintScreen...........................68 V.5 Mode, Lines and Cursor Control....................68 V.6 Beeps.............................................70 V.7 Screen dumps......................................70 V.8 Rebooting.........................................71 V.9 Lock Toggles......................................72 V.10 The Halt Command.................................72 V.11 Pause for input..................................73 Chapter VI:ADVANCED TOPICS...............................74 VI.1 Keyboard basics: interupts.......................74 VI.2 Keyboard basics: The buffer and BIOS data area...76 VI.3 Keyboard basics: Int 9 processing................77 VI.4 Keyboard basics: int 16/DOS service 8............79 VI.5 Keyboard Basics: How other programs work.........81 VI.6 Keyboard basics: How STACKEY works (or doesn't)..81 VI.7 Inline: Syntax...................................84 VI.8 External: Syntax.................................85 VI.9 Inline examples..................................86 VI.10 STACKEY's API...................................88 Chapter VII:ASSOCIATED PROGRAMS..........................90 VII.1 FILEKEY.........................................90 VII.2 EGAPAL and VGAPAL...............................91 VII.3 Demonstration BATch files.......................93 Chapter VIII:MISCELLANY..................................95 VIII.1 Usage notes....................................95 VIII.2 Also by the same authors.......................97 Appendix to Chapter VIII..............................99 Chapter I:INTRODUCTION FIRST A WORD FROM OUR SPONSOR: THIS IS NOT FREE SOFTWARE. IF YOU CONTINUE TO USE IT AFTER AN INITIAL 30 DAY TRIAL PERIOD, YOU MUST REGISTER; PLEASE SEE SECTION I.3. THANK YOU. I.1 What It Does STACKEY, a utility from the makers of CTRLALT, will automatically place keystrokes in your keyboard buffer. It is intended for use in connection with BATch files. Here is a typical example of a BATch file "lot.bat" for use with 1-2-3 using STACKEY: stackey W18 CR"/FR%1.wk1" CR 123 Entering "lot mysht" at the DOS command line starts the BATch file with mysht as %1. STACKEY has the command line passed to it by the BATch processor with %1 already replaced by mysht. Thus STACKEY places in the keyboard buffer the text: "/FRmysht.wk1" followed by a carriage return. The initial W18 tells STACKEY to pause about 1 second to allow 123 to load. If it weren't there 123 would happily remove the keystrokes from the buffer before allowing any input. These characters wait in the buffer until a program requests keyboard input. The BATch file then loads 123 which requests input and gets it from STACKEY. /FR calls up a dialog to retrieve a worksheet and %1.wk1 followed by a CR loads that worksheet. The CR after the W18 will banish the opening logo screen in those versions with an opening logo. And this example hardly uses the power of STACKEY: you can stack any function key or legal Alt-key combination; you can even stack today's date or the current directory name. You can stack commands to turn the Num Lock state on and off. You can stack commands to set colors on the CGA and remap colors on the EGA or VGA. You can stack a PrtSc. You can stack commands to call up SIDEKICK, SIDEKICK PLUS or any other program that pops up on pairs of shifts. You can invoke CTRLALT PLUS, CAROUSEL or DESQVIEW. STACKEY has numerous methods for controlling the flow of a STACKEY "script". You can put delays in or have STACKEY delay its playback until a given message appears on the screen or you can have script playback pause until you hit a key. You can pause playback and later restart it with appropriate hotkeys and even flush STACKEY's buffer that way. STACKEY also has a utilities mode allowing you to use it to replace lots of little utilities that switch monitors or ports, restore or change the cursor or even reboot your machine. STACKEY comes with a second program BATUTIL, described in a separate manual Chapter I:INTRODUCTION Page 3 Documentation for STACKEY, Version 3.0 with which you can manipulate your environment or get input in BATch files. Finally STACKEY has a special mode of interest to programmers giving you access STACKEY's insides, allowing you place inline code in the middle of a STACKEY script. And STACKEY does its magic with only about 1.3K of resident code (with the default buffer size). For a quick summary of what STACKEY can do, you can call up help any time you are at the DOS command line with the command stackey ? (see the HELP!! Section I.8 below) or you can consult the quick summary at the end of the documentation. I.2 For The New User STACKEY is a powerful package which has many features that you won't want to use too often. For that reason the manual is long but many parts can be skipped when you first start using the program. For the basic stacking commands, you'll want to read the first three sections of Chapter II after reading the next section. After that, you can be off and running. If you want to use utilities mode, you'll need to read Chapter V and if you want to set colors with STACKEY, you'll need Chapter IV. This latter chapter is long because of the EGA color tutorial which is included. If you have a CGA, you should only read the first four sections. If you've been confused when hearing about int 16 and int 9, you might look at the keyboard basics parts of Chapter VI. While STACKEY has numerous options to change the way it works, typically set and changed with /../ instructions on the command line, we have set the defaults to be the most reasonable. Thus, you need not worry about these questions unless you find yourself in a situation where you wished STACKEY worked differently in order to properly interface some particular application program. You may be able to tell it to act in an appropriate way. A summary of the STACKEY commands can be obtained by typing stackey ? Chapter I:INTRODUCTION Page 4 Documentation for STACKEY, Version 3.0 If you obtained a registered version of STACKEY/BATUTIL directly from Support Group, you'll find directions for installing the program in the readme.com program. The files on diskette are in self compressed archives prepared with the Lharc program. We thank Yoshi for writing this program and allowing its use. If you are a less advanced user, you'll want to run the batch file INSTHARD.BAT to install BATUTIL and STACKEY on your hard disk or if you have only two floppies, use INSTFLOP.BAT. The hard disk automated installation places the programs in the directories C:\stackey and C:\batutil. It requires roughly 700K of free disk space including the doc files which you won't need if you are registered and have the printed docs. INSTFLOP requires that you have four blank but formatted floppy diskettes handy. Both programs only run from the A: drive. More sophisticated users may wish to do the installation by hand to control the directories where the programs live (they can be anywhere although you may want them on your path). Go to the directory you want STACKEY, place the distribution diskette in drive A and run A:skexe and A:skdoc Then go to the directory you want BATUTIL and run A:buexe and A:budoc With floppies each command should be issued with a fresh floppy in drive B. If you got your trial version from a BBS or disk vendor, there directions for installation may be different. Basically you want to unpack any archives. You can then run the programs directly. I.3 Shareware Considerations The STACKEY package consisting of STACKEY, FILEKEY and EGA/VGAPAL were developed by Barry Simon and Richard Wilson and is copyright, 1986-90 by us. Unlike versions 1.x and 2.x which were copyrighted but free, this version is shareware. You have a 30 day trial period from the time that you first use the program to see if it meets your needs. If you continue to use it after that time you Chapter I:INTRODUCTION Page 5 Documentation for STACKEY, Version 3.0 are required to pay a registration fee not as a contribution but because you are getting use out of our program. Shareware is dedicated to the idea that users are best served by a chance to fully try out something as complex and individualistic as software before they buy it and that authors are served by an ethic that encourages wide copying for trial runs. But in order for the system to work you need to respect the trust that we show in you and register if you continue to use our program. With the release of this shareware version, we will no longer support earlier versions of STACKEY. Registration fees are as follows: License to STACKEY & BATUTIL with printed docs $39 Consultant's License $200 All registrations will get you the printed documentation and the latest version on disk. The printed documentation is essentially identical to the documentation on disk. You may register by phoning or writing (9AM-5PM Eastern time) Support Group, Inc Lake Technology Park PO Box 130 McHenry, MD 21541 1(800)872-4768 (1-800-USA-GROUP) 1(301)387-4500 FAX 1(301)387-7322 Visa, Mastercard, Discover and American Express are accepted. Registration gives you the right to use any version of STACKEY with a major version number of 3. If there is a version 4, an update fee may be required. In addition to the thirty day trial period, you may return the disks (and printed documentation) for a full refund if you are not totally satisfied for a period of 90 days after initial registration. You have the choice of one of two license terms: "use like a book" OR a single user license. The former allows you to place copies of this software on as many machines as you wish so long as there is NO CHANCE that more than one copy of STACKEY will be loaded into any of the machine's memories at one time. The latter allows you to place copies on all machines for which YOU are the principal user even if there is a chance that OCCASIONALLY more than one copy is in use (for example, if you use STACKEY on a office machine while a family member might OCCASIONALLY use a copy on a home machine at the same time). Chapter I:INTRODUCTION Page 6 Documentation for STACKEY, Version 3.0 This 800 number is for orders only. Registed users may obtain support by writing to CTRLALT Associates Suite 133 260 South Lake Ave. Pasadena, CA 91101 or you may reach us via MCIMAIL (CTRLALT Associates) or on Compuserve. Simon has a Compuserve number [76004,1664]. CTRLALT Associates has its own Compuserve support area: section 12 of PCVENDOR FORUM A. After logging onto Compuserve, GO PCVEN will take you to this forum. In addition to asking questions, you will be able to download the latest version and various sample files, tips, etc. You can aslo reach us on the IBMSYS forum and on the UTILITIES forum of PCMAGNET. For general discussions of shareware issues, you can GO SHAREWARE and leave messages in Section 8. You can also reach Simon via internet by using the Internet/Compuserve connection. Send messages on internet to 76004.1664@compuserve.com CTRLALT Associates is happy to offer a free Compuserve signup kit including a $15 credit. Details are provided with your registration kit. This offer is dependent on its continued availability from the Compuserve Information service. We're glad to hear comments, suggestions about enhancements, as well as complaints, incompatibilities and bugs. Suggestions for enhancements would be especially welcome. For example, we added utilities mode in going from version 1.0 to version 2.0 in response to a request to allow a reboot command. You can find the version of STACKEY by using the DOS command "type STACKEY.COM" or by passing a /?/ to STACKEY on the command line. Consultant's license: Consultant's may want to use STACKEY and BATUTIL to customize a client's system. For this purpose we offer a special consultant's license which allows you to personally place copies of BATUTIL and/or STACKEY on any client's machine without additional fees so long as no help or documentation is included. We refer here to the documentation and help files that we supply. If you are interested in some kind of bundling of STACKEY and/or BATUTIL with a product, please write to CTRLALT Associates at our address or send MCImail or Compuserve easyplex to us. Consultant's licenses are limited to people placing the software on machines owned by companies for which they are not employees, that is, it is not intended for sitewide licenses. Chapter I:INTRODUCTION Page 7 Documentation for STACKEY, Version 3.0 Volume discounts start at 5 copies and sitewide licenses at 500 copies according to the following: 5-10 copies: 15% discount 11-20 copies: 20% discount 21-500 copies: 25% discount sitewide license to 500 copies: $ 8,000 sitewide license to 1000 copies: $10,000 unlimited sitewide license: $25,000 Volume discounts are shipped with one set of (two - STACKEY and BATUTIL) manuals for each two program licenses. Sitewide licenses comes with 100 copies of the manuals with additional manual sets available for a nominal fee. Foreign users are asked, if possible, to pay via credit card. Foreign registrants will be billed for first class airmail postage. If you like the program, please give it to your friends, place it on bulletin boards and otherwise spread it around. We explicitly allow TRIAL use of it privately and in a commercial environment. You may give it away, but you may not charge for it or include it with commercial software without our permission. An exception is made for user groups and shareware software distributors who are approved shareware distributors of the Association of Shareware Professionals, an organization to which both Wilson and Simon belong. Those interested in contacting ASP to become approved distributors should write for an application to Association of Shareware Professionals Executive Director PO Box 5786 Bellevue,WA 98006 Vendors may only distribute the full BATUTIL/STACKEY package which archived fits on a single diskette; see vendor doc. This program is produced by a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at P.O. Box 5786, Bellevue, WA 98006 or send a Compuserve message via easyplex to ASP Ombudsman 70007,3536. Chapter I:INTRODUCTION Page 8 Documentation for STACKEY, Version 3.0 STACKEY is warranted for no particular purpose. While we have tried to make the program bug free, no software can be guaranteed to be free of bugs. Due to the complex nature of computer software CTRLALT ASSOCIATES does not warrant that the licensed Software is completely error-free, will operate without interruption, or is compatible with all equipment and software configurations. Repair, replacement or refund, at the option of the CTRLALT ASSOCIATES, is the exclusive remedy of the customer, in the event of a defect. By using this program, you accept it AS IS and agree that we will NOT be held responsible for any damages including but not limited to consequential damages or loss of data. This includes damages caused by problems of which CTRLALT Associates is already aware. We will attempt to correct any bug which is pointed out to us. Registered users are entitled to use bug fixes while still numbered 3.xx. We do not intend to support Version 3.xx once a Version 4.xx is available and you may need to pay an upgrade fee to a new version if there are any bug fixes made once Version 4.xx is available. You may ask for a full refund of your registration for a period up to 90 days after you register but only if you return the program package sent registered users and agree to destroy any copies of BATUTIL and STACKEY in your possession and cease using the programs. While we have attempted to make this documentation as clear as possible, we cannot guarantee that there will not be misunderstanding or user error. We specifically exclude any warranties, EXPRESS OR IMPLIED, including the IMPLIED WARRANTIES OF MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SOME STATES DO NOT ALLOW THE IMPLIED WARRANTIES TO BE EXCLUDED. CONSULT A LAWYER TO SEE WHETHER OR NOT THE ABOVE EXCLUSIONS APPLY TO YOU IN YOUR STATE. This documentation, the programs and source code for the associated programs STACKEY, FILEKEY, EGAPAL, VGAPAL and the demonstration BATch files COLOR, SEECOLOR, CGACOLOR, and SOUNDS are copyright by Barry Simon and Richard M. Wilson, 1986 - 1990, all rights reserved. The following may be trademarked names: Turbo Pascal, Reflex and Sidekick by Borland International, Newfont by Mark Horvatich, CED and PCED by the Cove Software Group, Fansi Console by Hersey Microcomputing, Software Carousel by Softlogic, IBM by IBM, Ultravision by Personics, Codeview by Microsoft, Quikbuf by Intel, Frieze by Zsoft, List by Vern Buerg, Move'em and 386Max by Qualitas, Qemm, Qram and DesqView by Quarterdeck, Pizazz Plus by Chapter I:INTRODUCTION Page 9 Documentation for STACKEY, Version 3.0 Applications Technology, Tesseract by Innovative Data Concepts, 123 by Lotus Development Corporation and Bradford by Concom. BATUTIL, STACKEY and CTRLALT are trademarks of Ctrlalt Associates. I.4 New in Version 3.0 If you have been using version 2.0 of STACKEY here are some of the new features in this version: - You can now pause playback (while allowing other programs to run in the foreground) until a stated character string appears at a given place on the screen or until it appears at the current cursor position. To remind you that this scan mode is on, the cursor will blink. As an alternative, you can scan "silently", that is with this visual cue not implemented. - You can simulate depressing any set of shift keys for a user specifiable number of clock ticks. This will allow popping up of SIDEKICK, SIDEKICK PLUS, PRIMETIME and many other programs. - You can load the resident part of STACKEY in high memory with 386max or Qemm. - You can invoke CTRLALT PLUS. - You can swap Carousel partitions or simulate the hitting of the Desq key in DesqView. You can also invoke any TSR which conforms to the Tesseract standard. - You can send STACKEY text strings and control codes to standard output rather than the keyboard replacing the need for a separate SEND program - STACKEY now has four hot keys which allow you to talk to the resident part from within other programs. One will stop playback and flush the buffer, one will pause playback until the third restart playback hotkey is hit, and one will cancel active scans. You can also pause a script to await the restart playback key. These keys can be changed from the DOS command line. - You can insert beeps and popup messages into STACKEY scripts. - For people who understand assembly language programming you can insert inline code or external files into a STACKEY script. This will allow others to provide custom routines to you even if you don't understand assembly code. - STACKEY now comes with a stand alone program BATUTIL which Chapter I:INTRODUCTION Page 10 Documentation for STACKEY, Version 3.0 gives you considerable control over batch files and over the DOS environment. - The EGA color support added in STACKEY 2.0 has been extended to VGAs and to users of Ultravision. - More informative error messages in response to syntax errors. I.5 New in Version 2.0 If you have been using version 1.0 of STACKEY, here are some of the new features of version 2.0 carried over to version 3.0: - Color support on the CGA including borders, background in medium resolution graphics and palette change - Color support on the EGA both temporary color changes and changes to permanent palettes when used in conjunction with a program that moves the permanent palettes to RAM - A separate program that moves the permanent palettes to RAM - A utilities mode that allows you to switch monitors, ports, cursor size, mode and 25 vs 43/50 lines. Variable beeps and a command to wait from .05 seconds to 30 minutes before resuming - Possibility to dump the screen to a file or printer at some point in the middle of a BATch file - The equivalent of DOS' pause but without a message (so you can supply your own) with the possibility of having the <Enter> key alone accepted or of having the BATch file aborted under a Y/N choice. This is now done better with BATUTIL but is kept in version 3.0 for compatibility with version 2.0 scripts. - Optional modes that control what happens when STACKEY finds a syntax error - Modes to handle programs that flush the buffer after every keystroke With the exception of two commands, version 3.0 is upward compatible with STACKEY, Version 1.0. The /xxxx/ has been replaced by /Bxxxx/ and /+xxxx/ by /Rxxxx/ (B for buffer and R for reload). Version 3.0 is fully upward compatible with Version 2.0. STACKEY Vers. 3.x ignore the existence of STACKEY Vers. 1.0 and 2.x. Thus if you try to load 3.x with the any earlier version resident, both will be loaded. And each will only talk to the appropriate version. However, if you try to run one version of STACKEY 3.x with another resident, you will get the message: Chapter I:INTRODUCTION Page 11 Documentation for STACKEY, Version 3.0 STACKEY: Version number doesn't match resident part. Re-install (Y/N)? I.6 Files in the STACKEY package There are six executable programs STACKEY.COM - The basic program SKRES.COM - Version for special loading; see Section III.11 FILEKEY.COM - Program to send input to STACKEY's stack from a file EGAPAL.COM - Program to allow STACKEY to control permanent palettes on the EGA VGAPAL.COM - Program to allow STACKEY to control permanent palettes on the VGA BOXES.COM - Small program for the demonstration BATch file CGACOLOR.BAT four demonstration BATch files CGACOLOR.BAT - Demonstrates STACKEY's color commands for the CGA COLOR.BAT - Demonstrates STACKEY's color commands for the EGA by displaying all 64 colors; use a parameter to indicate the time between color changes in half second units; e.g. "color 3" would give 1.5 second change times. SEECOLOR.BAT - Allows you to see any color or colors supported on the EGA by typing in their numbers or color patterns; e.g. "seecolor 14" or "seecolor RrGgB" or "seecolor 23 42" SOUNDS.BAT - Illustrates the {BEEP} command ten files demonstrating the STACKEY external interface: FLASH.BIN - External code to flash the screen FLASH.ASM - Source for flash.bin FLUSH.BIN - External code to reenable the keyboard and flush the buffer FLUSH.ASM - Source for flush.bin MAKEMESS.ASM - Shell for making popup yes no messages SAMPLE.MSG - A sample external made with MAKEMESS GAVOTTE.BIN - High class music external file Chapter I:INTRODUCTION Page 12 Documentation for STACKEY, Version 3.0 MONTEV.BIN - Another high class music external file POP.BIN - A less high class music external file MUSIC.ASM - Source for music files (See Section VI.9 for more on these samples). and the help files STACKEY.HLP - Basic Help file In addition, there are the files associated with BATUTIL discussed in the BATUTIL documentation. While these programs are the package and may be distributed as such, the original disks from CTRLALT Associates come with the files in compressed format. The file README.COM on the distribution disk will explain how to install the programs. You cannot just use the copy command. If you got them from another source, that source may have used another packing method. I.7 Loading and Using STACKEY The first time that STACKEY is invoked, it loads a small resident portion which becomes permanently resident taking almost exactly one kilobyte of RAM for code plus whatever buffer size you choose. By default the buffer size is 128 'keystrokes' or 256 bytes. This can be changed; see Chapter III - indeed many of the new features takes 3-10 keystrokes of buffer space and some considerable more so you may want a larger buffer. It displays the message: Resident part of STACKEY now in place. and proceeds to read its command line. At later times, STACKEY will find itself in memory and only read its command line. If you are using a hardware or software protocol that allows loading in high memory (MAXIT board, 386max or QEMM), you'll want to use SKRES rather than STACKEY as you will if you want a buffer with over 10000 keystrokes, see Section III.11. STACKEY will place keystrokes in its stack according to the rules of syntax described below. If there is a syntax error, it will exit with no keyboard stacking and give an error message. For example, saying stackey "hello "CRthere Chapter I:INTRODUCTION Page 13 Documentation for STACKEY, Version 3.0 will result in the error message Oops! There is an error on the STACKEY command line. "hello "CRthere ^ Unrecognized command. The arrow (shown as a caret here) will point to the first place on the line that STACKEY was unable to interpret. The command line to send hello on one line and there on the next should have said stackey "hello "CR"there" The arrow will indicate other errors; for example, if you ask STACKEY to swap printer ports but you only have one printer port, STACKEY will exit with Oops! There is an error on the STACKEY command line. {PRN} ^ Hardware or software environment does not appear to support this command. The syntax is fine but there is an error none the less. Similarly, if you try to swap Carousel partitions but STACKEY finds that Carousel isn't loaded, you will get an error message. The command line is parsed into parts consisting of text between quotes, two character special codes, hex and decimal input, delays and special commands. Some of the two character special commands allow an integer for the second "character" which may be more than one numeral. The special commands include EGA/VGA color settings between square [] brackets and utilities commands inside pointed braces {}. Certain of the new features like SCan and SHift take parameter inside (). If only a utility is called up and the final } is left off, the resident part of STACKEY will not load. Spaces between the parts are optional so that stackey F1"hello"^r@E is the same as stackey F1 "hello" ^r @E or even stackey F1 "hello" ^r@E but stackey F 1"hello"^r@E which splits the two character code F1 will result in an error message. Chapter I:INTRODUCTION Page 14 Documentation for STACKEY, Version 3.0 I.8 .HELP!! Seventeen screens of help are available if you type in stackey ? To get help, the file STACKEY.HLP distributed with STACKEY must be available either in the default directory or in your path. This STACKEY.HLP file is different from the file of the same name distributed with STACKEY 2.0. If that old STACKEY.HLP is found, STACKEY will exit with the error message: The file STACKEY.HLP has wrong format or version number. The first help screen is a table of contents and the last one an index. You can search by hitting S or goto a given page with Goto. The help is a useful summary but not really a replacement for reading the manual! On a true monochrome monitor like the original MDA or Hercules card, STACKEY ? will show up in the proper two color attributes. But on a color adapter with monochrome screen (for example, most laptops), the "colors" may make the help invisible or ugly. On such a screen call for help with STACKEY ?m When you exit the help, a screen appears reminding you to register. You can suppress this screen by placing BU$=I paid in your environment. Obviously, having told you the secret, you can do it even if you haven't paid - let your conscience be your guide. I.9 ERRORLEVEL If STACKEY can interpret its command line and does not find the buffer full, it exits with an error level of 0. If there is an error in the command line, the errorlevel is set to 1, if there is a buffer overflow, the errorlevel is 2 and if there is any kind of DOS file error whether due to an invalid path or an open drive door in the {dumpf} utility, the errorlevel is set to 3. You can test the errorlevel in BATch files with the "if errorlevel.." DOS command. All error messages are directed to standard output so you can redirect them to NUL and suppress them if you will handle errors with errorlevel. An example of this can be found in the demonstration BATch file COLOR.BAT. If you enter an illegal parameter value, say "color a", the BATch file responds by Chapter I:INTRODUCTION Page 15 Documentation for STACKEY, Version 3.0 suppressing an error message from STACKEY and giving you one appropriate to the BATch file. How STACKEY responds to an error is controlled by the /t/ and /c/ commands discussed in Chapter III. By default STACKEY will flush its and BIOS's buffers when there is an error but the BATch file will continue. If STACKEY finds that the version number of the resident part does not agree with the version number of the file that you have invoked, it will exit with an errorlevel of 4. Chapter I:INTRODUCTION Page 16 Chapter II:PLACING KEYSTROKES IN THE BUFFER II.1 Stacking text Most often, you will want to stack ordinary alphanumeric data, that is the white letters in the center of the keyboard including the numbers, punctuation, braces, etc. You do this by placing the text within quotes on the command line as in stackey "hello there" or stackey 'hello there' Either single or double quotes can be used. Once a quote occurs on the line, every letter counts until a matching quote OF THE SAME TYPE occurs so to place "Hi!", he said in the stack, you can use stackey '"Hi!", he said' You cannot stack both types of quotes within one string but you can stack strings with both types of quotes by using more than one string. For example, to stack "I can't come", he said use stackey '"I can' "'" 't come", he said' Later, we will describe the command codes SQ and DQ for placing quotes. You could also use: stackey DQ"I can't come"DQ", he said" to stack the above string. While you will mainly stack ASCII characters corresponding to the white keys between quotes, you can also stack an ASCII character such as the graphics characters. STACKEY will simulate the hitting of the A key if you use stackey "A"; it will simulate entering an ASCII code above 128 as if it were entered from the Alt-numeric keypad. II.2 Two-character Codes Many keys on the keyboard do not correspond to any ASCII character. For these and also for a few ASCII characters, STACKEY recognizes special two character codes. The first of these can be a special symbol such as ^, @ or #. Because some programs like CED give special meaning to some of these codes, we have given them alternatives. That is, as the FIRST character in these codes: ~ means the same as ^ ( means the same as @ ) means the same as # * means the same as $ Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 17 Documentation for STACKEY, Version 3.0 This replacement is only effective for the first character, so that you cannot replace ^^ by ~~ but only by ~^. If you need to stack a control-^ and ^ has a special meaning, you will have to use another method like hex codes. These alternatives are not applicable in the color setting commands (i.e. you cannot use [)3 1=4] in place of [#3 1=4]). You stack function keys using one of F,S,C,A (for function, shifted function, control function and alt function) followed by a single digit; 0 stands for 10 and on an enhanced keyboard, - stands for 11 and = for 12 (note the - and = keys are on the numeric row in the eleventh and twelfth place). Thus Ctrl-F10 is stacked with C0 and stackey C2 A3 S5 F0 A- would stack the sequence Ctrl-F2, Alt-F3, Shift-F5, F10, Alt-F11. You may use either upper case or lower case for the key letter f,s,c,a. Do not confuse ^1 (for Control-end) and C1 or @1 (for alt-1) and A1. You can stack the numbers on the numeric keypad with N0,..., N9, the numeric decimal point (shift del) with N. and the grey +, - and * with N+, N- and N*. The BIOS also makes codes for certain Alt key combinations: legal possibilities are alt- followed by any letter or number (top row numbers) or the following special symbols: - =. These can be stacked by preceding the key with @, e.g. stackey @a @2 @- will stack Alt-A followed by Alt-2 followed by Alt-minus. It does not matter if you use upper or lower case letters or if you use @! rather than @1 or @_ rather than @-. Similarly, available control combinations are the letters A-Z, [,\,],^,_,`,@ left arrow, right arrow, home, end, pgup, pgdn, prtsc. These are entered using the ^ (or ~) as the first key. ^A through ^Z will enter those control codes as will ^[, ^\,.... The six keys, on the numeric keypad corresponding to ^Home, etc. can be entered with the corresponding numbers 1,3,4,6,7,9. Thus stackey ^z ^Z ^[ ^6 will stack two control z's, an escape and then ctrl-right arrow (but the "escape" here is entered as if you depressed the control key and then struck [; to enter an escape as if you hit the escape key, use $e or ES as described below). For the letters, ^ may be followed by an upper or lower case letter. For the remaining combinations, only one possibility is allowed. For example, do not Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 18 Documentation for STACKEY, Version 3.0 confuse ^^ and ^6. In the next chapter, we will discuss the PH two character code which stacks a PHony keystroke and the WR two character code which stacks a "Wait for Request". Next, there are two character mnemonics for special key combinations as follows: LA Left Arrow RA Right Arrow UA Up Arrow DA Down Arrow PU Page Up PD Page Down HM Home EN End IN Insert DE Delete G+ Grey plus ("+" will send the top row +; also N+) G- Grey minus ("-" will send the top row -; also N-) G* Grey star ("*" will send the top row *; also N*) CP Control PrtSc PS PrtSc TA or TB Tab ST or BT Shift Tab (=Back Tab) ES Escape (also $e) BS Backspace (also $h) SP Space bar (also " ") CR Enter (carriage return) LF Ctrl-Enter (line feed) FF form feed (^L) (NEW in vers 3.0) DQ The double quote " SQ The single quote ' CB Ctrl-Backspace (NEW in vers 3.0) These codes can be entered in upper or lower case. It is a little known fact that Ctrl-Backspace is a legitimate keystroke that even enters a valid code: ASCII 127 which is . PS for PrtSc will simulate the pressing of the Shift-PrtSc key. If some other program, e.g. PIZAZZ PLUS has taken over that key, it will be called up with PS. ^! will simulate the Ctrl-Break key; for techies, it places an ASCII 0 word in the keyboard buffer and then calls int 1BH. Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 19 Documentation for STACKEY, Version 3.0 STACKEY provides support for combinations understood by the enhanced keyboard or by the BIOS that comes with machines supporting the enhanced keyboard. First, the following Alt-key combinations are allowed: Alt-[ Alt-] Alt-; Alt-' Alt-` Alt-\ Alt-, Alt-. Alt-/. These are entered with the combinations A[ A] A; A' A` A\ A, A. A/. In addition we have the following codes for the enhanced keyboard: Alt-Bksp AB Alt-Enter AC Alt-Esc AE Alt-Tab AT Ctrl-Tab CT The alt-keypad cursor keys (i.e. everything but the 5 key but including Ins and Del) are allowed keys with a enhanced keyboard. You enter them with K followed by the number, e.g. Alt-Left is K4 and Alt-Del is K, The center key (unshifted 5 when numlock isn't on) is K5. In addition we have: Alt-Numpad K / K/ Alt-Numpad K * K* Alt-Numpad K - K- Alt-Numpad K + K+ Alt-Numpad K Enter KC Ctrl- K / ^/ Ctrl- K * ^* Ctrl- K - ^- Ctrl- K + ^+ Ctrl- K Up [8] ^8 Ctrl- K 5 [5] ^5 Ctrl- K Dn [2] ^2 Ctrl- K Ins[0] ^0 Ctrl- K Del[.] ^. Grey Enter GE or GC While most programs do not distinguish them, the enhanced BIOS will distinguish the cursor pad keys and the numeric pad keys. The cursor pad keys are given by Cursor pad End G1 Cursor pad DA G2 Cursor pad PD G3 Cursor pad LA G4 Cursor pad RA G6 Cursor pad Hm G7 Cursor pad UA G8 Cursor pad PU G9 Cursor pad Ins G0 Cursor pad Del G. Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 20 Documentation for STACKEY, Version 3.0 The logic behind the codes is a little stretched. The G is because the keys are grey; the 1,2,3 correspond to the numbers the keys correspond to on the keypad (not the cursor pad!). An appendix to this chapter summarizes all the two character codes in alphabetic order. II.3 Status Toggles You can turn NumLock, etc. on or off from the STACKEY command line. The syntax is +N Turn NumLock on -N Turn NumLock off +C Turn CapsLock on -C Turn CapsLock off +S Turn ScrollLock on -S Turn ScrollLock off +I Turn BIOS insert mode indicator on -I Turn BIOS insert mode indicator off Strictly speaking, the discussion of status toggles does not belong in this chapter since they are handled in real time. That is rather than placing a command in the resident buffer, a command like +N is interpreted and acted on by the non-resident part of STACKEY as soon as it reaches the interpretation of that part of the command line. In this sense, the lock toggles are like utilities and, indeed, they are included also in utilities mode. They continue to be available in two code form for compatibility with earlier versions of STACKEY. BATUTIL will let you read the state of the lock keys from a batch file; see Section IV.9 of the BATUTIL documentation. II.4 Prompt metastrings Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 21 Documentation for STACKEY, Version 3.0 STACKEY supports the full set of metastrings allowed in the DOS PROMPT command as well as the added strings supported by the program SEND.COM of Howard Rumsey and Barry Simon. Specifically: $$ The character "$" $t The time in HH:MM:SS.hh format $d The date in DAY MM-DD-YYYY format e.g. Tue 9-30-1986 $p The current path in full, e.g. C:\BIN\FOO $v The current DOS version $n The current default drive $g The character ">" $l The character "<" $b The character "|" $q The character "=" $h The backspace $e The ESCape $_ CR/LF (i.e. <Enter> followed by Ctrl-<Enter>) $P same as $p in the root dir and as $p\ elsewhere $T time in HHMM format $M month in MM format, e.g. 09 $D day in DD format, eg 03 $Y year in YY format, eg 86 in 1986 and 01 in 2001 $W day of the week in English, e.g. Sunday $E the date in English, e.g. February 18, 1988 $H hour from 00 to 23 $m minute from 00 to 59 There is a difference between upper case and lower case after the $. $W, $E, $M and $m are new with this version. Because of STACKEY's send mode (see Section II.10), you need no longer use the SEND program but can use STACKEY instead. That is, you can use STACKEY to send these codes to standard output. II.5 Decimal and Hex Codes This section deals with advanced features not needed by most users. See Chapter VI for a tutorial on keyboard basics used in this section. You may enter various ASCII key combinations from the keyboard by pressing Alt (or by pressing Alt-Left Shift) and tapping one to three digits on the keypad and then releasing Alt. To stack keystrokes as if entered in this way use \ followed by a decimal number, so Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 22 Documentation for STACKEY, Version 3.0 stackey \104\101\108\108\111 at the DOS command line will cause "hello" to appear on your screen. Keystrokes are stored in the buffer as a set of two hex bytes: a scan code and an ASCII code. You can enter such a combination by typing an X followed by four hex digits. The first two are the scan code and the second pair the ASCII code. For example stackey X2368 X1265 X266C X266C X186F at the DOS command line will cause "hello" to appear on your screen. The hex digits a-f and the letter x can be either upper or lower case. Because they are used internally by STACKEY, the scan codes E0 through FF (which are not legal anyway) are allowed but take the place of two keystrokes in STACKEY's buffer. STACKEY will place in the keyboard buffer whatever combination you tell it to even if it is an illegal combination. DOS will only pay attention to the ASCII half of such combination as will many programs. Some keyboard macro programs will allow such possibilities. For example, KEYWORKS associates Ctrl-Up Arrow (a keystroke not supported by an old style BIOS) with 8448. Stackey X8448 will call up the KEYWORKS macro assigned to Ctrl-Up if one is defined. Some combinations are filtered out by the so-called enhanced keyboard. II.6 Invoking special programs and keystrokes Most TSRs will not pop up by responding to strokes in the keyboard buffer and, as a result, STACKEY cannot invoke them by its usual method. However, when we have special information about a program, we can provide a special routine for that program in particular. We'll discuss those commands, all new in Version 3.0 here. For programs that popup on depression of several shift keys, like SIDEKICK, we can simulate depressing shift keys as discussed in the next section. Here are the special invocation routines: CTRLALT PLUS: CA will invoke the main menu of CTRLALT PLUS so, for example stackey CA"MAP" will print the entire screen even if you are in 43 or 50 line mode. If CTRLALT PLUS is not loaded, you'll get an error message from STACKEY. Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 23 Documentation for STACKEY, Version 3.0 DESQVIEW: Quarterdeck provides two methods for macros to simulate the Desq key which work on different keyboards or BIOS. We have assigned them to D1 and D2. So for example stackey D1"Z" would zoom the current window to full screen. The combination DL is the same as the Desqview learn key. Finally {boot=d} as a utility will invoke a Desqview specific reboot command. CAROUSEL: You can tell Carousel to switch to partition n with Qn where n=1,2,...,9,0 (0 is for partition 10); with Carousel 3.0 or later, you can also use Q- and Q= to switch to partitions 11 and 12.. Thus you might have a sequence of BATch files that successively loads partitions 1,2,.... If you want to load program "foobar" in partition 6, issue the string "hello" followed by F1 to the program and then switch to partition 7, you'd end the batch file for partition 6 with stackey "hello" F1 W36 Q7 foobar The wait command W36 which is discussed in the next chapter (and pauses for 2 seconds) gives the program time to react to the keystrokes before the swap. You may need to adjust the W command for particular applications. TESSERACT PROGRAMS: Tesseract is a library of TSR routines provided by Innovative Data Concepts as a shareware product. If a TSR is written with these routines, you can invoke it with the TE command: stackey te(idstring) will call up the tesseract TSR with the given idstring name. You'll need to consult the documentation that came with your program to find the required id string but here is an example. Suppose you have SWAPSP and want to dial the third entry in your phone book under M. Use stackey TE(SWAPSP15)"PM"DNDNCR The idstring must be exactly eight characters in length. For Tesseract programs that allow multiple hotkeys, each hotkey has an a number. Te(idstring) will call the program with hotkey 0. For other hotkeys, place a /NN after the idstring. Thus, for example stackey te(idstring/23) would invoke the program in question via hotkey 23. CLONE SPEEDUP/SLOWDOWN: Many clones have two speeds adjusted with ^@G+/-. You can simulate this with stackey Z+ Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 24 Documentation for STACKEY, Version 3.0 to speedup and stackey Z- for slowdown. This will not work with all clones. You might object to some of these additions to STACKEY by saying that you don't use CAROUSEL and object to resident memory being taken by the CAROUSEL command. In fact, most of these commands take NO additional memory - they use the inline feature discussed in Section VI.7. II.7 Simulating depression of shift keys Some popups come up when you depress a pair of shift keys. You can simulate the depression of any subset of the four shifts with the command SH which takes two parameters in the form SH(XXX,YY) where XXX is some subset of the letter C,A,L,R for the Control, Alt, Left shift and Right shift respectively and YY is a number from 1 to 65,535. This command simulates depressing the shift keys in question for YY clock ticks. You'll need to experiment with the value of YY depending on the program. We added that parameter because different programs seem to require different values. For example, with a default SIDEKICK Ctrl+Alt, you can invoke the SIDEKICK main menu from within a STACKEY script with stackey SH(CA,1) but invocation of SIDEKICK PLUS requires stackey SH(CA,n) where n is at least 7 or 8 while PRIMETIME (with say C+L as hot key) seems to require stackey SH(CL,10) You'll need to adjust the shift mask to whatever combination you've chosen for your application. For example, if you've changed the SIDEKICK popup to C+L use SH(CL,1) rather than SH(CA,1). II.8 Stacking real time beeps STACKEY scripts can include real time BIOS beeps with the special two key code BE. Beeps are especially useful combined with loops and waits and with jumps (see Section III.2). Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 25 Documentation for STACKEY, Version 3.0 II.9 Popup messages STACKEY scripts can include popup messages that are displayed and take over the machine until the user hits a key. There are two versions depending on whether you want the key hit passed to the underlying application. STACKEY MP(hi there) will display the message "hi there" in a box and pass the keystroke on while STACKEY ME(hi there) would eat the keystroke. These messages are implemented as inline code to avoid having to permanently use resident memory but as a result they take a lot of buffer space. A message takes 156 bytes plus 7 times the length of the message. The default buffer has only 256 bytes so that long messages will require you to load STACKEY with the command (see Sections III.11 and III.12) to take a larger buffer. II.10 Sending to standard output STACKEY places keystrokes in the keyboard buffer. However, you can tell STACKEY to instead send the interpreted material to standard output. You could then redirect this output to a file or the printer. Thus STACKEY provides a replacement for the SEND program of Rumsey and Simon. With their permission, a modified version of the documentation for SEND is provided as an appendix to this chapter. To send output to the standard output, include the special symbol underscore in the STACKEY command line so that STACKEY _"hello"$_ will have the same effect as echo hello Following _ the ONLY allowed codes are: character strings in quotes control codes of the form ^x with x=a,...,z,[,\,],^ or _ (but not ^1, or ^@ etc) prompt metastrings in extended form as discussed above upper ASCII codes in the form \xxx the following two character codes: TA, TB, ES, BS, SP, CR, LF, FF, SQ, BQ, CB Any other codes, even ones normally legitimate in STACKEY (e.g. LA which doesn't have an ASCII equivalent) will produce an error message but only AFTER the codes prior to it on the command line Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 26 Documentation for STACKEY, Version 3.0 are already sent to standard output. The special command _ is only in effect for the line it is issued on; you must include it on each line which you wish to send to standard output. It need not be the first command on the line and a second _ will toggle back to real mode. If you have CED or a similar command line processor that allows synonyms or aliases, we suggest that you use CED SYN send 'stackey _&a' Appendix 1 to Chapter II. Two character codes Here is a list of the two character codes understood by STACKEY (cases where the "second" key is nnnn are shorthand for nnnn being a number): @ followed by letter, number, - or = : Alt-keystrokes ( followed by letter, number, - or = : Alt-keystrokes ^ followed by letter, 1,3,4,6,7,9, [ \ ] ^ _ ` @ : control key combinations 0,2,5,8,.,+,-,*,/ : control key combinations (enhanced only) ! : ^! = Ctrl-Break) ~ followed by letter, 1,3,4,6,7,9, [ \ ] ^ _ @ : control key combinations 0,2,5,8,.,+,-,*,/ : control key combinations (enhanced only) ! : ~! = Ctrl-Break) \ followed by nnn : Decimal ASCII code # followed by nnnn: repeat command (including loops) ) followed by nnnn: same as #nnnn (including loops) $ followed by $ t d p v n g l b q h e _ P T M D Y W E H m : metastrings * followed by $ t d p v n g l b q h e _ P T M D Y W E H m : metastrings + followed by N,S,C,I: turn on locks - followed by N,S,C,I: turn off locks Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 27 Documentation for STACKEY, Version 3.0 : followed by 0 1 2 3 4 5 6 7 8 9: labels (see Section III.2) A followed by number: Alt-function keys - = : Alt-function keys (enhanced keyboard only) [ ] ; ' ` \ , . / : Alt-key combos (enhanced only) B : AB = Alt-Backspace (enhanced only) C : AC = Alt-Enter (enhanced only) E : AE = Alt-Esc (enhanced only) T : AT = Alt-Tab (enhanced only) B followed by E : BE = BIOS BEep S : BS = BackSpace T : BT = BackTab (=Shift-Tab) C followed by number: Ctrl-Function key - = : Ctrl-Function key (enhanced keyboard only) A : CA = invoke CTRLALT PLUS B : CB = Ctrl-Backspace P : CP = Ctrl-Printscr R : CR = Carriage Return T : CT = Ctrl-Tab (enhanced keyboard only) L : Caps-Lock (as hotkey ONLY) D followed by A : DA = Down Arrow E : DE = DElete Q : DQ = Double Quote (i.e. ") 1, 2: D1 or D2 = Invoke Desqview main menu (Desq key) L : DL = Invoke Desqview Learn mode E followed by N : EN = ENd S : ES = EScape F followed by number: unshifted function keys - = : unshifted function keys (enhanced keyboard only) F : FF = Form Feed (Ctrl-L, ASCII 12) G followed by + - *,: Grey Plus, Minus, Star E C : Grey Enter (enhanced keyboard only) 0,1,2,3,4,6,7,8,9,.: Cursor pad keys (enhanced only, see Section II.2) H followed by ! + - * : Hotkeys, see Section III.6; e.g. H!(.,.) M: HM = HoMe Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 28 Documentation for STACKEY, Version 3.0 I followed by N : IN = INsert J followed by 0 1 2 3 4 5 6 7 8 9 : jumps (see Section III.2) K followed by 1,2,3,4,6,7,8,9,0,. : Alt-Keypad (enhanced keyboard only) 5 : Keypad unshifted 5 key (enhanced keyboard only) /,+,-,* : Alt-Grey keys: enhanced keyboard only C : Alt-Grey-Enter (Carriage return, enhanced keyboard only) L followed by A : LA = Left Arrow F : LF = Line Feed (Ctrl-Enter, Ctrl-J, ASCII 10) M followed by P, E : Messages with passing or eating keystroke nnnn : Wait minutes (see Section III.3) N followed by number 0 1 2 3 4 5 6 7 8 9 : Numeric keypad . : Shift-Del (Numeric decimal point) + - * : Grey keys (near keypad) L : NumLock (Hotkeys only) P followed by D : PD = PageDown H : PH = Phony keystroke (see Section III.5) S : PS = Shift-PrintScreen U : PU = PageUp + - : suppress, reenable printscreen key Q followed by number : Carousel partition switch - = : Carousel 3.0 partition switch to partitions 11, 12 R followed by A : RA = Right Arrow S followed by number : Shift Function key - = : Shift Function key (enhanced keyboards only) C : SC(..) = scan ; also SCn,m(..) (see Section III.4) S : SS(..) = scan silently (see Section III.4) H : SH(.,.) = shift mask (see Section II.7) P : SP = SPace Q : SQ = Single Quote (') T : ST = Shift Tab L : Scroll Lock (Hotkey only) R : SysReq (Hotkey only) T followed by A B : TAB Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 29 Documentation for STACKEY, Version 3.0 E : TE = TEsseract callup (see Section II.6) U followed by A : UA = Up Arrow W followed by B : WB = Wait for buffer to be empty (see Section III.3) H K S : Wait for hotkey, any key, specific key (see Section III.7) R : WR = "Wait for Request"; pauses script until a key is requested (see Section III.5) nnn : Wait command (see Section III.3) X followed by nnnn : Hex key (see Section II.5) Z followed by + - : speedup up/down (see Section II.6) Appendix 2 to Chapter II. SENDing to STDOUT The following is a revised version of part of the documentation from SEND by Rumsey and Simon included with permission. It discusses how to use STACKEY's send to standard output mode invoke with an underscore in the STACKEY command line. stackey _<string> is an enhanced version of the ECHO command, ideal for sending escape sequences to the printer or screen. We'll refer to it as SEND. This appendix is primarily a tutorial on ECHO, SEND and redirection of output. You may be used to exploiting ECHO in your batch files but may not be aware that it can be invoked from the DOS command line. If that is the case, type in at the DOS prompt: echo hello You need to also hit <Enter> but we won't keep saying that. The response is amusing but not useful. Next try: echo hello > prn More interesting! Still not so useful but at least if you ever want to use your printer as a typewriter you can do it yourself without needing a BASIC program which does precisely that. Now try echo <Ctrl G> where "<Ctrl G>" means to hit a "control-G", that is to depress the <Ctrl> key and strike the G. With a dot matrix printer try Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 30 Documentation for STACKEY, Version 3.0 echo <Ctrl G> > prn These are decidedly more interesting and you may even think of some uses for them in batch files! Next try turning off your printer, carefully aligning your printer paper, turning your printer back on and typing echo <Ctrl L> > prn <Ctrl L> is the command to send a "top of form" to your printer but if you look carefully you will discover that more than a top of form was sent to the printer. ECHO automatically inserts a carriage return-line feed pair (CR-LF) to the end of any line so your last command first sent a top of form but then advanced the paper one additional line. Annoying, isn't it? Next try: echo <Esc> and echo <Ctrl [> (Escape and Control-[ are the same). This doesn't do what you might hope. <Esc> is interpreted by DOS as a desire on your part to abort the present command and thus you cannot use ECHO at the command line to send an <Esc> to either the screen or your printer. This is unfortunate since ANSI.SYS allows you to do all sorts of nice things if you send the proper "escape sequences" to the screen and many printers can be told to turn on boldface or other neat things by sending escape sequences to them. You can send such sequences to the printer by using some word processors (even EDLIN (ugh!) if you use its <Ctrl V> feature) to make a file with embedded escape characters which you can copy to your printer. But you then need to have these files around and you have files with embedded control characters which you may have trouble printing out or sending over a modem. SEND is intended to remedy these defects of ECHO: 1. It does not terminate line in a CR-LF combination; one can add such a pair "by hand". 2. Typing "stackey _^G" is equivalent (except for the lack of a CR-LF) to typing "echo <Ctrl G>" so one need not fill files with control characters. 3. Typing "stackey _^['E' > prn" will send a <Esc>E to the printer thereby turning on "emphasized" print. In addition, as will be explained, SEND supports the PROMPT $- characters. Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 31 Documentation for STACKEY, Version 3.0 SEND works much like ECHO but if the string to be echoed includes the caret (<Shift 6> which appears as ^), different rules apply. SEND will replace ^a by the character <Ctrl A> (ASCII 1), etc. ^ followed by any letter is replaced by the corresponding control character whether the letter is upper case or lower case. The remaining control characters: ^[=ASCII 27 (1B Hex)=<Esc> ^\=ASCII 28 (1C Hex) ^]=ASCII 29 (1D Hex) ^^=ASCII 30 (1E Hex) ^_=ASCII 31 (1F Hex) may be included by following a caret by the appropriate symbol. Obviously, ^[, the escape character will be used most often. SEND does not automatically terminate any line in a CR-LF (ASCII 13,ASCII 10) pair. Thus typing "echo hello" at the DOS command line will result in two lines on the screen before the next DOS prompt: one line saying hello and the other a blank line. Typing stackey _"hello" will only produce the one line saying hello. If one wants the CR-LF pair, one can insert it "by hand"; thus stackey _"hello"^M^J will have the exact same effect as "echo hello". As we will see in the next section stackey _"hello"$_ is also equivalent. It is important to remember to put in these CR-LF by hand if you are using SEND in a batch file to echo a message to the screen. For example the four line batch file echo off cls stackey _"hello" stackey _"there" will produce the string "hellothere" on one line on the screen while adding $_ after "hello" or even replacing the last two lines by stackey _"hello"$_"there" will produce a two line message with one word on each line. You may find BATUTIL better to use for echoing messages to the screen. SEND supports the $-metastring conventions of the DOS PROMPT In accordance with the general STACKEY metastring translation, a special interpretation is made if the $ is immediately followed by one of the following: Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 32 Documentation for STACKEY, Version 3.0 $ g,l,b,q h,_,e t,d,p,v,n P,M,D,Y,T,W,E,H,m The case of the letter following $ is significant. The metastrings are described in Section II.4. $g,$l,$b,$q correspond to the characters >,<,|,= respectively. You can use the ordinary "=" in a line starting with "stackey _", but you CANNOT type >,< or | in such a line since DOS will interpret these symbols as redirection or piping. You must use the $-metastring instead. For example, if you use FANSI-CONSOLE and want to send the ANSI code "<esc>[>4h" typing the command stackey _^["[">4h will make a file "4h" with two bytes in it while stackey _^["["$g"4h" will do exactly what you want. $h is equivalent to ^H, ASCII 8, the "backspace" which, if sent to the screen, moves the cursor back one space. Like the $h of the Rumsey-Simon SEND program, the Stackey SEND $h does not erases the previous character. Thus stackey _"a"$h will show an "a" on the screen and stackey _"a"$h"b" will show a "b" on the screen since the cursor will backspace one unit and the b will overwrite the a. But the command stackey _"a"$h"b">file will produce a file with three bytes: a,<Ctrl H>,b. $t and $d send the time and date in the form returned by the TIME and DATE commands. Thus the time will appear as HH:MM:SS:hh. If you only want the hours and minutes to appear on the screen, you can use stackey _$t$h$h$h$h$h$h" " (There are six spaces after the final $h and they are important!). One of the most useful things you can do with SEND is exploit the ANSI.SYS device driver. ANSI.SYS is a file that comes with DOS (version 2.0 and higher). You need to load it in your CONFIG.SYS file. If you already have such a file, add a line device=ansi.sys to it and place ANSI.SYS in your root directory or, even better, Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 33 Documentation for STACKEY, Version 3.0 place ANSI.SYS in a directory, say GEORGE and add a line device=\george\ansi.sys to your CONFIG.SYS file. If you don't have such a file, add one to your root directory with one of the above lines and while you're at it, you should probably add files=20 and buffers=15 (unless the memory of your computer is very limited). You can read about the syntax of the ANSI.SYS commands in the DOS 2.0 manual or the DOS 3.0 technical reference. ANSI.SYS can be used to control screen colors on a color monitor, and attributes on a monochrome monitor. For example, stackey _$e"[1;31;42m" will produce an unpleasant screen while stackey _$e"[1;33;44m" will be more to your liking. Actually, it is best to set your screen colors using the DOS PROMPT command. You can use SEND to call up colors and attributes for effect in batch files. BATUTIL will generally give you better color control. You can also use SEND and ANSI.SYS to redefine keys in DOS. DOS, following UNIX, supports two virtual devices called "standard input" (stdin) and "standard output" (stdout). Programs rather than sending their output to a specific device like the screen or printer can send them to stdout and similarly rather than take input from a specific device, they can take it from stdin. If not specified otherwise, stdout is sent to the currently active screen and stdout is taken from the keyboard (i.e. the DOS command line). However, one can redirect stdout to another device. For this to work the program MUST send its output to stdout. For example, the "main output" of the COPY command goes not to stdout but to the second file specified on the command line; only the message that COPY sends goes to stdout. Thus "copy somefile prn" will print a file on your printer, but "copy somefile > prn" will print the error message File cannot be copied onto itself 0 File(s) copied If a program takes its input from stdin, that too can be redirected. One redirects output using the symbol ">" and input using "<". STACKEY's SEND sends its output to stdout and that can be redirected, for example to a printer or file. It takes its input from the keyboard rather than from stdin so one cannot redirect Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 34 Documentation for STACKEY, Version 3.0 input. SEND can also be used for sending control sequences to your printer. Unfortunately, the sequences to be used tend to be highly dependent on the brand and/or model of your printer. The simplest example is a one line batch file entitled tf.bat stackey _^L> prn Typing tf at the DOS command line will cause your printer to eject a page. You might even want to define a function key to mean tf. A more sophisticated example is the five line batch file BOLDPRN.BAT, for IBM graphics printers: echo off cls stackey _$e"E"$e"G">prn copy %1 prn stackey _$e"F"$e"H">prn Thus typing "boldprn MYFILE" will print a boldface (=emphasized and doublestrike) copy of myfile on your printer. You might consider adding the line: stackey _$P"%1 printed on "$d>prn before the "copy..." line. A particularly useful way of sending printer codes is to use send in CED synonyms if you have the program CED or in 4DOS aliases. Chapter II:PLACING KEYSTROKES IN THE BUFFER Page 35 Chapter III:COMMANDS TO THE RESIDENT PORTION III.1 Overview There are various ways that you can pass commands to the resident part of STACKEY. Seven discussed here: delays, repeats, the two types of scan, WB, WR and PH, and the color commands [],L,P discussed in the next chapter are just stored as special "keystrokes" in STACKEY's buffer so it processes them as they are reached. The command to flush the buffer is acted on immediately and the command to quit which we discuss below is properly speaking not a command to the resident part but to the command line interpreter. The commands /Bxxxx/ and /Rxxxx/ are commands to the part of the program that loads the resident part and strictly speaking not commands to the resident part. Another set of commands set certain flags (toggles) which the resident part keeps and effect how the command line is interpreted. Thus, in a certain sense these are commands to the interpreter but ones which are kept track of in the resident part. The toggles come in pairs: /T/ and /N/ turn test mode on and off (default is off) /S/, /P/ and /I/ choose among smart, patient and impatient processing (the default is smart) /C/ and /D/ turn continue mode on and off (default is off) III.2 Repeats and loops If you need to stack ten left arrows, you will not appreciate having to type LA ten times (nor do you want to take that much space in STACKEY's buffer). Thus STACKEY allows a key repeat command. # followed by a decimal number from 1 to 255 will result in the next key stroke being repeated that number of times, so stackey #7 F1 will stack 7 F1's while stackey #7 "hello" will stack hhhhhhhello. Trying to repeat a repeat command (as in #2#4) or a delay (as in #2W6) is not recommended. Indeed, following a repeat command with anything that isn't a keystroke will produce unexpected effects. Sometime, you will want to repeat a set of 'keystrokes' multiple times (loop) and for this you need only use # followed by a number followed by [, the commands and ] so for example stackey #3["hello"] Chapter III:COMMANDS TO THE RESIDENT PORTION Page 36 Documentation for STACKEY, Version 3.0 would enter "hellohellohello". You might try stackey #10[be w5] in a batch file which will produce 10 beeps and which would notify you from another room. We recommend that repeats also by handled as loops; the repeat command is only included for compatibility with earleir versions. Future versions of STACKEY may remove support for the # command iwht the [..] required by loops. In addition STACKEY supports labels for use in external com files we might supply (or you if you have programming background) and a single jump command. Taking a leaf from batch file labels, STACKEY labels are :0 through :9 and j7 would unconditionally jump to :7 if it exists. Thus stackey :0 be w5 j0 would beep forever; more properly, it will beep until you flush the buffer with the STACKEY hotkey AL! As an example of how to use jumps look at the sample external file sample.msg and try STACKEY w20 ex(sample.msg) :1 be 'yes' j0 :2'no' This is described in detail in Section VI.9. III.3 Delays There will be times that an application program will flush the keyboard buffer before asking for a keystroke. This is to force you to respond or to make sure the response is not accidental. If you just stack the strokes you want, they will get flushed out. A famous example of this is 1-2-3. STACKEY provides several ways to try to get around this problem: delays, two kinds of phony keystrokes and patient processing. STACKEY allows you to place a delay into the stack so that when those strokes are gotten to, STACKEY will pause before inserting them in the buffer. You specify the time to pause in 55 millisecond units (clock ticks; there are about 18.2 per second). This is done with the command Wn where n is from 1 to 65535 so stackey W36 ES will Wait about 2 seconds before it puts an <Esc> into the buffer. You can use either w or W. 65535 ticks is about one hour. If you need a longer wait, you can stack multiple waits or use a loop. New in STACKEY 3.0 is the M command. M is followed by an integer n from 1 to 65535 and delays for n minutes where a "minute" is really 1092 clock ticks. Each hour of delay via the M command takes 4 Chapter III:COMMANDS TO THE RESIDENT PORTION Page 37 Documentation for STACKEY, Version 3.0 bytes of buffer. A delay of a week would require about 320 keystrokes more than the default 128. You should distinguish between what we call delays and what we call waits. For consistency with Version 1.0 we still use the letter W for delays. Delays are set with the command Wnnn while waits are set with the {WAIT=nnn} utilities mode command. Delays are commands to the resident part of STACKEY telling it to delay placing strokes in BIOS' buffer (or setting colors) while operating in the background as some underlying program is running. Waits are commands to the foreground part of STACKEY telling it to loop and control all machine resources (although you can call up a program like SIDEKICK) until the wait period is over. Thus waits will be useful only in rather special circumstances like demonstration BATch files while delays will get used more often. Delays are implemented as they are reached by the resident part of STACKEY. The resident portion checks to see if BIOS' buffer is empty and only starts counting the delay if it is empty. Thus, a command like stackey "1"W36"2" will separate the two keystrokes by 36 ticks as they are processed by your application program and not by when they happen to be placed in the keyboard buffer. In distinction to this, STACKEY implements waits as soon as they are reached in its interpretation of the command line. Unlike other commands which look for an empty keyboard buffer, delays are not effected by whether you are in impatient, patient or smart mode. There are times you might want to pause a STACKEY script until the BIOS buffer is empty. W1 will almost do that although it will delay for an extra 1 tick. If you just want such a pause, use WB (Wait for Buffer). III.4 Scanning There are times that you will want to pause STACKEY until your application program takes a certain action. If the application program announces that action with a message on the screen, then the SCan command is exactly what you want. You can scan for either a "string" at a particular location on the screen for which the syntax is SCn,m("string") Chapter III:COMMANDS TO THE RESIDENT PORTION Page 38 Documentation for STACKEY, Version 3.0 or you can scan for the "string" immediately preceeding the cursor position for which the syntax is SC("string") Do NOT place quotes around the string. SC may be upper or lower case. n,m are the row and column that you want to scan at. The string will need to START at position n,m. For example stackey SC2,7(hello)"there" would pause stackey (while your foreground application continues to work) until the string hello appeared in row 2 columns 7-11 and at that point, "there" would be entered through the keyboard. When STACKEY runs into such a command in a script it pauses playback in the script while remaining in the background. To warn you that this has happened, it will blink the character at the current cursor position for a plain SC command or at position n,m for an SCn,m command. If you do not want this blinking you can tell STACKEY to scan silently (i.e. without the blink) by using SS rather than SC. Be especially careful of SS, since, if the scanned element doesn't occur, you may forget what has happened and think that STACKEY is broken since further scripts are placed in the buffer but no action occurs since STACKEY is patiently scanning. There are three ways to stop a STACKEY scan. First at the DOS command line, you can issue stackey ! which flushes the STACKEY buffer as described in Section III.10 below. Secondly, you can use one of two STACKEY hotkeys. These are described in Section III.6 below. One hot key flushes the STACKEY buffer; the other resumes playback immediately following the scan command. In general, it is better not to search for too long a string. Ideally, you want a string of 2 or 3 characters. Here is a real life example of how to use STACKEY's scan command. Magellan takes some time to read all your hard disks. If you load it in a Carousel partition, you'd like it to fully load in an initial batch command after which you switch partitions. While loading, Magellan displays the word WAIT in the upper right corner of the screen. When finished it changes to LIST. The following will do what you'd want: stackey W54 SC1,76(LI) W25 q6 mg Chapter III:COMMANDS TO THE RESIDENT PORTION Page 39 Documentation for STACKEY, Version 3.0 if placed in a batch file where you want to go to Carousel partition 6 next. III.5 The phony keystrokes Two other tools that STACKEY provides to cope with programs that flush their buffers after loading or even before accepting any input are the PHony keystroke stacked with the two key code PH as in stackey PH"hello" and the WR (wait for request) keystroke as in stackey WR"hello" When the resident part reaches such a phony keystroke, it stops processing the buffer until the underlying program makes any call to int 16. This is the way that programs normally check for and process keystrokes. The first time that a program asks if there are any keystrokes in the buffer, it will be told no which means that it won't bother to flush the buffer. As soon as an int 16 call is processed, STACKEY sets itself to continue the placing of strokes and processing of color commands. PH will not always work the way that you would like because a program may use a different strategy. If PH didn't work for you in version 2.0, try WR since we have changed the strategy in a way that we feel is likely to be more successful. For compatibility with programs fro which PH worked, we have kept the version 2.0 PH but we believe that WR is more likely to overcome the buffer flushers. If you are having problems with a program flushing some of STACKEY's keystrokes, you can try PH but if that doesn't work, you can consider delays and/or using patient processing; see the discussion of erase *.* in the Usage notes. Alas, DOS tends to issue int 16 calls while it loads programs so that it will eat WRs. You may want to find a harmless keystroke like Backspace and try stackey BS WR .... when loading a program. III.6 Hotkeys STACKEY provides four hotkeys to enable you to communicate with it from within application. Since you can change what keys call them, we give a table which includes their two letter code and function: Chapter III:COMMANDS TO THE RESIDENT PORTION Page 40 Documentation for STACKEY, Version 3.0 Code Function Default ──────────────────────────────────── H! Flush buffer AL "!" H* Flush scan AL G* H- Pause script AL G- H+ Resume script AL G+ H! flushes the stackey and BIOS buffers, H* only has an effect when processing has stopped because of a scan (SC), a silent scan (SS), a keyboard scan (WS) as described in the next section or an H- pause. It flushes the scan command from the buffer and resumes operation on the next "keystroke". H+ resumes playback of a script that has been paused by an H- or by the WH command that we'll discuss in the next section. Pause here just means stopping the background STACKEY playback; your foreground program will continue to run. The actual hotkeys that cause an action are described by two pieces of data: the required shift pattern given as a subset of ACLR (see the description of the SH command in Section II.7) and a key. The key is described by one of the following: a one character string in quotes like "a", "A" or "+" the following two character code that invokes normal STACKEY keystrokes: F1,...,F0,F-,F=, SQ, DQ, N* or G*, N+ or G+, N- or G-, PS, N0,...,N9, CR, UA, DA, LA, RA, ES, BS, DE, IN, PD, PU, TB, TA, EN, HM special two character codes for this purpose only: CL for CapsLock, SL for ScrollLock, NL for NumLock and SR for SysReq STACKEY then uses the key associated to that single stroke and combines it with the given shift combination. Thus "A" and "a" are the same for this purpose and PU and N9 are also the same. Thus to say that AL "!" is the default hotkey for H! means that the buffer is flushed by pressing Alt+LShift+the key marked 1/!. This is the same as AL "1". You can change the hotkeys in STACKEY at any time including the initial loading by using the syntax stackey HX(YY,Z) where X is one of !,*,+ or -, YY is a subset of CALR and Z a key indicator. For example, H+(CL,"+") would make Ctrl+LShift+top row plus the combination to resume playback, H!(,SR) would make the unshifted SysReq key flush the buffer and the following would restore all hotkeys to their defaults if you changed them Chapter III:COMMANDS TO THE RESIDENT PORTION Page 41 Documentation for STACKEY, Version 3.0 stackey H!(AL,"!") H*(AL,G*) H+(AL,G+) H-(AL,G-) STACKEY uses int 9 to interpret hotkeys, that is, it directly reads the keyboard. Thus you cannot include STACKEY hotkeys in keyboard macros and if you have used a mapping program and changed keytops, you'll probably find that STACKEY calls the original "A" key "a" and not the mapped key to which you've transferred the "A" keytop. STACKEY traps its hotkeys and does not pass them on. Alas, most keyboards other than IBM keyboards have some combinations of multiple shifts plus letters which are dead combinations in that the keyboard will not issue any interrupt in response to them. In particular, on some Northgate keyboards, the AL! default flush combination is dead. III.7 Pauses for keystrokes STACKEY will pause its playback (while not affecting the foreground program) until a particular key is struck with three different commands: WK waits for any key to be struck or released WH waits for the H+ hotkey to be hit; this is the same as hitting the H- hotkey WS(XX,Y) waits and scans the keyboard for a particular combination The keyboard scan uses the same conventions as hotkeys so that stackey WS(L,"a")"hello" will pause stackey playback until LShift+"a" is struck. The hotkeys are eaten by STACKEY and not passed on to the underlying application program. III.8 Multiple STACKEY commands If you are just stacking keystrokes, you can place strokes on more than one line of a BATch file; that is there is no difference in the effect of stackey "hello there" and stackey "hello " stackey "there" Chapter III:COMMANDS TO THE RESIDENT PORTION Page 42 Documentation for STACKEY, Version 3.0 or even stackey "hello ther" stackey "e" Thus you can use separate lines for more readability or to overcome the length of DOS lines. Of course with two commands, stackey will load twice but it is so small that even on a floppy based system, it should be in DOS' buffers and that won't slow things down. On a floppy based system, extra lines in a BATch file will slow things down. Because utilities mode commands are processed in real time, there is a subtle difference between how multiple lines are processed when there are utilities commands on the second line but for virtually all situations this distinction won't matter. Here is a special situation where it will: You start on a monochrome monitor on a dual monitor system and issue stackey L4 {mon=c} and the monitor switch will take place before the color change. But with stackey L4 stackey {mon=c} the attempted color change takes place before switching monitors and so have no effect. Of course if you want to use two lines just reverse the order! III.9 Patient, impatient and smart processing STACKEY must cope with the fact that BIOS only provides a keyboard buffer of 15 strokes. You may have software which enlarges this buffer for your actual typing but STACKEY cannot know about this. Thus STACKEY keeps its own internal buffer. When there are keystrokes waiting in this buffer, STACKEY checks 18.2 times a second to see the state of BIOS' buffer. Depending on the command and the mode you set, STACKEY will either check to see if the buffer is empty before placing any strokes in or will at least check whether there is room before placing strokes in. STACKEY's inpatient mode, places as many strokes in the buffer as will fit. Its patient mode will place no strokes in the buffer unless the BIOS buffer is completely empty in which case only one stroke or command will be acted upon. STACKEY, by default, treats keystrokes impatiently while treating certain commands patiently, i.e. not implementing them until BIOS' stack is empty. A typical example is a color change. Chapter III:COMMANDS TO THE RESIDENT PORTION Page 43 Documentation for STACKEY, Version 3.0 Temporary color changes are wiped out by a change of video mode so, if you are loading a program which switches into graphics mode, you want to be sure that the colors do not change until after the program has loaded and changed modes. You can do this by experimenting with delay length, but if you also want to send keystrokes to the program, the default processing method is better. By preceding the color change command with some keystrokes, you can be sure that the color command will not be acted upon until the application program has loaded and no delay is necessary. We call this default mode smart processing. Smart processing effects the following commands which are all discussed in later chapters: Ln,Pn,+/-B and [...] (but not commands that change permanent palettes, i.e. [#...] commands). It also effects the PS command discussed in the last chapter (PrtSc). The Wn delay command is always handled smartly whether or not you have turned smart processing on or not. There are times that you will NOT want smart processing. For example, in the demonstration BATch files CGACOLOR.BAT and COLOR.BAT, there are commands to change colors for illustration purposes. If smart processing were in effect, the color changes would stop if the user happens to hit a key by mistake. For this reason there are commands to force impatient processing for all situations except Wnn commands and to turn smart processing back on. stackey /i/ turns impatient processing on and stackey /s/ turns smart processing back on. The /i/ and /s/ must be the first thing on the line and we urge you to take this change seriously by placing only this single command on a line. Either S or s and either I or i are allowed. S obviously stands for smart; I stands for idiotic or impatient but not for intelligent. Delays (the W command) are always treated patiently even if impatient mode is on. If you are in a situation where you wish that the Wn command were impatient, you may find that the {wait=n} command is what you want. When smart processing is turned off, color commands are acted on as soon as they are reached. This may not be immediately if BIOS' buffer completely fills and there are keystrokes ahead of the color command waiting to be put into BIOS' buffer. Chapter III:COMMANDS TO THE RESIDENT PORTION Page 44 Documentation for STACKEY, Version 3.0 Patient mode where all keystrokes are treated patiently is turned on with stackey /p/ Since it slows down keystroke entry to only 18 per second (not much better than a good typist), you'll only want to use it under special circumstances. Here is a typical example: the shareware fancy printing program BRADFORD opens by asking you the name of the file that you want to print followed by several questions about settings that you'll probably want to always answer the same way. This is clearly a place to use STACKEY in a BATch file with %1 as part of the stacked material (to be replaced by the file name). Alas, BRADFORD completely flushes BIOS' buffer before reading each and every keystroke so if STACKEY were in smart mode, all the strokes that you carefully arranged to have entered would be flushed! But patient mode works beautifully - you need to do something so that the first stroke isn't entered too soon. One could experiment with Wnn's but here PH works fine so the BATch file might read: stackey /p/ PH"%1"CR <more stuff> bradford stackey /s/ III.10 Flushing and Quitting As long as there is room in STACKEY's internal buffer, you can stack additional keystrokes with a second STACKEY command, as we explained above. If you enter a ! in a STACKEY command line, then STACKEY will flush its buffer, i.e. clear it and reset its internal pointer to the bottom of the stack. It will also flush BIOS' buffer. If you have an extended buffer provided by some other program, STACKEY will not flush that. Thus, the BATch file: stackey "abcdefghij1234567890" stackey ! will display nothing on the screen when it is over. If STACKEY finds an ! on its command line, the interpreter continues processing after flushing the buffer so you may place other commands on the line following a !. If STACKEY finds a ; (lower case only) in its command line, it will quit interpreting the command line at that point. This is to allow you to place comments in your BATch files. Semi-colons Chapter III:COMMANDS TO THE RESIDENT PORTION Page 45 Documentation for STACKEY, Version 3.0 inside {} or [] are interpreted as delimiters and not as comment indicators. III.11 Enlarging the Buffer STACKEY will use a default buffer allowing 128 keystrokes to be stacked. The first time that STACKEY is loaded, you can tell it to set aside a larger buffer by including the letter B (or b; stands for Buffer) and the buffer size in number of strokes between slashes so stackey /B2000/"hello there" as an initial command would set aside a 2000 stroke buffer and then stack "hello there" in that buffer. Any number between 1 and 10000 is allowed for the buffer size. The size is given in keystrokes; each keystroke requires two bytes of resident memory so a buffer size of 2128 would increase the amount of RAM taken by the resident portion of STACKEY by 4000 bytes. If you need more than 10000 keystrokes or want to load STACKEY in high DOS memory, use the SKRES program described in the next section. Once STACKEY is loaded it cannot change the size of the buffer in the loaded copy. Further calls to STACKEY find the resident copy and use it and do not load another copy. If a copy is loaded and /Bxxxx/ appears on the command line, you will get an error message. You can however choose to load a new copy of STACKEY with any buffer size you want. The old copy remains in memory but will be unused; STACKEY always finds the last copy loaded in memory. You tell STACKEY to load a new copy by placing an R (or r; stands for Reload) after the first / in the buffer size command so stackey /R2000/"hello there" will load a new copy of STACKEY with a 2000 stroke buffer. Even if STACKEY has not already been loaded, you can load it with the /R.../ command. Both the /B.../ and the /R.../ commands must be the first thing on the command line after the name STACKEY; this is also true of the other /.../ commands that we will describe. You cannot place more than one set of /'s on a line. However, you can place multiple /../ commands within one set of brackets such as stackey /R2000 T I/ which would load a new copy and turn on testing mode and off smart mode in this new copy (of course, stackey /T I R2000/ will first Chapter III:COMMANDS TO THE RESIDENT PORTION Page 46 Documentation for STACKEY, Version 3.0 change the modes in the old copy and then load the new copy, probably not what you wanted). If STACKEY cannot fit the characters on the command line into it internal buffer, it prints an error message, showing you where the overflow occurs, beeps and places NO new characters in the buffer. The beep is sent to standard output and so it may be redirected to nul. The errorlevel is set to 2. In the default setting STACKEY will also flush the buffer when there is an error; see the discussion of continue mode below. III.12 The SKRES program A separate program is provided whose sole purpose is to load STACKEY the first time. It does not do additional command line processing so that you cannot include your first set of STACKEY commands. It is intended for use in two circumstances: when you want a buffer larger than 10,000 keystrokes and when loading in a small area of high DOS memory. STACKEY itself will only load with a buffer of up to 10,000 keystrokes (20,000 bytes). SKRES allows up to 30,000 keystrokes (60,000 bytes). If you wonder how one could want a buffer over 10,000 strokes, so do we but we received the request from some users with large FILEKEY scripts. The syntax is identical to that for STACKEY so that, for example skres /B30000/ would load with the maximal buffer size. Users of 386max, QEMM, Move 'em, QRAM and other programs that let you load TSRs into nooks and crannies of free address space in the region between 640K and 1 meg, often want to load STACKEY into a small space. Even though STACKEY's resident part takes under 1.3K, loading the program and initializing it takes over 23K and you'll need that much free to load STACKEY. SKRES leaves out the interpreter precisely to make it as small as possible so we recommend using it if you wish to load STACKEY's resident part into high memory. If skres is used, the only allowed command on its command line is /Bxxxx/. Chapter III:COMMANDS TO THE RESIDENT PORTION Page 47 Documentation for STACKEY, Version 3.0 III.13 Test mode STACKEY is a powerful program. For that reason, especially while debugging a BATch file, you may want to abort a BATch file after STACKEY displays an error message. STACKEY has a special "test mode" which you invoke with stackey /T/ Whenever, STACKEY issues an error message, it checks whether test mode is on. If it is, it will pause processing of the BATch file and issue the message STACKEY: Abort (Y/N)? If you answer Y, STACKEY will place a ^C in BIOS' buffer which will normally cause the BATch file to ask Terminate batch job (Y/N)? and Y will stop the BATch file. This message from STACKEY cannot be redirected. To be sure that you are the one to answer the Abort message, STACKEY flushes both BIOS' buffer and its own. To turn off test mode and restore normal processing issue stackey /N/ Some users may prefer to always use test mode. While /N/ and /T/ need only be the first commands on the line, we suggest that you make them the only commands on the line. In order for ^C to stop the BATch file and ask "Terminate batch job (Y/N)?", you must have Break on. For this reason, if STACKEY is in testing mode, you respond Y to "STACKEY: Abort (Y/N)?" and Break is off, STACKEY will turn Break on and tell you that it has done so. III.14 Continue mode If there is an error in STACKEY's command line but there are keystrokes pending then STACKEY, by default, assumes that you want the current processing aborted and it flushes both its buffer and BIOS' buffer. If for some reason, you don't want this done, you can issue the command stackey /c/ (C or c for continue). To restore the default setting use stackey /d/ Chapter III:COMMANDS TO THE RESIDENT PORTION Page 48 Documentation for STACKEY, Version 3.0 (D or d for discontinue). When continue mode is on, not only will what is in STACKEY's buffer at the time of the erroneous line still be processed but the parts of the line up to the error are also processed. If test mode is on, STACKEY flushes the buffer automatically before displaying its "Abort(Y/N)?" message; thus, if testing mode is on, the setting of C/D will be overridden. III.15 Pushing, popping and querying the flags STACKEY uses several flags to keep track of the current state of the following toggles: Normal vs. Test mode, Smart vs. Impatient vs Patient processing, Continue vs. Discontinue on error. You can save this combined state and the with stackey /u/ and restore from the last command of this type with stackey /o/ These commands pUsh and pOp the STACKEY flags. The initial value of the pushed flags is the default and only one set is pushed so that popping does not change the pushed values. These commands are included for you to employ if you make demonstration BATch files with STACKEY. You may want to turn off smart processing but you can't just restore smart processing since the user may have turned it off. As a courtesy, if you are making demonstration BATch files to be used by others and you change the STACKEY flags, please push them at the start and pop them at the end. Since we can find no reason for you to change the hotkeys, we don't save their state in a push. If you want to use a WH command but are unsure what to tell the user to push to resume, use WS instead. At any time, the command stackey /?/ will send the version number, the current values of the STACKEY flags, the four current hotkeys and the buffer size of the active copy to standard output. The state of the hotkeys output takes the form Hotkeys H!, H*, H+, H- are: (LA,"!") (LA,n*) (LA,n+) (LA,n-) where the indication is (set of shifts, keyname). Be forewarned that one particular keyname is picked when there are several e.g. TB rather than TA. Chapter III:COMMANDS TO THE RESIDENT PORTION Page 49 Chapter IV:SETTING COLORS IV.1 Color Basics: Introduction Color monitors on an IBM PC provide graphics as well as colors but unfortunately the attitude of the authors of many graphics programs seems to be that you can have any two colors you want so long as you want white on black. STACKEY has tools which allow you to set colors on a color monitor even for programs that set no colors or set colors that you don't like. There are separate tools for the IBM Color Graphics Adapter (CGA) and the Enhanced Graphics Adapter (EGA). The EGA compatible modes of the VGA are supported but the new 256 color VGA modes are not supported. CGA users should read through the section on SETTING COLORS ON THE CGA and can then skip to the next chapter. EGA users can skip the section on SETTING COLORS ON THE CGA but should read all the sections on color basics. Special support is provided for users of Ultravision. IV.2 Color Basics: Graphics modes The amount of color you can have depends not only on the adapter but also on the particular mode. The CGA supports essentially three modes: Text mode (mode 3 for 80 columns) CGA Medium Resolution mode (mode 4) CGA High Resolution mode (mode 6) Mode 3 allows 16 background colors and (normally) 8 foreground colors. Mode 4 has a resolution of 320x200 and allows four colors, a background color which can be from among 16 possible choices and one of two palettes of three colors. Mode 6 has a resolution of 640x200 and two colors, a black background and a foreground chosen from among 16 choices. The EGA supports two additional modes: EGA medium resolution (mode 14) EGA high resolution (mode 16) Each mode is a sixteen color mode (at least if your EGA card has a full 256K of memory). Mode 14 has resolution of 640x200 just like mode 6 (so why use mode 6? Simple, if you're the programmer; you can write one program for the CGA and the EGA. If you're the user, there is no reason to want mode 6 over mode 14 except if you like programs written by lazy programmers!). Mode 16 has the full 640x350 resolution supported by the EGA. The VGA supports two modes more than the EGA: 256 color medium resolution (mode 19) Chapter IV:SETTING COLORS page 50 Documentation for STACKEY, Version 2.0 VGA high resolution (mode 18) VGA high resolution is 640x480. Mode 19 is much lower resolution (320x200) but has 256 colors out of a palette of 262,144 rather than the 16 colors out of 64 allowed by the EGA or the other VGA modes. There is a tradeoff between number of colors and apparent resolution. Television makers have known for a long time that many colors can fool the viewer into thinking the resolution is higher than it actually is. Even though it is low resolution, graphics in mode 19 can be quite striking. Various so called superVGA cards, most notably those from Paradise and Video7 support 800x600 resolution and 256 colors with 640x480. Alas there is not yet a common standard so STACKEY does not have support for these superVGA modes. Actually, we have not included in this discussion the 40 column text mode (mode 1 supported on the CGA and the EGA) nor the 16 color 320x200 EGA mode (mode 13) nor the two color graphic modes 15 and 17 which are rarely used. If you have the full 256K memory and an enhanced color display, you can choose these 16 colors from among an array of 64. Of this, more later. Borders further complicate the possibilities. The CGA allows a border in text mode. While the EGA does also, the only description of the text mode border is wimpy. In mode 4 on the CGA, the border is the same color as the background. On the EGA, you can specify a border color differently from the background and it is a full border. The same is true in mode 14. It is important to realize that a mode change will reset the colors to their default values (this is not always quite true on the EGA/VGA; see the discussion of permanent colors later). IV.3 Color Basics: CGA color choices The sixteen colors on the CGA are numbered as follows: 0(0H) Black 8(8H)I Dark Grey 1(1H) B Blue 9(9H)I B Intense Blue 2(2H) G Green 10(AH)I G Intense Green 3(3H) GB Cyan 11(BH)I GB Intense Cyan 4(4H) R Red 12(CH)IR Intense Red Chapter IV:SETTING COLORS page 51 Documentation for STACKEY, Version 2.0 5(5H) R B Magenta 13(DH)IR B Intense Magenta 6(6H) RG Brown 14(EH)IRG Yellow 7(7H) RGB Light Grey 15(FH)IRGB White After the decimal number, we give its hex value. The letters I,R,G,B describe the color in terms of 4 basic on/off switches determining the color: the Intensity, Red, Green and Blue switches. Thus cyan is a mix of Green and Blue. The intensity bit is a misnomer in that Dark Grey is not what one would think of as "Intense Black"; I is really a brightness and so an intenseness of light. There is a connection between the IRGB switches and the color number. If B has the value 1, G the value 2, R the value 4 and I the value 8, then the CGA color value is arrived at by adding the values of the switches that are on. Thus intense magenta which is IRB is color number 8+4+1=13. IV.4 Setting colors on the CGA CGA colors are set using STACKEY with two commands the L (for coLor) and the P for Palette command. The P command only has effect in mode 4 (CGA medium resolution graphics) while the L command has a effect in any mode. It is IMPORTANT that the color command only get issued by STACKEY after the mode has changed and to do this you may have to add waits and experiment with their lengths. For example, if you load a program which switches to mode 4 and want a red background, the command stackey L4 in a BATch file immediately before the line loading the program will not work. Rather, the L4 command will get issued by the resident portion of STACKEY immediately and change the border to red while you are still in text mode. The graphics program will then load and change modes thereby wiping out the color change you issued. Instead, you should try stackey W36L4 which will tell the resident portion of STACKEY to wait roughly 2 seconds before issuing the color change command. While this wait is going on, control will be passed to the application which can load and change modes. If the W36 is a long enough wait, the color change will only take effect after the application program has changed modes. But you will have to experiment to see how long a wait you need to put in. If you are also stacking keystrokes which will only be processed by the application program after it changes modes, you do Chapter IV:SETTING COLORS page 52 Documentation for STACKEY, Version 2.0 not need to stack a wait, for STACKEY only acts on the L command if the keyboard buffer is empty, that is if there are no strokes waiting for a program to process. Even if you don't want to stack keystrokes, it may be easier to stack a harmless keystroke (like backspace) rather than experiment with delays of appropriate length. Depending on the program, you may be able to use PH or WR as the harmless keystroke. In BATch files, you may want to turn smart processing (reading the buffer to check that it is empty before issuing a color command) off using the /i/ command discussed in Chapter III. Be sure to turn smart processing back on with /s/. What the coLor command does depends on mode: In text mode (modes 1 and 3) Ln sets the border color to n In medium resolution mode (mode 4) Ln sets the background to color n In high resolution node (mode 6) Ln sets the foreground color to color n If this choice seems odd, it is essentially the single globally chosen color available in each mode. Each mode allows 16 choices for n. STACKEY will accept any integer value and compute n modulo 16. The demonstration BATch file CGACOLOR.BAT will illustrate the abilities of STACKEY on the CGA. The medium resolution mode on the CGA (mode 4) is a four color mode. In addition to the background color, there is a choice of one of two palettes: Palette 0: green, red, brown (color numbers 2,4,6) Palette 1: cyan, magenta, grey (color numbers 3,5,7) The default is palette 1. You can change palettes with the P command. Pn will change to palette n where n must be 0 or 1. Like the L command, when smart processing is on, STACKEY will wait for an empty buffer before implementing the palette change. Example: To change to palette 0 on a red background, just before loading a program changing to mode 4 issue stackey W36L4P0 Unfortunately, if you set colors for graphics mode with STACKEY and then call up a resident program that works in text mode like SIDEKICK (TM), when the resident program exits and you return to graphics mode, you will have lost your color settings. CTRLALT PLUS enables you to reset these color settings. Chapter IV:SETTING COLORS page 53 Documentation for STACKEY, Version 2.0 IV.5 Color Basics: EGA color slots and palettes The EGA/VGA carries color setting a step further than on the CGA. The graphics modes special to the EGA and also the normal text mode are capable of showing 16 colors but those 16 colors can be chosen from among 64 in modes 3 and 16. Thus the 16 choices should be viewed as "color slots". Into each slot, one can map any one of the 64. In the default situation, the color slots are filled by colors identical to the ones on the CGA but with suitable software (like STACKEY!), the user can change the assignment of colors to slots. Such an assignment is called a palette. Sometimes what we are calling color slots are called palette numbers and the numbers we will call color labels are called palette parameters. The total number of palettes is approximately 8 times 10 raised to 28th power. To appreciate how large this number is, we note that if every PC in the world were equipped with an EGA and could check out a billion distinct possibilities each second, it would takes millions of years to complete the exploration of all the palettes. IV.6 Color Basics: EGA color labelling Each individual color among the 64 is gotten by blending a level of red, green and blue. Each primary color can be mixed in at one of 4 levels (so 64=4x4x4). Alternatively, one thinks of a strong red bit and a weak red bit whose presence are indicated R and r. Thus, the four levels of red are none, r, R and Rr. Similarly, there is no blue, b, B, Bb and no green, g, G and Gg. Each color can be associated to a mixture of the six letters rRgGbB and is assigned a number by using the following values: B=1,G=2,R=4,b=8,g=16,r=32 Thus, for example Rg has the value 4+16=20. With one exception, the default colors are taken by looking at the CGA IRGB labels and replacing I by rgb. The exception is brown in color slot 6 which is RG in CGA and translates to Rg in EGA. Chapter IV:SETTING COLORS page 54 Documentation for STACKEY, Version 2.0 To help you in exploring the colors, we have attempted to give them names: 0(00H) black* 32(20H) r faint red 1(01H) B blue* 33(21H) r B looks blue to me 2(02H) G green* 34(22H) rG looks green to me 3(03H) G B cyan* 35(23H) rG B looks cyan to me 4(04H)R red* 36(24H)Rr bright red 5(05H)R B magenta* 37(25H)Rr B hot pink 6(06H)R G pea green 38(26H)RrG orange 7(07H)R G B grey* 39(27H)RrG B flesh pink 8(08H) b navy blue 40(28H) r b royal purple 9(09H) Bb bright blue 41(29H) r Bb looks bright blue to me 10(0AH) G b glade green 42(2AH) rG b looks glade green to me 11(0BH) G Bb powder blue 43(2BH) rG Bb looks powder blue to me 12(0CH)R b maroon 44(2CH)Rr b lox (smoked salmon) 13(0DH)R Bb lilac 45(2DH)Rr Bb bright lilac 14(0EH)R G b khaki 46(2EH)RrG b peach 15(0FH)R G Bb blue grey 47(2FH)RrG Bb light lilac 16(10H) g forest green 48(30H) r g looks forest green to me 17(11H) gB steel blue 49(31H) r gB looks steel blue to me 18(12H) Gg bright green 50(32H) rGg looks bright green to me 19(13H) GgB cyan green 51(33H) rGgB looks cyan green to me 20(14H)R g brown* 52(34H)Rr g vermilion (red orange) 21(15H)R gB lavender 53(35H)Rr gB pale hot pink 22(16H)R Gg lime green 54(36H)RrGg canary yellow 23(17H)R GgB bright cyan green 55(37H)RrGgB cream 24(18H) g b steel grey 56(38H) r g b dark grey* 25(19H) gBb cyanic blue 57(39H) r gBb intense blue* 26(1AH) Gg b intense cyan green58(3AH) rGg b intense green* 27(1BH) GgBb bright cyan 59(3BH) rGgBb intense cyan* 28(1CH)R g b chocolate brown 60(3CH)Rr g b intense red* 29(1DH)R gBb bright lilac 61(3DH)Rr gBb intense magenta* 30(1EH)R Gg b bright lime green 62(3EH)RrGg b yellow* 31(1FH)R GgBb bright cyan 63(3FH)RrGgBb white* The default colors are indicated with a *. We feel that the tolerable choices for background colors include blue(1), maroon (12), steel grey (24) and forest green (16). Particularly interesting colors include chocolate brown (28), hot pink (37), orange (38), lox (44), peach (46) and vermilion (52). Among the combinations we like for text in graphics mode are cream on maroon (55 on 12) and bright cyan on blue (27 on 1). The demonstration BATch files color.bat and seecolor.bat, described later allow you Chapter IV:SETTING COLORS page 55 Documentation for STACKEY, Version 2.0 to explore the EGA color combinations. They require an EGA or VGA connected to an Enhanced Color Display or VGA monitor or equivalent. A palette on the EGA is thus the assignment to each color slot of one of the 64 color values. This is also called a color mapping. If you have mapped blue into the slot normally occupied by black and yellow into the slot normally occupied by grey, your dumb program will think it is displaying vibrant grey on black for you but you'll see yellow on blue. Later we'll see how to make this kind of mapping with STACKEY. While color mapping is possible in modes 4,6 and 14, you don't have 64 colors to choose from and the g and b parameters have no effect on colors in those modes. IV.7 Color Basics: EGA borders In addition to the sixteen colors that you can display on the EGA (in modes 3,13,14,16), there is a choice of border color. While in principle you can set a border in any mode, the border in the 350 line modes (modes 1,3,16) is so wimpy, you won't want to use it. But the border is a full one in modes 4,6,13,14. Unlike the CGA which forces the same color for background and border in mode 4, the EGA allows these colors to be different. The technical name for the border is overscan and the corresponding slot is called the "overscan byte". IV.8 Color Basics: EGA hardware considerations All our discussion has been for the EGA with 256K attached to an enhanced color display or equivalent. There are some differences if you have less memory or an ordinary color monitor attached to your system. With 64K on your EGA, even with an ECD you can only display four colors from a set of 16 in mode 16 (high res EGA graphics). The available slots are 0,1,4,7. An ordinary color monitor attached to an EGA does not support mode 16 and does not support any colors but the standard 16. We believe that color mapping is possible with this setup but have not tested it out. There is unfortunately quite a bit of variation between hues on different sets of the same hardware and even greater variation if you are using an ECD clone rather than the IBM version. In Chapter IV:SETTING COLORS page 56 Documentation for STACKEY, Version 2.0 particular, colors 33 and 1 will look exactly alike on some machines and at least slightly different on others. IV.9 Setting colors on the EGA or VGA STACKEY lets you make an arbitrary mapping of colors to color slots. The syntax is to place the color commands inside []. The command stackey [] resets the palettes to the default. Otherwise inside [], use c=nn where c is either a number from 0 to 15 and represents the color slot or the letter o (or cap O) if you want to change the overscan byte. nn can either be a number from 0 to 63 or a string of up to six characters from rRgGbB. Thus stackey [0=62] and stackey [0=RrGgb] do the same thing, namely place yellow in color slot zero. As is the case for delays and CGA colors, the [] command will only be implemented when there is an empty keyboard buffer. This means that if you are also placing keystrokes in the buffer which will only be absorbed after your application loads and changes mode, you need not (and should not) place a wait in the command line. For special situations you may want to turn this smart processing on and off with the /p/, /s/ and /i/ commands discussed in Chapter III. If you do not have an EGA or VGA installed and attached to a color monitor, then STACKEY will issue an error message if any command with a [ is attempted. Several changes separated by commas, spaces or semicolons can be used inside a single pair of brackets. Example: It's Halloween so you want black on orange in text mode. Normally your colors are the default grey on black (shame on you!). Enter stackey [0=38,7=0] Example: You want to call up REFLEX 1.0 on the EGA from a BATch file REFL.BAT which first of all loads a file specified on the command line (normally, you'd have to hit / for menu, p for print/file submenu, r for read, enter the file name and hit <Enter> twice). You also want Chapter IV:SETTING COLORS page 57 Documentation for STACKEY, Version 2.0 to change REFLEX's default colors (white on black, shame on BORLAND; colors have been fixed in Reflex 2.0 - hooray for Borland) to cream on maroon. Your BATch file should read: echo off cls C: cd\reflex stackey "/pr%1"CRCR[0=12,15=55] reflex Probably you should include special handling if %1 is the empty variable. If you were not placing keystrokes in the buffer, it would be essential to put a delay in such as stackey W150[0=12,15=55] to make sure that REFLEX has changed modes before the color change command takes effect. With a stroke in the buffer, the color change is only implemented after REFLEX loads and processes those strokes. If you have turned off smart processing, then waits will be necessary. Example: Your colors are normally yellow on blue set with your prompt. You want to have bright blue on lilac for text today. Use stackey [1=RBb,14=Bb] (We don't particularly like this combination, mind you). Example: You want to call up a program using mode 6 graphics and want a cyanic blue border and blue on cyan text area. Use stackey [o=gBb,0=BG,1=B] Yes, it is 1=B and not 7=B. The foreground in mode 6 is color slot 1 even though it defaults to grey. Similarly, the foreground in mode 4 defaults to color slot 3. Note for users of Ultravision: In order for the temporary palette commands to work, if you have Ultravision installed and call for a [] color change, then STACKEY will turn off Ultravision palette locking and you will not be able to set colors with Ultravision without turning it back on either with a [#U..] command (see the next section) or from the Ultravision main menu. CTRLALT PLUS' resident palette setting will only work if Ultravision's palette locking is turned off. Chapter IV:SETTING COLORS page 58 Documentation for STACKEY, Version 2.0 IV.10 Setting permanent colors on the EGA/VGA Every time the mode is changed the colors get reset by the EGA/VGA to their default value. A mechanism is provided to change the default values to which they are reset. These changes are made only for the current session on your computer. The values are changed to their "real" defaults whenever you reboot. Nevertheless, since the choices do persist through mode changes they are called permanent. Unfortunately, the place where these permanent palettes are kept is in ROM where they cannot be changed by the user or any program! It is possible to set aside a region of RAM which is read instead of ROM for permanent color changes. Once the permanent colors are stored there, it is possible to have a program that changes them. As we will describe in Chapter VII, the programs EGAPAL and VGAPAL set up such a region in RAM. STACKEY's permanent palette setting only works with one of these programs or with Ultravision. The syntax is stackey [#m,c=nn] where m is the mode number in decimal. Thus to arrange that mode 16 always comes up with black mapped to maroon and white to cream use stackey [#16,0=12,15=55] As usual, the comma can be replaced by spaces or semicolons. You can change the permanent colors back to the default by using stackey [#m] If you replace m by A, STACKEY will make the changes to all palettes and, in particular stackey [#A] resets all the permanent palettes. Acceptable values of m are 1,3,4,6,13,14,16 and A. Any other value, or an attempt to use this service without an EGA or VGA will result in the error message: VGAPAL is not installed on a VGA and similarly on an EGA. On an EGA, separate palettes are kept for each mode. Only one #n is allowed within a single bracket. On a VGA only a single palette is kept. You can set the palette for multiple modes with multiple uses of # sign as in [#3 #16 1=4,2=13] Chapter IV:SETTING COLORS page 59 Documentation for STACKEY, Version 2.0 If Ultravision is installed, you will get an error message if you try to use [#n..] or [#A..]. Instead you need to use [#U..] or [#T..]. This tells STACKEY to turn on Ultravision's palette locking and set its palette. The difference between the two ultravision commands is that #T turns on Ultravision's palette locking only in text mode while #U turns it on in all modes. The color slot and color label must appear on either side of the equal sign with no spaces allowed. Between different color settings in a multiple setting command you must place a delimiter (comma, semicolon or space). The permanent changes are made in "real time", that is as soon that part of the STACKEY command line is interpreted. Thus they are not postponed by previous delays (the Wn) command although they are postponed by waits (the {Wait n} command). In particular, permanent palette changes are not delayed until there is an empty buffer as is the case with temporary color changes when smart processing is turned on (the default). You may not stack both temporary and permanent changes in the same bracket. Permanent changes can only be made if # is the first symbol immediately following [. A delimiter (comma, semicolon or space) must separate the color slot numbers. While you cannot place permanent and temporary changes inside of the same set of [], there is no reason that you can't place more than one set of [] on one command line with some temporary changes in one [] and some permanent changes in the other. Color palettes made "permanent" will be properly restored by your popup programs when they exit. IV.11 Controlling the blinking bit As we explained, in text mode, you have 16 foreground colors but only 8 background colors. Each cell on the 80x25 screen has a full byte describing its "attributes" so there is enough room to describe 16 foreground and 16 background colors but instead, by default, the bit that would naturally describe the intensity of background instead describes whether the foreground is blinking. One can program the EGA or VGA to suppress blinking and instead display the full 16 background colors. The command stackey -B turns off the blinking choice and turns on the 16 background color Chapter IV:SETTING COLORS page 60 Documentation for STACKEY, Version 2.0 mode while the command stackey +B turns blinking back on and reverts to the 8 background color mode. These commands only have an effect on text modes. Like the L,P and temporary [] commands, the +/-B commands are subject to smart processing. Chapter IV:SETTING COLORS page 61 Chapter V:UTILITIES MODE V.1 Overview of Utilities Mode STACKEY offers a command line utility mode that should allow you to replace lots of little utilities that you might have. In a sense, these utilities are completely independent of STACKEY's key stacking function. The commonality of the two modes is that they are both naturally callable from BATch files or from CED synonyms and a commonality of some parts of syntax. However, it is possible to use the utilities without loading the resident portion of STACKEY if you wish. Stackey's send mode (Section II.12) is really a utility since it doesn't use the resident part of STACKEY; however, there is no way to use it without loading the resident portion. Utilities are called from the STACKEY command line by placing the desired function within braces {}. As usual you can place any other STACKEY commands on the same line so long as the utility ends with }. If there are other commands on the line or there is a final }, then the resident portion of STACKEY will be loaded if it has not been previously loaded. However, if you meet two conditions, then the resident portion will NOT load: you must not place any commands on the line before the opening { and you must not put in a closing }. By separating with delimiters (space or semicolon but NOT comma since a comma is used as a delimiter for multiple parameters in a single command) you can call up several utilities at once. Thus, to switch to a color monitor and a block cursor covering the entire line you can use stackey {mon=c cur=0,7} or stackey {mon=c cur=0,7 In the second case, the resident portion would not load if it were not already loaded whereas in the first case it would. Placing a command to the stack like CR before or after the {}'s in the first case would have the same effect. In the second case placing CR before the { would load STACKEY if it weren't already loaded. Placing it at the end of the line with no closing } before would produce an error message. It is important to realize that utilities are implemented in real time and in the order they occur. Thus stackey {wait=360 mon=m} would wait 20 seconds before changing monitors while stackey {mon=m wait=360} would change to the monochrome screen and then wait 20 seconds before continuing the BATch file or returning control to DOS. Chapter V:UTILITIES MODE Page 62 Documentation for STACKEY, Version 2.0 Because of the real time processing of utilities, errors in syntax are handled a little bit differently when there are utilities commands on the command line. Normally, if there is any error on the command line, STACKEY aborts with an error message and takes no action. But since a utility command is implemented as found, if an error occurs afterwards STACKEY will abort with an error message but any utilities which have been done will not be undone. For example, the line stackey xyz {mon=m} will abort with an error message and no action taken but stackey {mon=m} xyz will first switch to the monochrome screen and then abort with an error message (naturally on the monochrome screen). Because utilities are performed in real time while commands to the resident part are performed only when the entire line has been processed for errors, commands to the resident part will normally only be implemented after utilities even if they proceed the utilities in line. Thus stackey [0=1]{mon=m} will only issue the palette change after the monitor change. If you want to have the palette change before the monitor change, you should use separate lines: stackey [0=1] stackey {mon=m} A special rule applies with waits where the commands prior to a wait are placed in the stack before the wait. For example stackey [1=4]{w=36}[1=1] if you normally have a blue screen will show you a red screen for 2 seconds. The precise syntax for the utilities command within braces is either FUNCTION or FUNCTION=parameter(s) if there are some necessary parameters. FUNCTION uses the notion of minimal truncation. Thus MON is the minimal truncation for MONITOR so any of MON, MONI, MONIT, MONITO and MONITOR are acceptable where MONITOR is indicated. We use the shortest minimal truncations which avoid ambiguity so MO is not a truncation for MONITOR to avoid confusion with the MODE command. To indicate that MON is the minimal truncation, we'll write the command at the start of the Chapter V:UTILITIES MODE Page 63 Documentation for STACKEY, Version 2.0 section describing it, and in the summary as MONitor. In spite of this case, the commands are not case sensitive so {mon=m} or even {MoN=m} would work. You may not use any spaces before or after the = signs when parameters are required. While we recommend that you do use delimiters between utilities, you need not so that stackey {mon=cw=36} would switch to the color monitor and wait 2 seconds. However, if the command has no parameters and you use a minimal truncation, you must use a delimiter. Thus stackey {k be=54} or stackey {keywaitbe=54} will both work but stackey {kbe=54} will generate an error message. The LOCK and BEEP commands let you issue several calls at once by separating the parameters by colons as in stackey {LO=-C:-N:-S} In addition you can call several beeps at once by using colons. A summary of all the commands can be found at the end of the documentation and in the help available from the DOS command line. V.2 WAITs and UNTILs Commands:Wait=nnn, UNtil=HH:MM (followed by p,t,n) There are times when you want to pause in your BATch files to give the user a chance to read a screen or because the action you want is time sensitive. The WAIT utility command is precisely for such times. The minimal truncation is W so the syntax is stackey {W=nnn} where nnn is the number of ticks for the delay. There are roughly 18 ticks per second and about 64K ticks per hour. nnn must lie between 1 and 64K=65,535. If a larger number is used you get an error message "Number out of range". If you want a delay longer than 60 minutes, you can place multiple waits as in Chapter V:UTILITIES MODE Page 64 Documentation for STACKEY, Version 2.0 stackey {W=64000 W=64000} Often, instead of wanting to wait for a fixed time, you want to wait until a fixed time. That is, you want to hold up a pending batch file until a time comes. The UNTIL command will do this. In its simplest form the syntax is stackey {until=HH:MM} where HH:MM is a military (24 hour clock). However, STACKEY will recognize three letters after the HH:MM. First, a "p" will add 12 hours so that {until=3:15p} will be interpreted as 15:15, i.e. 3:15 pm. p must be the first letter after HH:MM. t for (tomorrow) will add 24 hours; multiple t's are allowed as is pt (but not tp). Thus {until=3:15pttt} would wait until 3:15 in the afternoon, three full days after the current day. STACKEY does not check that the time is a legal time so that {until=32:15} would be interpreted as 8:15 tomorrow as would {until= 30:135}. Normally STACKEY computes the time that you are calling for and checks if that time has past. If it has, STACKEY assumes that you've made a mistake and exits with an error message. For example, if you enter STACKEY {until=3:15p} and it s 4:00 pm, you'll get an error message. Of course, it may happen that you'll want something to happen the next 3am whether it is today or tomorrow. Suppose, for example that you leave your machine on 24 hours a day but some resident program insists on reading daily alarms each day. So you might want to reboot at 3AM while you sleep. A batch file stackey {until=3:00}{reboot} will do what you want so long as you start it after midnight but if you start it before, you'll get an error message. The key letter n tells STACKEY you want the next time that time appears. Explicitly, it computes the time and, if it has past adds 24 hours. Thus stackey {until=3:00n}{reboot} will do what is desired. {until=HH:MMntt} will not wait two days after the next HH:MM. Instead use two separate stackey commands if that is what you want, e.g. stackey {until=3:00n}{until=3:00tt} if you want to wait until two days after the next 3:00 am. Chapter V:UTILITIES MODE Page 65 Documentation for STACKEY, Version 2.0 If you put in a wait or until by mistake, hitting Ctrl- Break, ^C or <Esc> at the keyboard will cancel the wait; i.e. STACKEY will exit. The remainder of the stackey command line will also be cancelled. You should distinguish between what we call delays and what we call waits. Delays are set with the command Wnnn while waits are set with the {WAIT=nnn} utilities mode command. Delays are commands to the resident part of STACKEY telling it to delay placing strokes in BIOS' buffer (or setting colors) while operating in the background as some foreground program is running. Waits are commands to the foreground part of STACKEY telling it to loop and control all machine resources (although you can call up a program like SIDEKICK) until the wait period is over. Thus waits will be useful only in rather special circumstances like demonstration BATch files while delays will get used more often. Delays are implemented as they are reached by the resident part of STACKEY. Thus, if you send more strokes to STACKEY's buffer than there is room for in BIOS' buffer, STACKEY will pause in sending its buffer until the backlog of strokes in BIOS's buffer is cleared. If there is a delay in the "strokes" waiting for STACKEY to process, the count in the delay will not begin until the delay is reached in STACKEY's buffer. In distinction to this, STACKEY implements waits as soon as they are reached in its interpretation of the command line. As already noted, while STACKEY loops and counts time when involved in a wait, you can invoke a resident program like SIDEKICK(TM) at such a time. STACKEY will continue to count time while the resident program is active and if the wait ends while the resident program is up, then STACKEY will exit as soon it regains control. WAITs are computed by using the built in real time clock on the PC and so should be independent of hardware so long as the IBM standard 55 millisecond tick rate is used. In particular, they will work the same way on 4.77 MHz PC's, 6 MHz AT's, 12 MHz AT clones and 25 MHz Northgate 386 machines. Other wait programs like the public domain WAITN.COM just program loops and will run for shorter times on machines with higher crystal speeds. Chapter V:UTILITIES MODE Page 66 Documentation for STACKEY, Version 2.0 V.3 Switching Monitors and Ports Commands:MONitor=x (x=C,M,S), Prn, COmm There are utilities to switch ports and monitors. The command stackey {PRN} will interchange LPT1 and LPT2 so that what was previously attached to LPT2 will now respond to attempts to send things out LPT1 and vice versa. Repeating the command will interchange them again restoring the status quo ante. Similarly, {COMM} will interchange COM1 and COM2. The minimal truncation for PRN is P and for COMM is CO. If you are not adding the final }, you will need to use the full PRN or COMM if they are the last command on the line. CTRLALT PLUS includes a resident program called 2ND PRINTER which will let you change printers from within a running program. Similarly, you can switch monitors with the MONITOR utility command whose minimal truncation is MON. This however must take a parameter. To switch monitors use MON=S, to force the color monitor use MON=C and to force the monochrome monitor use MON=M. You will also wind up on the target monitor in 80 column text mode after a MON command. In addition, the cursor on the original monitor, if different from the target, will be removed. Be careful not to use the MON command if you only have one monitor. CTRLALT PLUS, another program by the authors of STACKEY provides considerable support for systems with two monitors and/or two printers. Chapter V:UTILITIES MODE Page 67 Documentation for STACKEY, Version 2.0 V.4 Turning off PrintScreen Nothing can be quite as frustrating as hitting Shift-PrintScreen by mistake with a computer not attached to a printer! Typically you'll hang losing any unsaved work. For such purposes, STACKEY provides a two key code P- which turns off the ability of Shift-PrintScreen to work. You do this with STACKEY P- so that it is not a utility but rather a resident command. However, like the Z+/Z- speedup commands described in Section II.6, it acts much like a utility. To turn the ability of Shift-PrintScrren to work again, use P+. This command works by turning on the byte in the BIOS data area that says a print screen is in process. So, if you hit Shift- PrintScreen, the BIOS check that sees if there is already a print screen in progress, thinks there is and it exits. This means that P- will not effect other programs like PIZAZZ PLUS or FRIEZE that pop up on the Shift-PrintScreen combination. V.5 Mode, Lines and Cursor Control Commands: MODe=n, UMode=n LInes=25, 43 or 50 CUrsor=+ or -, CUrsor=n,m There are a number of utilities commands associated with the video display. You will not normally want to switch modes when at the DOS level but might, for example, to check out color setting commands discussed in the last chapter. The MODE=n command will switch to mode n if n is on the allowed table below. If a not allowed value is used, STACKEY will abort with a syntax error message. Allowed values of n are: On an ordinary (or Hercules) monochrome screen: 7 On an EGA attached to a monochrome monitor: 7,15 On a CGA: 1,3,4,6 On an EGA attached to a color monitor: 1,3,4,6,13,14,16 On a VGA: 1,3,4,6,13,14,16,17,18,19 With one exception, this prevents you from trying to switch to an illegal mode which may produce problems. The exception is that you should not try to switch to mode 16 if you have an EGA connected to the old fashioned color display rather than an enhanced color display. For example Chapter V:UTILITIES MODE Page 68 Documentation for STACKEY, Version 2.0 stackey {mod=14} will switch to the medium resolution EGA 14 color graphics mode if issued on a color screen and if you have an EGA. The minimal truncation for MODE is MOD. Some Super VGA monitors have additional modes set with a BIOS call identical to the standard mode change but with another mode number. If you wish STACKEY to make such a call without checking that the mode number is legal, use the UMODE command (for User mode). LINES=25 and LINES=43 will switch to the appropriate modes if you have an EGA. Many programs will not act properly in 43 line mode. The minimal truncation is LI. On a VGA, use LINES=25 or LINES=50 instead. STACKEY will check on the monitor type and issue an error message if you use any value of lines other than 25, 43 or 50 and if you use an illegal value for the monitor you have (e.g. lines=43 on a VGA). CURSOR, which takes one or two parameters, controls the cursor. The minimal truncation is CU. CU=- will remove the cursor and CU=+ will restore it to the standard place (lines 6 and 7 on the color monitor and lines 12 and 13 on the monochrome monitor). For certain BATch file displays, it is effective to use CU=- but please remember to restore the cursor with CU=+. If you don't like the standard cursor you can control it with CU=m,n. On a color monitor, there are 8 lines, labelled 0 through 7 and on a monochrome monitor 14 lines labelled 0 through 13. The command CU=m,n when m and n are in the allowed values sets the cursor to start on line m and end on line n. If m is less than or equal to n, the cursor is in one piece while if m is greater than n, the cursor wraps around an is in two pieces. For example stackey {cu=0,7} produces a full height block cursor on a color monitor and stackey {cu=7,0} produces a cursor consisting of a thin roof and thin ceiling. Using improper values will typically produce unexpected effects, e.g. {cu=32,0} will cause the cursor to vanish (and is effectively the same as cu=-). Programs like CED and FANSI CONSOLE can effect the cursor at the DOS prompt. In particular, on a machine with SOFTWARE CAROUSEL and FANSI CONSOLE, partitions with PCED had any cursor set with STACKEY immediately reset at the DOS level. But in BATch files, Chapter V:UTILITIES MODE Page 69 Documentation for STACKEY, Version 2.0 STACKEY should give you complete control over the cursor. BATUTIL will let you change the position of the cursor; see the BATUTIL documentation for the ROw and COl commands. V.6 Beeps Command: BEep=n,m or BEep=n You can send variable length and frequency beeps with STACKEY. In version 2.0 of STACKEY, the duration for a given set of parameters was machine dependent since it relied on the clock speed of the underlying machine although the frequency was machine independent. BEEP, whose minimal truncation is BE takes two parameters. The second parameter may be left blank in which case the comma must also be left out. The first parameter determines the frequency and n is a measure of the inverse frequency so as n increases the pitch goes down. The most reasonable values are n between 15 and 60 but any number between 1 and 256 will yield an audible sound. The second number is the duration; the default is m=50. You'll have to play with this one to see how it works. The sample BATch file SOUNDS.BAT is not intended as competition for Pianoman. Multiple beeps can be stacked as in stackey {BE=20,40:75,55} In addition, you can tell STACKEY to repeat a string of beeps multiple times by inserting "#nnn" between "BE" and "=". For example, stackey {BE#5=20,80:30,90:40,80} would play the three notes and then repeat it four more times. V.7 Screen dumps Commands: DUMPP, DUMPF=x,DUMPOF=x,DUMPL=x,DUMPOL=x where x is a filespec STACKEY will let you send the current screen to the printer or a file. The command line stackey {dumpp} will send the screen to the printer. If the printer is not on or you have no printer, a standard STACKEY error message will display. Chapter V:UTILITIES MODE Page 70 Documentation for STACKEY, Version 2.0 This command simulates the pressing of <Shift-PrtSc> so if you have a program like Intel's QUIKBUF or Zsoft's FRIEZE which takes over this key combination, it will be called up instead of the screen printing. DUMPF, DUMPOF, DUMPL and DUMPOL which require an = and a file name, all dump the screen to a file. The commands without an "O" append the present screen to the file if it exists while those with an "O" will overwrite it. The commands with an F make the 2000 bytes on the screen into a file. This file will occur as one long line with no LF/CR pairs. Those with an L append LF/CR pairs at the end of each line and so produce files with 2050 bytes. Files produced with an L will be properly displayed in a file viewer like Vern Beurg's LIST while those produced by an F will properly TYPE to the screen. If you TYPE a file with L to the screen, blank lines will appear in between each original line. LIST can properly view files made with F if you turn wrap on but many other programs will have problems with files produced in that manner. The filespec placed after = is passed to DOS so the usual rules apply. If there is any kind of file error whether due to an invalid path or an open drive door, STACKEY will exit with the message STACKEY: DOS File Error and set the errorlevel to 3. V.8 Rebooting Commands: BOOT(=c), REBOOT(=c) Minimal truncation NONE In rare circumstances you may want to reboot your machine automatically. STACKEY only accepts the exact phrase BOOT or REBOOT and if it finds it looks for the next two characters. If they are "=c", STACKEY initiates a cold reboot, otherwise a warm reboot. The difference is the parity resetting and checking of memory. While the reboot method just jumps to the instruction in ROM that is gone to when you turn on the machine, if you try to REBOOT with STACKEY and you are using SOFTWARE CAROUSEL your EMS board may not reset properly; a second warm reboot should clear that up. Chapter V:UTILITIES MODE Page 71 Documentation for STACKEY, Version 2.0 V.9 Lock Toggles Command: LOck=xy (with x=+ or -; y=C,S,N,I) For consistency, recognizing that the lock commands like +C are real time utilities, the eight two character commands +/- C,S,N,I are available in utilities mode as {LOCK=xy}. So to turn on the caps lock you could use stackey {LOCK=+C} or stackey +C The only reason to prefer the former is if you do not want STACKEY resident and leave off the final }. The minimal truncation is LO. Multiple lock commands can be combined separated by colons as in stackey {lo=-C:-N:-S} V.10 The Halt Command Command:HAlt STACKEY offers a command which halts a batch file in midstream. You'd use it most often after an if command as in if errorlevel 2 then STACKEY {HA} The HALT command first checks if Break is on and if it is not, it turns it on. Then it places a ^C in the buffer so that DOS will pause the batch file and display the message: Terminate batch job (Y/N)? and give you an opportunity to terminate the batch file. If you wish to absolutely terminate the batch file without a Y/N question from DOS, make the last line of the batch file the label :end and use if errorlevel 2 then goto end If STACKEY finds the Break is off and turns it on, it displays the message: STACKEY: BREAK has been turned on. Chapter V:UTILITIES MODE Page 72 Documentation for STACKEY, Version 2.0 V.11 Pause for input Commands:Keywait, Enterwait, Abortwait, ~abortwait STACKEY 2.0 had four commands to interact with keyboard input in batch files. For compatibility, these are still included although BATUTIL has expanded and extended them. KEYWAIT will pause a batch file for a key to be hit. It is equivalent to BATUTIL {ge el} while ENTERWAIT, which pauses until <Enter> is hit is equivalent to BATUTIL {ge cr} ABORTWAIT pauses until either Y or N is pressed and halts the batch file if Y is pressed. It is equivalent to BATUTIL {ge Y N} if not errorlevel 2 then stackey {HA} ~ABORTWAIT pauses until either Y or N is pressed and halts the batch file if N is pressed. It is equivalent to BATUTIL {ge N Y} if not errorlevel 2 then stackey {HA} Chapter V:UTILITIES MODE Page 73 Chapter VI:ADVANCED TOPICS In this chapter, we discuss three distinct advanced topics. First, for the reader's background, we provide a tutorial on how keystrokes are processed in a PC. This may help you understand what STACKEY can and cannot do but for most operations that you'd want to do, it isn't necessary. Then we'll discuss a powerful but potentially VERY DANGEROUS feature where STACKEY allows you to place any arbitrary sequence of machine language instructions in the middle of a STACKEY script. We originally developed this INLINE feature for STACKEY's internal purposes. The idea was that while we wanted to give users of a program like CAROUSEL access to the Qn command, it hardly seemed fair to make all users carry the code for that command as part of the RESIDENT code of STACKEY. We thus developed INLINE code to place a sequence of commands as part of the playback buffer. Thus the Carousel code is part of the non-resident program and is only loaded into the keystroke buffer when needed. Of course, if you have long scripts that include INLINE commands, you'll need to increase your buffer size but this need will only be felt by a small set of users. INLINE code if not done right can really screwup your machine - requiring a reboot or even lost disk data. It should only be used by those who know what they are doing which means people adept in 80x86 assembly language. If you are copying an inline routine supplied by someone else, be careful to not make any typing errors! There is also an EXTERNAL command to read inline code from a binary file. As illustrations, we have supplied a number of external files called *.bin. Finally, we will describe STACKEY's API (application program interface) which programs can use to talk to the resident part of STACKEY. Indeed, STACKEY's nonresident part talks to the resident part through the API. VI.1 Keyboard basics: interrupts We want to explain the journey taken by a single keystroke. In short, hitting a key calls int 9 and the BIOS processes the keystroke and places it in a buffer. Programs then call BIOS int 16 or DOS service 8 to get keystrokes out of the buffer. Here is more detail: Your CPU runs programs as a sequence of instructions in RAM. RAM is organized into bytes, each of which has a unique address. Normally, the CPU runs a program by sequentially going through the instructions but there are instructions to jump to a given address or to jump depending on the result of some comparison. Programs call DOS services by placing certain information in the CPU registers (local storage in the CPU) which tell DOS what is wanted Chapter VI:ADVANCED TOPICS Page 74 Documentation for STACKEY, Version 3.0 and then turn control over to DOS. How does the program know where DOS is since different versions of DOS will typically reside in different places? The lowest 1K of bytes on the machine is a list of 256 addresses. The instruction int nn (with nn a Hex number) transfers control to address nn of these 256 (with the convention that the first address is int 0 so int 21, the interrupt for most DOS services is the 34th address since 21H = 33). This is done in a way that stores the current state of the machine so that if DOS ends its routine with an IRET (interrupt return) instruction, then the calling program can resume operation from where it began. What has just been described is a software interrupt, that is one that is called by a program actively asking for that interrupt. There are also hardware interrupts, indeed the notion began with hardware interrupts. How does the CPU determine that a key has been struck? It could periodically ask the keyboard: "Hey, any action for me?" but such "polling" isn't very efficient. A better method is for the keyboard to tap the CPU on shoulder and say: "I've got something for you, buddy". What the CPU should do is stop what it is doing, keep a record of where it is, process the stroke and return to what it is doing. In more prosaic terms, hitting a key sends a signal to the interrupt controller chip which causes int 9 to be issued. This transfers control to the 10th address in memory, information is processed on the basis of which key is struck and control is then returned to where the CPU was and the underlying program continues. The two hardware interrupts of greatest interest are int 9 which is issued whenever a key is hit or released and int 8, the timer interrupt which is issued every 55 milliseconds. These 55 millisecond periods are called clock ticks. There are roughly 18.2 per second. One of the key aspects of interrupts is that a program can steal an interrupt. If done responsibly, such larceny is good for everyone and in particular TSRs can only work because they steal interrupts. Let's imagine a program that pops up whenever you hit Ctrl+Alt+A. How does such a program gain control when you hit its hotkey? When it loads, it looks at the address stored for int 9. This is the address of the routine which will be called whenever a key is struck. It stores this address in its own data area and places the address of some of its code in the int 9 location. Thus one of its routines is called whenever a key is struck. This routine will look and see if the key hit was A; if it is A, then it Chapter VI:ADVANCED TOPICS Page 75 Documentation for STACKEY, Version 3.0 checks the byte where BIOS keeps the state of the shift keys and checks if Ctrl+Alt are depressed. If they are, then the TSR pops up after doing some necessary housekeeping to reset the keyboard and interrupt controller. If the key isn't for the TSR program, then the routine passes control to the original routine stored at the original int 9 address. In this way, a chain is created of all the different TSRs peeking at each keystroke and passing it on if it isn't their hotkey. TSR technology is more complex than this but this describes the basic idea. It is only by sitting on some interrupt that a program can get control and so take part in the goings on. STACKEY actually does most of its work by sitting on the timer interrupt, checking each 55 milliseconds to see if it still has anything to do. VI.2 Keyboard basics: The buffer and BIOS data area The first 1024 bytes in memory contain the interrupt table. The next 256 bytes form the "BIOS data area" where lots of miscellaneous information is kept including the number of clock ticks since midnight (BIOS sits on int 8 and increases this number every time int 8 is called) and a good deal of information about the keyboard. In one byte is kept the information about the state of CapsLock, NumLock, ScrollLock and the Insert state. As part of the same byte is kept information about which of the four shift keys is currently depressed (thus all 8 bits of this byte are productively used). 34 bytes are used to deal with a type ahead buffer. As we'll explain, each "normal" keystroke places two bytes in the buffer. As you type, new two byte combinations are added to the buffer while as an application processes input, two byte combinations are "removed from the buffer". Rather than actually remove the bytes, BIOS keeps track of the head of the active buffer and of its tail. The head is the address of the next stroke to be processed and when it is processed all that BIOS does is move the head pointer up in memory. As you hit keystrokes, they are placed in the buffer at the position kept by the tail pointer and it is moved up. The 15 word (a word means two bytes) buffer is circular so that the head and tail pointers will wrap around the circle. If the head has caught up to the tail, then BIOS knows that the buffer is empty and will so inform a program that asks. If the tail has looped around and caught up with the head, BIOS knows that the type ahead buffer is full and will beep at you if you try to type more. Chapter VI:ADVANCED TOPICS Page 76 Documentation for STACKEY, Version 3.0 VI.3 Keyboard basics: Int 9 processing The keyboard on the original PC has its own built in micro processor but it is not a very clever one. Basically, all it knows about is that you have depressed or released a certain key. To it all keys have equal footing - it doesn't distinguish between shifts, locks or letter keys. It just knows them as keys. Each key has its own unique hardware scan code so that the <Esc> key has scan code 01, the letter "A" scan code 1EH, <F7> 41H, the Left shift 2AH and the Capslock 3AH. Basically, the codes are arranged so that on the original PC they increased from left to right in each row but as the position of keys migrated from one keyboard upgrade to the next, the old codes were kept for compatibility. All the codes lie between 01H and 7FH (=127). In fact none is as high as 7FH but theoretically one could have 127 keys on the keyboard without drastic changes, but 128 or more keys each distinguished from the other would require a completely redesigned BIOS! In fact the so called enhanced keyboard is more clever. It distinguishes keys like the arrow keys on the numberpad and the separate cursor keys pads by using a pair of codes for the arrow key so that in theory it could support more than 127 keys. In addition, the scan codes issued by the arrow keys are dependent on the state of NumLock. We will not consider the extra complications associated with this new keyboard again. When you hit or release a key, the microprocessor on board the keyboard sends a signal into the computer that activates the interrupt controller chip which calls int 9 in the CPU. The CPU then shifts into the built in BIOS routine. Actually, there are probably several onlooker TSRs that first look at each keystroke but let's ignore them for the time being. The first thing that the BIOS does is to read the keyboard "port" for the keyboard is primed to report the scan code of the key hit if a key was hit or 80H plus the scan code if a key was released. The keyboard will report this information whenever asked until it is reset which is done at the end of the keyboard routine. What the BIOS now does, depends on the key hit or released. If the capslock was the key hit, it will toggle the bit that keeps the capslock state; if a shift was hit, it will adjust that bit and if the shift was released it will adjust the bit back. If a letter key was hit say "A", it will check whether there is room in the buffer for another keystroke and beep if there isn't. If there is, it will proceed to place two bytes in the buffer. The first byte is Chapter VI:ADVANCED TOPICS Page 77 Documentation for STACKEY, Version 3.0 the "scan code" which is usually but not always the actual hardware scan code. The second byte is the ASCII code. For the "A" key, it will place the actual hardware scan code 1EH as the scan code. To figure out the ASCII part, it will look at the state of the shift keys and of Capslock. If "a" is intended, it will place ASCII code 61H, if "A" then 41H, if ^A then 01H and if Alt-A then 00H. This is typical: if there is no ASCII code associated to the key (Ctrl-A is a perfectly good ASCII character but Alt-A is not), then an ASCII code of 00H is placed. In that case, the "scan code" is called "extended ASCII code" or "second ASCII code" - both terrible names since it has nothing to do with the ASCII scheme. The hardware scan code for <F1> is 3BH. Since none of the shifted F1 keys has an ASCII equivalent, BIOS places an ASCII code of 00H in as part of the word placed in the buffer for those keystrokes. If it always put the actual hardware scan code of 3BH into that half of the word, the computer wouldn't be able to distinguish F1, Shift-F1, Alt-F1 and Ctrl-F1. So what does BIOS do? It makes up "scan codes" as follows (!): F1 3BH S1 54H A1 68H C1 5EH These codes were picked for the original PC where there were 84 keys with codes from 00H to 53H. Thus 54H wasn't a real scan code but on an AT, it is the scan code for the <SysReq> key! It doesn't matter since the SysReq key doesn't put anything in the buffer. The "scan code" for Ctrl-PgUp is 84H which is the hardware scan code issued when you RELEASE the top row <3> key. The point is that the "scan code" half of the what is put in the buffer is usually but not always the hardware scan code. If the key struck is on the keypad, there are extra complications, not only because of the numlock but because of the special meaning of the Alt-numeric keypad. We won't discuss the details of how that is handled but once you indicate that you want to put in an ASCII 200 say (lower left handle double corner), it is put in with a "scan code" of zero. That is if the scan code is zero, that indicates something put in via the keypad. So the <+> (ASCII code 2BH) can normally get put in the buffer with one of 3 different "scan codes" - 00H if you use the Alt-keypad and press <4> and then <3> with alt depressed, 0DH if you use the top row and 4EH if you use the grey plus. Since both halves of the word are in the buffer, programs can distinguish between the two pluses if they Chapter VI:ADVANCED TOPICS Page 78 Documentation for STACKEY, Version 3.0 wish. We have not discussed how typematic fits into all this (typematic is the name for the key repeat function that goes into effect when you hold a key down). Given that int 9 tells BIOS when a key is released as well as hit, you can imagine how BIOS by combining int 9 and the timer interrupt can produce this effect. There is an important point to be made here. Certain special combinations cause the BIOS to jump to special routines. For example, if you hit <Del>, the BIOS checks to see if Ctrl+Alt are down and if so it jumps to a special routine with which you might be familiar. First, it is quite possible for a program to intercept int 9 and disable Ctrl-Alt-Del! Secondly, STACKEY can only mimic a Ctrl-Alt-Del, because we know exactly what the machine does when you press Ctrl-Alt-Del. Perhaps, your clone is set up to play the star spangled banner when you hit Ctrl+Alt+$. Unless we know what action it is taking, there is no way we can mimic that. We do try to mimic the Ctrl+Alt+G+/- speed switch since there is a standard routine that many clones use to change the speed but if your clone uses something else, there is nothing that we can do mimic that! Why not just simulate hitting G+ with Ctrl+Alt depressed. The problem is that while we can place strokes in the buffer, steal ints or set off custom routines, there is no way (at least no way known to us!) to steal the keyboard port and simulate the hitting of as key under int 9. VI.4 Keyboard basics: int 16/DOS service 8 Int 9 places strokes in the buffer. Application programs normally get the strokes out with int 16H (henceforth we'll drop the H from that) or by using DOS service 8 which actually calls int 16 itself. Before calling an int, programs can place a number in the AH register of the CPU which tells the int which service to use. Thus the expression "service 8 of DOS" means invoking the DOS interrupt (int 21H) with ah=8. Int 16 has several services including one (service 2) that tells a program the state of the shift keys (most programs directly look at byte 417H), one that tells the program whether there are any keystrokes to waiting to be processed (service 1) and one (service 0) that returns the next keystroke in the buffer, waiting for a stroke if there isn't one there. If int 16, service 0 is called, then when control is passed back to the application program, ah contains the "scan code" part of the next keystroke and al the ASCII part. The application Chapter VI:ADVANCED TOPICS Page 79 Documentation for STACKEY, Version 3.0 program is perfectly able to distinguish top row plus and grey plus, for example. DOS service 8 calls int 16 and proceeds to throw some of the information away! Only the ASCII part of the code is returned to the calling program. If this ASCII code part is zero (corresponding to a key combination which doesn't correspond to an ordinary ASCII code), then and only then, can the program get additional information - if DOS service 8 is immediately called again, the scan code part is returned which explains why it is called "second ASCII code". Using the DOS service, a program cannot distinguish the top row plus and the grey plus. Why use the DOS service instead of int 16? About the only virtue is that you can redirect input and have the input used if you call the DOS service 8. There are many disadvantages. Why do some programs still persist in using the DOS service? For some, it is a holdover from the era of MS-DOS machines; these were not 100% IBM compatible machines. The idea was that while these machines might have a somewhat incompatible BIOS, they'd react properly to the DOS call. For some, it is because their compiler insists on calling DOS. Ironically some compilers (Turbo Pascal is an example!) mimic the behavior of the DOS call and it is recommended that with such compilers, you include your own int 16 routine for getting keyboard input. Most programs that flush the keyboard buffer, do it by calling int 16, service 1 and seeing if there is a keystroke waiting. If there is, then they call service 0, get the keystroke and ignore it. They then loop until they are told by service 1 that no keys remain in the buffer. In principle, a program could bypass int 16 and directly remove strokes from the buffer. Fortunately no programs do so (as far as we know), since such programs will have a tendency not to work with keyboard macro programs. But some programs completely ignore int 16 and have their own keyboard handlers replacing both int 9 and int 16 and the BIOS buffers. SMARTCOM II is a good example of this. If you use STACKEY before loading SMARTCOM, you'll find that the keystrokes don't get acted on by SMARTCOM but appear on the screen when you exit. This is because STACKEY places strokes in buffer where SMARTCOM ignores them but they get read when you exit SMARTCOM. There is nothing that can be done to get STACKEY to work with a program like that. Chapter VI:ADVANCED TOPICS Page 80 Documentation for STACKEY, Version 3.0 VI.5 Keyboard Basics: How other programs work To understand how STACKEY works, it is useful to have some idea of how various kinds of other programs work. Keyboard macro programs generally have two distinct parts - one that enhances int 9 and the other enhances int 16. The int 9 enhancement allows the macro program to react to strokes like Ctrl-Up which BIOS ignores. (Actually, the BIOS with the enhanced keyboard does interpret Ctrl- Up so this statement is only true of the older BIOS.) Each macro program has a different set of codes used for these non-BIOS keystrokes - alas there is no standard - but the well known ones all put a word in the buffer corresponding to these strokes. Then their int 16 module looks at what the "real" int 16 is about to report - the older BIOS would pass these strange words through. Since the macro program worries that the calling program won't know what to make of this non-standard code, if you haven't made Ctrl-up into a macro, the macro program will eat the non-standard code. If the key is a macro key, then the macro program will return the strokes in the macro as int 16 is successively called. Typeahead buffer extenders typically work by seeing if the buffer is about to fill and if so they remove the stroke from the buffer and place it in their buffer. Depending on how they are implemented they'll continually take out and put in the last stroke in the buffer or all of them. Several programs promise to improve on BIOS' typematic by eliminated the dreaded "cursor overshoot" (oh horrors!). If you hold down the arrow key when your application program isn't ready or in a situation where it can't process strokes fast enough, then BIOS will fill the buffer with the code for that arrow key. The more intelligent typematic programs place the extra strokes in not by using the buffer but by stealing int 16 and responding that there is an arrow key ready. In this way, they'll give strokes just at the rate that the application can take it and you'll get "stop on a dime" behavior. VI.6 Keyboard basics: How STACKEY works (or doesn't) STACKEY's most basic function is to simulate the entering of ordinary keystrokes. It does this by placing them in the buffer. When smart or impatient processing is in effect, STACKEY checks every clock tick and if it has keystrokes waiting to be placed in Chapter VI:ADVANCED TOPICS Page 81 Documentation for STACKEY, Version 3.0 the buffer, it places as many as it can without overfilling the buffer. If there is no room, it will do nothing. If your application can process them that fast, STACKEY can place as many as 18.2*15=about 270 keystrokes per second in the buffer. However, STACKEY doesn't prevent int 9 from being processed in the middle, so if you hit a key, it may wind up in the middle of the playback. The non-resident part of STACKEY keeps a translation table to tell it what each special symbol keystroke and letter corresponds to and it just places the corresponding words in STACKEY's internal buffer. So you understand why each "keystroke" takes two bytes and the 128 keystroke default buffer is 256 bytes. STACKEY reserves the "scan codes" E0 and above to tell it that a special command is in the buffer, like a delay or repeat. However, XF012 would still work; it would place a word F012 in the keyboard buffer but the intermediate codes in STACKEY's buffer wold take a third byte to warn STACKEY that the F0 wasn't a command. Since STACKEY is only simulating the result of hitting a key rather than the hitting of the key itself, custom routines are needed to simulate each "keystroke" that doesn't place a key in the buffer. Since BIOS does nothing when Ctrl-Up is hit, STACKEY has no primitive command for Ctrl-Up. If your macro program or application program gives meaning to this stroke it is probably by placing its own idiosyncratic code in the buffer. If you can find out what codes it is using, you can simulate them with the Xnnnn command. (For some macro programs, CTRLALT PLUS' ^@R command or CTRLALT's ^@T which reports on what int 16 is saying will let you see what codes your macro program is using.) STACKEY simulates a shift depress by saving the byte at address 417 and changing it for the specified number of ticks to the requested value and then it restores the original value. Programs that pop up on the shift keys do so by checking byte 417 each tick so they will get fooled by STACKEY. In principle a program could popup on Alt+LShift by sitting on int 9 and seeing if the key hit is Alt or LShift and then checking whether the complementary shift is depressed. The only programs we know of that do this are in the SWAPxx series and they do not pop up on STACKEY's SH command - fortunately as Tesseract programs, you can use the TE command instead. There is an extra complication with the SH command that you should be aware of. Suppose that you have a SH(AL,18) stacked and you have the Alt key depressed when the processing of the SH command begins. But during the processing of the SH command, you Chapter VI:ADVANCED TOPICS Page 82 Documentation for STACKEY, Version 3.0 remove your finger from the Alt key (18 ticks is a full second after all). When STACKEY restores the initial state of the shifts, it will restore the Alt key down bit and even though your aren't depressing the Alt key, the keyboard will act as if you are! Pressing and releasing the Alt key should cure this problem, which fortunately should be rare. STACKEY's hotkey processing is done on int 9. Thus if you have used a keyboard mapping program and changed the keytops, STACKEY for its hotkeys will be sensitive to the original meaning of the keys, not their remapped meaning. For example, on an AT you might physically interchange the <Esc> and <`/~> keys and use a program like FANSI CONSOLE to correct for the action of the keys. However, if you want Alt-<Esc> to be the H+ hotkey (where by <Esc> you mean the key currently marked <Esc>), you'll need to use stackey H+(A,"`") since a keyboard mapper can't fool programs that sit on int 9 and STACKEY's int 9 handler doesn't know that you've swapped keytops. Above, we described how program tend to flush the buffer. If you have 100 strokes in the STACKEY buffer, the way STACKEY works by default, those strokes will all get cleared out by many such schemes (although if the program is doing things quickly enough, it may clear out the BIOS buffer and find that empty before the next clock tick when STACKEY will refill the buffer). You should be able to figure out why the PH keystroke will fool such flushers. Some programs, flush the buffer after getting any keystroke, disabling type ahead! You should be able to understand why patient processing will normally deal with such programs. You'll find that you have to fine tune STACKEY in many ways to get it to overcome some strange scheme that a program has to flush the buffer or otherwise force you to do things its way. It is unfortunate that programs work that way but if all programs worked properly, you wouldn't have much need for STACKEY - they would allow you on the command line to do what you must make a STACKEY script to do instead. When a difficulty does occur, it may pay to try to use the knowledge in this tutorial to figure out what is going on. We hope that the tools we have provided in STACKEY will let you overcome the difficulty. If they don't, please let us know so we can attempt to add even more flexibility to STACKEY to let it solve those problems. Chapter VI:ADVANCED TOPICS Page 83 Documentation for STACKEY, Version 3.0 VI.7 Inline: Syntax Important note: STACKEY's INLINE code is powerful but dangerous and should only be used by those adept in assembly language programming. When experimenting, act the way you would if you were debugging an assembly language program. Be careful to be in a situation where a crash wouldn't lose any work. The syntax for inline code is: STACKEY IL(xx/xx/xx/xx/xx) where xx are hex numbers from 00 to FF. The hex digits A-F can be either uppercase of lower case; do not add an explicit H. When this set of commands is reached in the STACKEY script, that sequence of bytes will be executed as a sequence of machine language instructions. Before they get issued, STACKEY pushes the ax,bx,cx and dx registers and when the code is done, it issues a RET instructions and then it pops these registers. Thus the IL code can freely use the ax,bx,cx,dx registers and it can also use the si,ds and es registers. Before using any other registers (bp,di,sp,ss,cs), be sure to push them and subsequently pop them. It is important that you note that STACKEY appends a RET instruction to the IL code so need not add one yourself; you cab use a RET but do not use an IRET or a FAR RET. When your code is called, cs=ds=the resident code's segment and es=40H, the BIOS data area. Moreover si points to the offset of the first instruction; see below. The 6 byte area ds:42H- ds:47H is available for user data storage; below methods are given for additional storage if you wish. The word at ds:40h is the segment of the screen (B000 or B800). THE CODE MUST BE FULLY RELOCATABLE. RELATIVE JUMPS ARE FINE BUT ABSOLUTE JUMPS ARE NOT. STACKEY does not have its own stack but uses the underlying programs stack. If you have a need for a large stack (only relevant if you are using an external command), you'll need to set one up in your inline code. To do this you might need to get access to the absolute position of your code. One way of doing this is to use the following inline fragment: \E8\00\00\58\ (which translates as call $+3 pop ax) will place the address of the 58 instruction (relative to CS:0000) in the AX register. Another way is to use the fact that si points to Chapter VI:ADVANCED TOPICS Page 84 Documentation for STACKEY, Version 3.0 the initial instruction when your inline code is loaded. So you could get a data or stack area with jmp short overdata ;or, jmp short $+10 for 4 words data dw 0,0,0,0 overdata: ... ... mov [si+2], ax ;si+2 points to beginning of "data" Be warned that if you use this idea (or the special value of es) in external files, you will not be able to debug them from DOS since DOS loads com files with si=00 and es=cs. A STACKEY inline call of n bytes takes n+3 bytes of buffer space (recall that a "keystroke" takes two bytes) including the final ret. And the resident code to implement inline instructions takes only about 50 bytes! VI.8 External: Syntax STACKEY also has a command to allow you to stack a compiled com or bin file in the place of an inline string. The syntax is stackey EX(filename) where filename can include a drive and or path if you wish. You may use any extension that you wish but it must be included as part of the name. The file MUST end in a RET instruction (and not in a call to DOS service 4C, for example) and obey all the rules for inline code except the rule about no final RET (we save the inline writer from having to add the RET by hand but for testing COM files, we assume you'll want the RET on the external file). STACKEY will complain if there is no final RET instruction. An EX command to a file of n bytes ending in ret is completely equivalent to an IL command of the n-1 bytes preceding the RET. The size of the external file is only limited to the size of STACKEY's buffer. Since an EX command requires an extra file, we'd imagine that you'll use EX while debugging and then translate it to IL code unless the code is too long to fit as IL on the DOS command line. Chapter VI:ADVANCED TOPICS Page 85 Documentation for STACKEY, Version 3.0 VI.9 Inline and External examples Here are some examples of how to use IL: Example 1. Pure Illustration STACKEY SC(hi) IL(b8/7/e/cd/10) ' Hello to you too.' The IL code is for mov ax,0E07H int 10H In this example, STACKEY will scan for the word "hi" and the IL code will issue a BIOS beep (service E of int 10 with a character of ^G) and then answer you back. Example 2. Hide the cursor STACKEY IL(b4/1/b9/0/20/cd/10) This is equivalent to mov ax,1 mov cx,2000H int 10H and will hide the cursor in real time. Example 3. Wait for a keystroke and eat it. STACKEY IL(31/c0/cd/16) equivalent to xor ax,ax int 16H Example 4. Send a FF to the printer. STACKEY IL(ba/00/00/b0/OC/cd/17) equivalent to mov dx,0 mov al,0CH Chapter VI:ADVANCED TOPICS Page 86 Documentation for STACKEY, Version 3.0 int 17H Example 5. Getting and restoring the shift status STACKEY IL(26/A0/17/00/3E/A2/42/00/26/C6/06/17/00/0A/... 3E/A0/42/00/26/A2/17/00) translates to mov al,es:[17h] ;get shift states - es=400 mov ds:[42h],al ;save it mov byte ptr es:[17h],0ah ;set alt-shift and after some intermediate code mov al,ds:[42h] mov es:[17h],al ;restore Example 6. You could write your elaborate resident program accessed by one of the user interrupts and call it up with STACKEY inline code calling that interrupt. Example 7. Flash the screen This involves the sample code flash.asm and its compiled bin file flash.bin. What it does is XOR all bytes in screen memory with 07F, count to 64K and XOR back. The effect is to flash the screen so stackey :1 w5 ex(flash.bin) be j1 will get your attention that a process has stopped; use the H! hotkey to flush out those instructions. Example 8. Play music Music.asm is source for the file gavotte.bin which will play a Bach gavotte with stackey ex(gavotte.bin) There are also a Monteverdi piece (montev.bin) and for the really highbrow pop goes the weasel (pop.bin). Music.asm is a shell and you can use it to write your own external music files. You might try stackey :1 ex(gavotte.bin) WH j1 which will play the gavotte whenever you hit the H+ hotkey. Of course, you won't be able to use STACKEY for anything else. Example 9. Messages The shell makemess.asm is source code for sample.msg but has directions for modification. By jumping to labels called label1, Chapter VI:ADVANCED TOPICS Page 87 Documentation for STACKEY, Version 3.0 label2, etc in this source code, when run the external file will jump to STACKEY labels 1, 2, etc. The sample file jumps to label 1 if you hit Y and label 2 if you hit N. Thus the command STACKEY ex(sample.msg) :1 be 'yes' j0 :2 'no' will pop up a message box and either beep and enter the string 'yes' through the keyboard if you answer Y or enter the string 'no' if you enter N. Notice since there is no label 0, j0 exits the command line. Example 10. Disable/Reenable the keyboard This example is potentially very dangerous! The following code will disable the keyboard: stackey IL(B0/AD/E6/64) and can be used in scripts where you want to be sure that the user will not interupt. Only use it after you have thoroughly debugged the rest of the script. To reenable the keyboard use instead stackey IL(B0/AE/E6/64). However, be warned that some keyboards will save up keystrokes while disabled and issue them when reenabled. For this reason, you may want to also flush the keyboard as well as reenable it. An external program flush.bin is provide that does this or you can use stackey IL(B0/AE/E6/64/33/C9/E2/FE/B4/01/CD/16/ 74/06/32/E4/CD/16/EB/EC) VI.10 STACKEY's API To talk to application programs, STACKEY takes over some unused int 16 services. All calls require AH=CA (that's CA Hex but think of it as the initials of CTRLALT Associates; CTRLALT PLUS' API also uses int 16 but with other values of BX and CX). It is also required that BX=CX=736BH ('sk'). AL must be one of 0, 1 or 2 and this value indicates the "service number" below. Any other values of AX,BX,CX will be passed on by STACKEY. Three bytes of user stack are used in addition to the 5 required by an interrupt. If STACKEY services an API call, it ALWAYS RETURNS AX=CAFF BX=Code segment of SK CX=Version of SK (CH=major,CL=minor) The API is only applicable for version 3.0 and later of STACKEY. Chapter VI:ADVANCED TOPICS Page 88 Documentation for STACKEY, Version 3.0 Here are the STACKEY API services: service 0: Are you there? Returns: DX=Words free service 1: Put word in buffer DX=word to place in buffer Returns: DX=number of words remaining in buffer if successful, FFFF if unsuccessful. [The only reason for unsuccess is a full buffer.] service 2: Flush STACKEY and BIOS buffers Chapter VI:ADVANCED TOPICS Page 89 Documentation for STACKEY, Version 3.0 Chapter VII:ASSOCIATED PROGRAMS VII.1 FILEKEY A separate program called FILEKEY is included which lets you read an entire file into STACKEY's buffer. STACKEY must be loaded in memory before FILEKEY is invoked or else you will get an error message. The syntax is filekey <filename> where filename can include a drive and/or path. The file read by FILEKEY should be a standard ASCII file. FILEKEY reads the file into the stack as literal keystrokes with each CR/LF pair (line ending) replaced by a CR. A final CR is automatically included (but see below). Thus the two line ASCII file (NOTE: FILEKEY does not ignore leading blanks; for typographical reasons we indent the examples but we describe what would happen if the file lines began in column 1): Now is the time for all good men would be read by FILEKEY as if the command stackey "Now is the time"CR"for all good men"CR were entered at the DOS command line. $ plays the role of a special escape character in the processing by FILEKEY. If the $ is followed by any character, but ; or another $, then the $ gets passed through in the usual way. "$;" tells FILEKEY to ignore the remainder of the line and not place a CR at the end of that line. Thus, to avoid having a CR stacked at the end of the final line end the file with $;. For example, the following file would be equivalent to the last STACKEY example: Now is the $; time $;this is a comment for all $; this is another comment good men $$ tells FILEKEY to toggle to a mode where it reads the file as if it were STACKEY reading a command line with five exceptions: $$ is no longer interpreted as a single $ lines are automatically wrapped; i.e. a literal CR/LF (but Chapter VII:ASSOCIATED PROGRAMS Page 90 Documentation for STACKEY, Version 3.0 not the letter CR or LF) is ignored. utilities mode cannot be called from a file /../ commands cannot be issued permanent palette changes cannot be made $$ will toggle back to the default mode. Thus the following file is also equivalent to the last STACKEY example: Now is the time$$CR$$for all good men$$CR$$$; The final $$$; is unnecessary. If you want to imbed $$ in the stack from a file, use $$"$$"$$ and similarly for $;. Note that [] color changes are allowed in FILEKEY's $$-mode but not permanent palette changes. This is because the permanent palette changes are utilities. SC, SS, SH, EX, and IL are all allowed commands after toggling with $$. Hotkey changes are also allowed in $$-mode. If you use FILEKEY for large scripts you may find that STACKEY's limitation of 10,000 keystrokes in the buffer is insufficient (it surprised us when we got requests for a large buffer but we did from several sources!). Note that with SKRES, you can load STACKEY with a buffer size of 30,000 bytes, see Section III.12. Filkey itself is limited to reading in files of no more than 54,000 bytes. VII.2 EGAPAL and VGAPAL The EGA and VGA allow one to keep permanent palettes and non- standard fonts in tables in RAM. By default, they are stored in ROM but by moving those tables to RAM, one can set permanent palettes different from the default. Permanent here does not mean surviving rebooting, only surviving a change of mode. Included with STACKEY are programs that move these permanent palettes. You can only use STACKEY's permanent palette setting with the supplied EGAPAL, VGAPAL or with the commercial program ULTRAVISION. EGAPAL replaces the DWORD1 program supplied with STACKEY 2.0. Please use EGAPAL rather than DWORD1. EGAPAL will refuse to load with a VGA - DWORD1 will load but should not be used. Instead, use VGAPAL. Chapter VII:ASSOCIATED PROGRAMS Page 91 Documentation for STACKEY, Version 3.0 If you are not running any other EGA/VGA specific programs that use palettes or fonts, you need just run EGAPAL or VGAPAL in your AUTOEXEC.BAT and forget about it. You'll then have access to the permanent palette setting. DO NOT REMOVE EGAPAL FROM MEMORY WITH old versions of MARK/RELEASE WITHOUT FIRST RUNNING "EGAPAL Q" AS DESCRIBED BELOW. If you ignore this warning and you are using these early versions of MARK/RELEASE, you will crash rather spectacularly although we think that you will not hurt your monitor. The more recent versions of MARK/RELEASE and CTRLALT PLUS' ^@<F9>Y command automatically restore the DWORD1 pointer that EGAPAL/VGAPAL change. The first time that you run EGAPAL, it remains resident taking 1600 bytes of RAM most of it in the tables (1472 bytes) that store the palettes. VGAPAL takes 224 bytes. In addition to this memory, memory will be taken for a copy of your current environment (see BATUTIL documentation, Section V.1). If EGAPAL/VGAPAL finds that it is not already in memory but another EGA/VGA is, it will refuse to load. Load EGAPAL/VGAPAL first and use the Q and R parameters. If EGAPAL/VGAPAL is run with no parameters (or with any parameters other than Q or R) it will look for itself in memory. If it finds itself, it exits with a message: "EGAPAL already loaded". Otherwise it loads itself as described above. When EGAPAL loads, it saves the EGA/VGA address that were there before it loaded. Running egapal Q (for Quit) will put these addresses back to what they were before EGAPAL loaded. Running egapal R (for Restore) will put these addresses back to what they were after you initially ran EGAPAL. If EGAPAL is run with one of these parameters and EGAPAL does not find itself in memory, it will exit with the message: "EGAPAL not loaded". When looking for parameters, EGAPAL stops after the first one so it doesn't matter what appears after the first R or Q. Any number of spaces, tabs or /'s can occur between 'egapal' and the Q or R. There are some programs (Microsoft CODEVIEW is an example) which react badly if the save_ptr region is in RAM. Assuming that you loaded EGAPAL when save_ptr was pointing towards ROM, you need Chapter VII:ASSOCIATED PROGRAMS Page 92 Documentation for STACKEY, Version 3.0 only run egapal q before such programs and egapal r afterwards. Do this also to use another program that is EGA/VGA specific and insists that it be loaded first. VII.3 Demonstration BATch files The STACKEY package comes with four demonstration BATch files to illustrate some of STACKEY's features. You should run them (at least the appropriate ones for your monitor) and then study them to see how they work. SOUNDS.BAT illustrates the BEEP command. You should also look at BATUTIL's SOund command and soundemo.bat. CGACOLOR.BAT shows you how the L and P commands work on the CGA. The full illustration of the L command requires the small stand alone program BOXES.COM to be in the default directory. You should only use it with a color monitor. COLOR.BAT and SEECOLOR.BAT illustrate the temporary palette setting on the EGA. Both take parameters. COLOR will cycle through all 64 colors on the EGA. With no parameter or an improper parameter, it displays a message and then runs the file with a default parameter value of 1. The correct parameter is a single integer. If the parameter is n, there is a pause of n/2 seconds between color changes. If you find the switching time too short with the default try n=3 or 4. SEECOLOR will let you see any color or several colors. You enter seecolor p1 p2...pn where each parameter is either a number (from 0 to 63) or a subset of RrBbGg and those colors will be displayed in order with a pause for keystroke in between. If an illegal parameter is entered, the BATch file will abort with an error message. In addition to the basic commands they illustrate, these BATch files show other features of STACKEY. For example, you Chapter VII:ASSOCIATED PROGRAMS Page 93 Documentation for STACKEY, Version 3.0 should study how COLOR.BAT and SEECOLOR.BAT use redirection to nul and errorlevel to recover from command line errors. And all the files except SEECOLOR make use of the wait command to control the timing of the BATch file. The possibility of doing arithmetic on STACKEY's input parameters, discussed in the usage notes, is illustrated in COLOR.BAT. Chapter VII:ASSOCIATED PROGRAMS Page 94 Chapter VIII:MISCELLANY VIII.1 Usage notes STACKEY checks its numeric input and normally gives an error message Number out of range if an integer is given over 64K or a number below 256 is required but one larger is given by the user. Colors which are supposed to be in the range 0 to 63 are reduced mod 64 so long as they are less than 256. Any place where STACKEY expects an integer, you can place a product by using a *. Thus, "W2*35" will be interpreted as "W70". Thus if you want to accept input from a user in a BATch file in seconds rather than clock ticks, you can use "W18*%1". In addition you can use + and - with multiplications done first. For example, the timed waits in COLOR.BAT are arranged to run for 64*%1 (the time to show the 64 color changes) minus a fixed amount to take into account the time it takes for the color change commands to load. Note that while DOS normally interprets >,< and | as redirection commands, if enclosed between double quotes, it gets passed as part of the commands line, so these symbols can be stacked by placing them between double quotes (but not between single quotes). If you prefer, you can use the $g,$l and $q metastrings. You can use stackey to make a batch file that will change the date and time of a file to one you specify. The following redate.bat file has the syntax: redate <filespec> to change the date and time to the current one and redate <filespec> date time to the specified date and time. <filespec> can include wildcards: echo off cls if "%2" == "" goto nodate stackey $tCR if "%3" == "" goto notime time %3 :notime stackey $M"-"$D"-"$YCR date %2 :nodate for %%a in (%1) do copy/b %%a+,, if "%2" == "" goto morenoda Chapter VIII:MISCELLANY Page 95 Documentation for STACKEY, Version 3.0 if "%3" == "" goto morenoti time :motenoti date :morenoda The stacked date and time restore the current values (your clock will lose a few seconds). One of the annoyances faced by DOS users is the seeming inability of automatically answering "Y" to "Are you sure (Y/N)?" in a BATch operation where you are issuing a del *.*. Actually, one can do this with DOS via: echo Y|del *.* and we recommend that, but it may be illuminating to discuss how to do this with STACKEY. The commands stackey "Y"CR del *.* will not work because DOS flushes the buffer and the characters are lost. Nor does stackey PH"Y"CR del *.* work because DOS doesn't ask for a keystroke until one is in the buffer. This illustrates our point that PH only works in limited situations. But stackey WR"Y"CR del *.* does work. And stackey W18"Y"CR del *.* works properly and you can probably decrease the 18 to 7 or 8. A more sophisticated method that works is stackey /up/"YY"CR del *.* stackey /o/ After the flags are pUshed for later pOpping, patient mode is turned on. The first Y which could be anything is flushed by DOS but then the second one is entered. If you have gone to command mode in a FILEKEY file and include a ";", the entire rest of the file will be ignored. This is consistent with the STACKEY usage. To add remarks, use $$$; and then remember to begin the next line with a $$ if you wish to remain in command mode. Processing also halts if FILEKEY comes across an ASCII 0 (NOT the number 0) in your file. Chapter VIII:MISCELLANY Page 96 Documentation for STACKEY, Version 3.0 We recommend that you include STACKEY with the default buffer size in your AUTOEXEC.BAT file. If you later need a large buffer size, you can load a new copy with the /Rxxxx/ command. Ideally you should use a program like Mark/Release to remove this second copy when finished in which case STACKEY will revert to using the original copy. You might want to also consider issuing some permanent palette change commands in your AUTOEXEC.BAT immediately after loading EGAPAL or VGAPAL. Do NOT use the version of FILEKEY distributed with STACKEY version 1.0 or 2.0 with this version of STACKEY. STACKEY finds itself in memory using the API and not the actual name so you can rename it to any convenient name you wish such as sk.com so long as the extension remains com. STACKEY's help uses a built in version of the CTRLALT Associates' MAKEDOC program currently under development. This is a shareware program that will let you make resident or non-resident executable display files. You can remove STACKEY.HLP if you are short for space. When you ask STACKEY for help, it looks in the current directory and then throughout the path to find STACKEY.HLP and if it is not found, STACKEY will display an error message. VIII.2 Also by the same authors STACKEY was developed by Barry Simon and Richard M. Wilson. Simon and Wilson have formed CTRLALT Associates to market their software. They are committed to the idea of shareware and both are founding members of the Association of Shareware Professionals. At the time of this release of STACKEY, CTRLALT Associates has two free programs and several other program under development: CTRLALT PLUS is our flagship product extending the popular free program CTRLALT. CTRLALT PLUS is expected to be released in 1990. It is a set of resident utilities including extensive cut and paste, a calendar, programmer's utilities (resident tables, emergency exit), two monitor support, a resident file viewer, dialer, calculator, color control and resident printer control. Chapter VIII:MISCELLANY Page 97 Documentation for STACKEY, Version 3.0 CTRLALT PLUS and STACKEY/BATUTIL are shareware and can be registered with Support Group, Inc. (see Section I.3). BIGECHO is a simple program which allows a BATch file to display characters which are 8 rows by 8 columns. Version 1.0 was released in September, 1986. It is available on many BBS systems and from some disk vendors. Most of its features are subsumed in BATUTIL. Chapter VIII:MISCELLANY Page 98 Documentation for STACKEY, Version 3.0 Appendix to Chapter VIII Here is a quick summary of the STACKEY command line syntax: - ? will give help - _ will send the remainder of the line to standard output - Place text inside single or double quotes - F1-F0,F-,F=; S1-S0,S-,S=; A1-A0,A-,A=; C1-C0,C-,C= for function keys - @x or (x for Alt-x where x=letter or number - ^x or ~x for Ctrl-x where x=letter or number (NOTE: @number for top row numbers; ^number for keypad) - LA,RA,UA,DA for arrow keys - PU,PD,HM,EN for Page Up/Dn, Home, End - IN,DE for Insert/Delete - N0,...,N9,N. for numeric keypad numbers and decimal point - G+,G-,G* or N+,N-,N* for Grey keys - PS for PrtSc - CP for Ctrl-PrtSc, CB for Ctrl-Backspace - TA or TB for Tab; ST or BT for Shift Tab - ES,BS,SP,CR for Escape, Backspace, Space, Enter - FF, LF for form feed (^L) and Ctrl-Enter - DQ,SQ for " and ' - PH and WR for two kinds of "phony keystroke" - +/-N,+/-S,+/-C,+/-I to turn On/Off Num, Scroll, Caps Lock, Insert - SH(X,nnn) with X a subset of CALR simulates shifts for nnn ticks - CA invokes CTRLALT PLUS - Qn switches to Carousel partition n - Dn with n=1 or 2 invokes Desqview main menu - TE(idstring,keyid) for Tesseract programs - Z+/- clone speedup/slowdown - P-/+ to disable, reenable Shift-PrtScrn - BE for BIOS beeps - MP(msg), ME(msg) for popup messages - $x or *x for prompt metastrings with SEND extensions (see below) - \nnn with nnn=decimal number for Alt-keypad entry - Xhhhh with hhhh=hex word for direct hex entry - #nnn or )nnn to repeat the next keystroke nnn times - Wnnn to insert a delay of nnn ticks (18.2 ticks = 1 sec) - Mnnn to insert a delay of nnn minutes - SC(string) to scan at cursor position - SCn,m(string) to scan at absolute position - SS(string) and SSn,m(string) to scan silently Chapter VIII:MISCELLANY Page 99 Documentation for STACKEY, Version 3.0 - WB pause script until buffer is empty - WH pause script for restart hotkey - WK pause script for any key Convention: X=subset of CALR; Y=single keystroke like "a" or F1 - WS(X,Y) pause for specific key - H!(X,Y) resets flush buffer hotkey (default=AL,!) - H*(X,Y) resets flush scan hotkey (default=AL,G*) - H-(X,Y) resets stop hotkey (default=AL,G-) - H+(X,Y) resets restart hotkey (default=AL,G+) - CL,NL,SL,SR CapsL, NumL, ScrollL, SysReq for hotkey only - ! to flush buffer - ; to stop reading command line (for comments) - /Bnnnn/ to change buffer size on initial loading - /Rnnnn/ to force extra loading with new buffer size - /i/ /s/ and /p/ for impatient, patient, smart processing - /t/ and /n/ to turn test mode on and off - /c/ and /d/ to turn continue mode on and off - /u/ and /o/ to push and pop the s,t,c flags - /?/ to query the s,t,c flags - Ln to set coLors on the CGA (n=0,...,15) - Pn to set palette on the CGA in mode 4 (n=0,1) - [c=nn] to map color number nn to slot c on the EGA - [#m;c=nn] to do the map in the permanent table for mode m #A:All palettes #T:Ultravision, text modes only #U:Ultravision - +/-B to turn blinking on/off on the EGA or VGA - IL(xx/xx/xx/xx) InLine command (USE WITH CAUTION!) - EX(filename) External inline (USE WITH CAUTION!) In summarizing utilities mode, minimal truncations are capitalized. Only use the leading capitol letter for x. - {BOOT} or {REBOOT} for a warm reboot - {BOOT=C} or {REBOOT=C} for a cold reboot - {MONitor=x} x=Color,Mono,Switch - {Prn} to switch LPT1 and LPT2 - {COmm} to switch COM1 and COM2 - {CUrsor=x} x=+/- to turn standard cursor on/off - {CUrsor=n,m} to put cursor on scan lines n through m - {CPosition=n,m} to move the cursor to row n, column m - {MODe=n} switch to allowed video mode - {LInes=n} n=25,43(50) to shift modes on the EGA (VGA) - {LO=xy} where x is + or - and y=N,S,C or I to toggle lock keys - {Wait=nnn} Real time pause of nnn clock ticks; n between 1 and 32K Chapter VIII:MISCELLANY Page 100 Documentation for STACKEY, Version 3.0 - {Until=HH:MM} Real time pause until time HH:MM - {DUMPP} to do a screen dump to printer - {DUMPF=x}, {DUMPL=x} to append screen to file with filespec "x" - {DUMPOF=x}, {DUMPOL=x} to overwrite screen to file - {HALT} stops batch file with ^C - {Keywait}, {Enterwait} pause for input - {Abortwait}, {~abortwait} pause for input to abort - {BEep=nn,mm} nn = inverse pitch, mm = duration PROMPT metastrings and extensions: - $v = DOS version - $t = time in HH:MM:SS.hh format - $n = current drive - $T = time in HHMM format - $p = current path - $H = hour from 0 to 23 - $P = current path with \ - $d = date in DAY MM-DD-YYYY - $$ = the character $ - $M = month in MM format - $g = the character > - $D = day in DD format - $l = the character < - $Y = year in YY format - $q = the character = - $W = day of the week - $h = the character bks - $E = date in English - $b = the character | - $e = the character esc - $_ = CR/LF FILEKEY has the following conventions: - default interprets as pure text - $$ toggles between pure text and STACKEY command mode - $; in text mode suppresses CR and remainder of line Chapter VIII:MISCELLANY Page 101 INDEX abortwait 73 errorlevel 71 Alt key combinations 18 extended ASCII code 22,78 Alt keypad 22 external code 85 API 88 file screen 70 arithmetic 95 filekey 90 beeps 70 filekey command mode 90 BIOS buffer 76 flush buffer 41 BIOS data area 76 flush scan 41 blinking bit 60 flushing the buffer 45 border colors 51 forty three lines 69 boxes.com 93 Function keys 18 Break status 48 halt 72 buffer overflow 15 help 15 buffer size 49 hotkeys 41 Buffer, enlarging the 46 inline code 84 buffer, flushing 45 interupts 74 buffer, keyboard 76 keyboard buffer 76 buffer, STACKEY's 43 keywait 73 Caps Lock 21 L command 52 CAROUSEL 24 large buffer 47 cgacolor.bat 93 loading STACKEY 13 CLONE SPEEDUP 24 lock toggles 72 cold reboot 71 loops 36 color codes - CGA 51 messages 26 color codes, EGA 55 mode changes 68 color.bat 93 modes, graphics 50 colors on the CGA 52 music 70 colors on the EGA/VGA 57 normal mode 48 com port swap 67 NUL, redirection to 15 comments 46 Num Lock 21 continue mode 48 Numeric keypad 18 Control key overscan byte 56 combinations 18 P command 53 copyright 9 palettes, CGA 53 Ctrl-Break 19 palettes, permanent CTRLALT PLUS 23 on the EGA/VGA 59 cursor control 69 palettes, temporary Cursor keys 19 on the EGA/VGA 57 date 22 path, current 22 delays 37 pause script 41 DESQVIEW 24 permanent palettes directory, current 22 on the EGA/VGA 59 disabling print screen 68 permission to copy 8 disclaimer 9 phony keystroke 40 discontinue mode 49 pop STACKEY flags 49 dumpf 15 popup messages 26 dword1 91 PRIMETIME 25 EGA/VGA colors 57 print screen 68,70 EGAPAL 91 printer swap 67 enhanced keyboard 20 push STACKEY flags 49 enterwait 73 query STACKEY flags 49 errorlevel 15 reboot 71 repeats 36 resume script 41 RrBbGg color labels 54 scan 39 scan silently 39 screen dumps 70 Scroll Lock 21 second ASCII code 78 seecolor.bat 93 SIDEKICK 25 SIDEKICK PLUS 25 SKRES 47 smart processing 43 sounds.bat 93 STACKEY's API 88 swap ports 67 temporary palettes on the EGA/VGA 57 TESSERACT 24 test mode 48 text mode 50 time 22 Two key special codes 19 ultravision 58 Upper ASCII codes 22 utilities mode syntax 63 VGAPAL 91 W command 64 wait for buffer 38 wait for hotkey 42 wait for key 42 wait for request 40 waits 38 waits 64 warm reboot 71