Black Box 4

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

/ Black Box 4 / BlackBox.cdr / ibm1 / pandor23.arj / PANDORA.DOC < prev next >

Wrap

Text File | 1992-01-03 | 46.1 KB | 1,069 lines

User Guide to Pandora For version 2.3 Pete Maclean [75776,660 on CompuServe] Copyright 1991 Pete Maclean. This document comprises a introduction to Pandora plus a summary of what is new in version 2.x. As a user manual, it is not intended to substitute for my original article describing the program, then called PAN, that was published in PC Magazine (Volume 9, Number 9, May 15 1990). Pandora is a scripting program for automating the operation of other programs. To make use of Pandora it is necessary to do a little programming in Pandora's script langauge. Commands are provided to load and run programs, to feed programs simulated keyboard input, to interact with a user, and to detect what a program is doing primarily by checking what is displayed on the screen. Pandora can be used either to set up a program to run all by itself, even in the middle of the night, or to provide a user with a modified user interface to a program. It also has application in testing programs in development. Pandora's script commands are completely described below. For anyone proposing to use Pandora it is vital to be aware of certain restrictions imposed. Most of these restrictions reflect original design decisions made to keep the project within manageable bounds and the program to a reasonable size. The precise limitations are: (1) Pandora is designed to be used only with text-mode programs. It is not impossible to use it with graphics programs -- one user has very succesfully done so -- but certain commands will be useless with graphics-mode video output and there are no facilities oriented to graphics. (2) It is very difficult to use Pandora to automate memory-resident applications. This is not so much because of limitations in Pandora but because the design of DOS makes it nearly impossible. If you want to use Pandora with a TSR program, do try -- you may be lucky -- but be prepared to find that it's hopeless. (3) It is difficult to use Pandora with remote-control programs such as Carbon Copy, Takeover, Close Up, Remote2, and pcANYWHERE. This is unfortunate because a lot of people have wanted to do so, but the fact is that such programs seize control of the PC at such a low level that Pandora just cannot slide in underneath in order to work its magic in the normal way. Despite this warning, there are some people who have been successful so, again, give it a try if you will but be cautious. (4) Pandora does not work with Windows programs. It can, however, be used as normally with DOS applications that are launched from Windows. (5) Pandora does not work with CIM, the CompuServe Information Manager. This is because CIM was intentionally designed and written in a manner that thwarts its use with programs like Pandora. Controlling Programs with Pandora ----------- -------- ---- ------- This section describes how Pandora operates. The discussion is necessarily a little technical but an understanding of the principles involved is essential to making effective use of the utility. I suggest that you study this once you have played with Pandora a little and have gained a sense of what it can do, but before you embark on writing any Pandora scripts. DOS provides support for two types of program: transient programs and TSRs (memory-resident programs). Transient programs include all those regular applications that you use such as word processors, spreadsheet programs, etc. When you run a transient program, it takes primary control of the PC and normally retains that control until you terminate it. The most obvious aspect of this control is that the program essentially owns the screen and keyboard. DOS allows only one transient program to run at a time but compensates to a small degree for this limitation by allowing one transient program to execute another in a nested fashion. The original program becomes dormant after starting up a second program, then regains control after that second program quits. You may be familiar with the idea of "shelling out" of an application, a facility implemented by means of this capability. Since the dormant program remains in memory, the degree to which this nesting can be done is severely limited by the amount of program memory available. Pandora works by running as a transient program itself, and then executing another program (or a sequence of programs). Once it has has started a "child" program, Pandora does not, however, go dormant; rather it plays some tricks normally used by TSRs to retain a measure of control so that it can act in the role of a "puppeteer" to the child. A Pandora script, at its simplest, covers three phases of operation: 1. Loading a child program and otherwise preparing for its execution. 2. Running the child program while exerting control over its actions. 3. Terminating the child or waiting for it terminate, and cleaning up after it. In a Pandora script you set a child program running by means of the Go command. From then on until the child dies there are two threads of execution proceeding: the child itself and the thread represented by Pandora performing the commands that you have written for it. Control alternates back and forth between these two threads and the key to successful use of Pandora scripting is managing synchronization between the two. Beyond the "Go" point Pandora can interact with the child in one of two ways: asynchronously or synchronously. Pandora's primary means of asynchronous interaction is feeding simulated keyboard input to the child. Pandora stuffs characters into the BIOS keyboard buffer and the child reads them in its own time. This is asynchronous because there is no synchronization between Pandora's "feeding" the characters and the child's "eating" them. Asynchronous character feeding works a lot of the time but there are also situations where synchronization is necessary. Consider an application that displays a prompt for the user to type something and, at the point of displaying that prompt, flushes the keyboard buffer -- that is, discards any waiting input to be sure that the characters it processes are fresh and pertinent. If Pandora is to respond to the prompt then it must first wait for it to appear on the screen. Synchronization is achieved by a set of commands with names starting "Wait". Each such command instructs Pandora to wait for some event before proceeding with further commands. For this reason, most Wait commands are valid only during the child-execution phase. (One partial exception is WaitUntil which can be invoked anywhere in a script to delay until a given time of day.) To further enhance synchronization between Pandora and its child, several other commands have been added, such as IfScreen which tests for the presence of a string on the screen. Version 2 ------- - Many of the changes in this second-generation Pandora arose from my realization that, in version 1, there was not a sufficiently clear distinction between commands that had synchronous effects and those that had asynchronous effects [see the previous section]. The changes made in version 2 may "break" some existing Pandora scripts but only trivial modifications should be necessary to fix them. (To be precise, it may be necessary to change some GetKey commands to WaitKey, some Pause commands to WaitPeriod, and no more.) The biggest problem lay in the GetKey command. Although the documentation never made this fact sufficiently clear, GetKey operated asynchronously. That meant that a GetKey caused Pandora to wait for the user to press a key before continuing (with its next command). GetKey had no effect on the child which would continue to execute indefinitely. GetKey has been recoded to operate synchronously. Now when Pandora reaches a GetKey, it stops the child and waits for the user to press a key. Nothing happens until that keypress is made. The new command, WaitKey, has been added to do what GetKey did previously. The name "WaitKey" ties the operation to all the other Wait commands which have similar effects. A Wait command causes Pandora to wait; the child continues to run. Synchronization has also been facilitated by the addition of the Kill and OnDeath commands. The former allows Pandora to forcibly terminate a child. I had not provided that capability before because I had not understood how to do it. OnDeath lets you synch up a script with a child that terminates asynchronously. See Pandora Commands for more. Pandora now supports BIOS Enhanced Keyboard Services. This allows it to operate with programs such as WordPerfect with which it was not compatible previously. Finally, you will find several other new commands that I have not had occasion to mention above. VideoFore and VideoBack, for example, let you set screen colors more easily. ScreenWrite and ScreenRead allow you to save and restore screen images to create slideshows or other similar effects. PassKey enables you to filter the keystrokes sent from the keyboard to an application. Version 2.3 saw the introduction of the CtrlBreak command and a necessary redesign of the Break On/Off command. ****************************************************************************** * Pandora Commands ------- -------- (for Pandora v2.2 and later versions) by Pete Maclean [CIS: 75776,660] Copyright 1991 Pete Maclean. This provides documentation on writing scripts for Pandora (originally published as PAN). Please note that many commands have been added since the PAN article was published in PC Magazine. The behavior of a few other commands has been changed slightly. Commands are written one per line with any amount of white space (blanks and tabs) thrown in before and between fields. Each command starts with a keyword such as "Output" or "Label". Keywords may be written in any mixture of upper and lower case. String arguments may be delimited by any non-blank character although for readability double quotes are suggested. You can include comment lines in Pandora scripts. Pandora treats any line that begins with an asterisk as commentary, for example: * This is a comment line that Pandora ignores. As is acknowledged in many of the command descriptions, Pandora does little error checking. If a script does not do what you expect, consider the possibility that there is some error that a compiler or other typical language processor would catch but which Pandora does not. Command Groups ------- ------ Commands fall into functional groups as follows: Loading, starting and terminating programs: Load, IfLoad, Go, KillChild, OnDeath, WaitChild, Env, SetMemory. Simulating keyboard input to programs: CtrlBreak, Key, KeyFile, OpenKeyFile, TypeRate. Displaying text on the screen: Cursor, Output, ReadScreen, Screen, Mode, Video, VideoBack, VideoFore, Wipe, WriteScreen. Controlling user interaction with a program: Alt, Ctrl, CapsLock, NumLock, LeftShift, RightShift, Break, Flush, ScrollLock, Lock, UnLock. Timing events; Pause, IfAfter, IfBefore, WaitPeriod, WaitUntil. Script control: Call, Return, If..., Else, EndIf, Jump, Quit. Detecting program activity: IfScreen, WaitScreen. Miscellaneous: DOS, Tone. Command Descriptions ------- ------------ Alt On/Off (See section on Keyboard Control Commands below.) Break On/Off Sets the condition for how Pandora handles a Control-Break. Please note that the effect of this command was changed in the transition from Pandora version 2.2 to 2.3. By default (the condition set by "Break Off") Pandora pays no attention to a Ctrl-Break. If a child program is running then the child handles Ctrl-Break according to its design. For many programs, this key combination serves as an abort signal and DOS provides some facilities for handling it as such. Programs may, however, treat Ctrl-Break in other ways. By issuing a "Break On" command, you tell Pandora to intercept a Ctrl-Break and use it as a signal to abort processing of the script. Then, when the user presses Ctrl-Break, Pandora steps out of the way and leaves the program to continue running as if it (Pandora) were no longer there. There may be no apparent indication of this happening! Setting "Break On" can be useful, for example, when you set up a script to run a program over and over again in a loop. You might do this with a program that displays the status of something that changes over time such as the load average on a LAN. Instead of having your script laboriously intercept every keypress and check for some signal to terminate, you may be able to just set enable termination by Control- Break. Issue a Break command prior to starting the child program. Pandora will generate an error if it meets a Break while running a program. Call label Call coupled with the Return command gives Pandora a primitive subroutine capability. When Pandora performs a Call command it pushes a pointer to the next command onto an internal stack. When a Return is issued that pointer is popped. No system is provided for passing arguments to a subroutine. Here's an example: Call procedure ..... ..... Quit Label procedure Output "This message come from a subroutine!" Return Warning: This facility is provided as an interim measure. It may in future be supplanted by a more powerful subroutine mechanism. I make no guarantee to continue supporting the current facility. CapsLock On/Off Simulates toggling the CapsLock key. The argument must be "On" or "Off". The setting of CapsLock affects keyboard input typed by the user; it does *not* affect simulated keyboard input generated by the Key command. To ensure that CapsLock is off when starting a program, for example, use the command: CapsLock Off Ctrl On/Off (See section on Keyboard Control Commands below.) CtrlBreak Simulates the user's pressing Ctrl-Break. Feeding a Ctrl-Break to a program is accomplished by this command rather than via the Key command because Ctrl-Break is interpreted as an abort signal and handled in a special way at a low level in the PC (actually by the BIOS keyboard driver). Simulating a Ctrl-Break condition is tricky and this command is known to not work correctly with certain programs such as Microsoft Flight Simulator. Cursor <row> <column> Repositions the cursor to a location on (or possibly off) the screen. As with all other commands that refer to screen coordinates, rows and columns are numbered from zero with the top left corner being row 0, column 0. The row and column arguments are decoded as decimal integers and their values are not checked. If an argument is omitted or invalid (i.e., non-numeric) then a default value of zero is used; *no* error indication is given. The cursor can be made to "disappear" by moving it to a location beyond the bounds of the screen, for instance with the command: Cursor 25 0 DOS "command" Runs a copy of the DOS command interpreter to execute the supplied command. Pandora allows the execution of any command that you can type at the DOS prompt. It can be used for such purposes as changing the current directory, getting directory listings, and deleting files. All standard command options are supported including redirection and batch files. Here are some examples: DOS "cd \new" DOS "del blah.dat" DOS "E:" DOS "call batch" DOS "dir *.exe >tmp" Don't forget to enclose the command in quotes! Note: The DOS command is not available while Pandora is running a program. This facility depends on COMSPEC being defined in the environment table. Pandora uses the COMSPEC string to find the command interpreter, COMMAND.COM. If COMSPEC is not defined then the DOS command will fail. Else Reverses conditional execution inside an If-EndIf command group. EndIf Terminates the effect of an If command (i.e. IfKey, IfLoad, IfScreen, etc.). Every If must have a matching EndIf. Env Several early users had trouble getting Pandora to pass on the desired environment to its children. To accomodate all needs the Env command allows you to select between two options. The valid forms of the command are: Env Own Env Master The "Own" argument tells Pandora to pass on copies of its own environment. This is the default. The "Master" argument tells Pandora to pass on copies of the master environment. Note that if you use Pandora's DOS command to change environment strings, as in: DOS "Set magic=teapot" it is the master environment that is affected. The issue of which environment gets inherited is tricky. If you see no reason to care then don't worry about it; the default should suit you. Flush Flushes the keyboard holding buffer. The Flush command is used mostly in association with the GetKey command to discard any accumulated key codes before soliciting a keypress from the user. GetKey Waits for the user to depress a key on the keyboard which then becomes available for testing with the IfKey command or passing on to the child with Passkey. See also IfKey, PassKey and WaitKey. Go "arguments" Initiates execution of a child program that has been loaded with a Load or IfLoad command. The child is run as if it had been started from the DOS prompt with the given argument string. IfAfter <time> Tests if the time kept by DOS is equal to or greater than the time given. The argument should be expressed in the format HH:MM using the 24-hour system. For example, the following will hold true if it is 10:15 pm or later: IfAfter 22:15 IfBefore <time> Tests if the time maintained by DOS is before that specified. As with the previous command, the time must be expressed in the form HH:MM where HH is an hour in the range 0 to 24 and MM is a minute in the range 0 to 59. The following command, for instance, will hold true if it is earlier than 6:05 am: IfBefore 6:05 IfExist "file" This works exactly like DOS' IF EXIST command for batch files. This example should make it clear: IfExist "XRB.BAT" DOS "XRB ABC" Else Output "ERROR: Cannot find the batch file XRB.BAT" Quit EndIf IfExist detects the presence of regular files plus hidden and system files. It does not directly detect subdirectories or volume labels. Nevertheless, as with the DOS command, you can test if a given directory exists by testing for NUL within that directory, as in. IfExist "C:\DOS\NUL Else Output "ERROR: You don't have a C:\DOS directory" Quit EndIf IfKey "list" Tests if the last keypress (that captured by a GetKey command) matches one of those in the given list. If there is a match the subsequent commands are executed. If the match fails then command execution is inhibited until a matching Else or EndIf command is encountered. The following command, by way of example, would result in a match if the key in question was any digit: IfKey "1234567890" IfKeyFileEOF Tests for an end-of-file condition on the file opened by the last OpenKeyFile command and processed by the KeyFile command. A typical sequence of commands is: OpenKeyFile "INPUT" Label keyer [Wait for some prompt] KeyFile Line IfKeyFileEOF Else Jump keyer EndIf IfLoad "file" Attempts to load a program into memory for subsequent execution. The argument supplies the filename in which the extension ("EXE" or "COM") must be included. Execution of the loaded program does not start until a Go command is performed. The commands following the IfLoad are performed if the load is successful; if it fails, the commands following an Else or EndIf are performed. For example: IfLoad "c:\program.com" Output "The program has been loaded successfully!^M^J" Go Quit Else Output "The program could not be loaded!^M^J" Quit EndIf IfScreen <row> <column> "string" Checks if the given string appears on the screen at the given position. (This command, obviously, is closely related to WaitScreen.) For example: IfScreen 24 0 "OK" Jump success EndIf IfScreen 24 0 "Error" Quit EndIf checks for two strings that a program may display, and takes appropriate action for each. Jump label Transfers control to the given label (defined in a Label command). Key "string" Feeds the given string of characters to the running program by entering them, one by one, into the keyboard holding buffer. This simulates a user typing the same characters at the keyboard. This example has the equivalent effect of a user typing "Yes" then pressing the Enter key: Key "Yes[Enter]" The Key command is valid only while Pandora is running a program. The rate at which keycodes are fed to the program can be moderated by means of the TypeRate command. If you want to feed a Ctrl-Break signal to a program you must do so using Pandora's CtrlBreak command. It is not possible to issue a Ctrl-Break with the Key command. KeyFile Char/Line KeyFile is a lot like Key but feeds characters read from a file into the keyboard buffer. Each invocation of KeyFile feeds either a character or a line from the file opened in an OpenKeyFile command. Each byte from the file is read as one literal character. Thus only ASCII and extended-ASCII characters can be fed in this manner; there is no way to introduce Alt-shifted keys, function keys, etc. Pandora strips linefeeds from the file and passes everything else. If any user finds a need to strip other characters, or to not strip linefeeds, then I shall add a mechanism to permit such. KeyFile is valid only while Pandora is running a program. The rate at which keycodes are fed to the program can be moderated by means of the TypeRate command. See also IfKeyFileEOF which provides for end-of-file detection. KillChild Kills the child program. An error occurs if this command is used when no program is running. This command should be seen as a brute-force method of terminating a child program. If you have the option of feeding the program some appropriate keystrokes to tell it to quit, then do that instead. If a program traps any device interrupts then terminating it with KillChild may result in an error condition that forces a reboot. This applies, for example, to most communication programs. Label label Defines a label that can be used as the object of a Jump command. This command is a no-operation in most respects. LeftShift On/Off (See section on Keyboard Control Commands below.) Load "file" Loads a program into memory for subsequent execution. The argument supplies the filename in which the extension ("EXE" or "COM") must be included. Execution of the loaded program does not start until a Go command is performed. Should the load fail for any reason, Pandora emits a suitable diagnostic and quits. If you want Pandora to maintain control after a failed load then use IfLoad instead. Lock This command locks the keyboard. If you want Pandora to have full control over keyboard input to the child program then you should use this command at an appropriate point. Locking the keyboard prevents user keypresses from getting interspersed with the simulated input generated by Pandora's Key commands. After a Lock, the keyboard remains locked until either an Unlock command is performed or Pandora quits. If the user presses a key while the keyboard is locked, the system beeps and otherwise the action is ignored. (In fact, the behavior is identical to that taken by DOS when the type-ahead buffer is full.) Mode Commands such as Screen and IfScreen operate by delving into the video buffer, that is the block of memory that holds a character-by-character image of what appears on the screen. When Pandora starts up it determines the memory address for the current screen buffer and then uses that same address whenever the need arises. Some programs change the video mode; in such a case the address of the effective video buffer may change too. The Mode command forces Pandora to reevaluate the address for the video buffer. Very few people will need the Mode command, especially as Pandora offers so little assistance in automating graphics applications. Should you write a script and find that WaitScreen commands do not take effect then consider the possibility that you need to add a Mode command. NumLock On/Off Simulates toggling the NumLock key. The argument must be "On" or "Off". The setting of NumLock affects keyboard input typed by the user; it does *not* affect simulated keyboard input generated by the Key command. To ensure that NumLock is off when starting a program, for example, use the command: NumLock Off OnDeath <label> OnDeath is Pandora's one asynchronous command. It allows you to establish a label to which control is transferred when a child dies. Here is a simple example of its use: Load "program.exe" Go OnDeath Obituary Label Loop GetKey IfKey "[Ins]" Else PassKey EndIf Goto Loop Label Obituary ...[continued] This script feeds keyboard input to a program filtering out the Insert key. When the child terminates, control is automatically switched from the loop to the command following "Label Obituary". You can use this form of script in more sophisticated ways to build application-specific keyboard-macro processors. OpenKeyFile "filename". Opens a file for use with the KeyFile command. If the file cannot be opened then Pandora displays a diagnostic and aborts. The file opened by this command remains open either until another OpenKeyFile is performed or until Pandora quits. For further information, see the entry for KeyFile. Output "string" Displays a string on the screen at the current cursor location. The cursor is updated in the process. The Output command should be used to display stuff when animating applications that use the screen in a simple scrolling manner (like DOS utilities). The Screen command, by contrast, should be used with screen-oriented applications. Here is an example: Output "This string scrolls onto the screen.^M^J" The "^M^J" part stands for a carriage return plus a linefeed. You may redirect Output to a file in the same way as you would using redirection on the DOS command line. For example: Output "This gets written to a file^M^J" > thisfile Output "This gets appended to a file^M^J" >> thatfile PassKey Passes the keycode obtained by the last GetKey or WaitKey to the child program. GetKey and PassKey can be used in combination to provide a keyboard macro facility for a program, as in this example: Label keyer GetKey IfKey "[Alt]M" Key "This is a macro" Else PassKey EndIf Jump keyer These commands can also be used to filter keycdoes to ensure that selected codes never reach a program. See also GetKey, Ifkey and WaitKey. Pause <n> Ticks/Seconds/Minutes Pauses for the specified period. Permissible times are: 1 - 255 ticks 1 - 255 seconds or 1 - 60 minutes A tick refers to the period between clock ticks on a standard PC; such ticks occur at a rate of 18.2 to a second. The following example invokes a delay of two and a half minutes: Pause 2 minutes Pause 30 seconds Pandora interprets only the first letter of the units field, looking for 't', 's' or 'm'. If the units field is omitted, Pandora assumes seconds. PrintScreen This command, which takes no arguments, has the same effect as pressing the <PrtSc> key on the PC keyboard. (Internally this invokes interrupt number 5.) It is compatible with PC Magazine's PRN2FILE utility. Quit Terminates Pandora. If Pandora has no child running then it quits immediately. If a child is active then Pandora quits only when that child quits. ReadScreen <filename> Restores a screen image from a file. Use the WriteScreen command to create suitable files. Return Return from a subroutine. (See Call.) RightShift On/Off (See section on Keyboard Control Commands below.) Screen <row> <column> "string" Writes a string of characters to the screen starting at the character position defined by the <row> and <column> arguments. The operation is performed using a direct write to the video buffer. For example: Screen 10 40 "This appears on line 10 starting at column 40" Note that for this, as for all purposes in Pandora, rows are numbered from 0 to 24 and columns from 0 to 79. The video attribute used is that set by the last Video, VideoFore and/or VideoBack command(s). ScrollLock On/Off Simulates toggling the ScrollLock key. The argument must be "On" or "Off". SetMemory SetMemory is a command intended for programmers who need to test their products running in limited amounts of memory. It is likely to be of no value to most Pandora users. The following command, for example: SetMemory 100 artificially sets the largest block of free DOS memory to a size of 100 kilobytes. The argument is a decimal number that is interpreted as a KB count. The effect of a SetMemory lasts until either another SetMemory is performed or until Pandora exits. Tone The Tone command enables you to generate a tone on the PC's speaker. Normally, it takes two arguments: a frequency and a duration. The frequency is a number of Hertz between 50 and 15000. Selecting 50 Hz results in a low buzz while 15000 Hz is sufficiently high-pitched that most PC speakers will not even succeed in reproducing it. The duration is the period of time that you want the tone sounded for. Here's an example: Tone 262 1s This will generate a 262-Hz tone (that's middle C, I believe) for a period of one second. The duration argument is expressed in exactly the same way as an argument to the Pause command. The shortest available duration is one tick, that is approxiamtely one eighteenth of a second. You can play some primitive tunes by writing a sequence of Tone commands. (Would someone volunteer to compose the Pandora theme tune?) A further option on the Tone command lets you have a tone sounding while other Pandora commands are executing. If the duration argument is given as zero (or is simply omitted) the tone will be generated until the next Tone command is performed. To shut off a tone started in this way, use a Tone command with a first argument of zero. Here's an example: Tone 98 0 Output "The tone you are hearing has a frequency of 98 Hz^M^J" Output "Press any key when you are sick of it!" GetKey Tone 0 TypeRate <ticks> Controls the rate at which characters are fed by the Key command into the keyboard holding buffer. For most situations setting the TypeRate to zero is the best choice; then the keys are fed to the animated program as fast as it will accept them. If you want the user to clearly see what is being "typed" then set the TypeRate to some number between 2 and 9. The number represents the count of 18.2-to-a-second ticks that are forced to pass between each pair of keyed characters. Unlock Unlocks the keyboard if it was previously locked by a Lock command. If the keyboard is not locked then this command does nothing. Video <attribute> Sets a video attribute for writes by subsequent Screen commands. The argument is interpreted as a hexadecimal number. The default screen attribute (70 hex) is for white foreground and black background. The Video command is provided for historical reasons. Most users will prefer to use VideoBack and VideoFore. VideoBack <background_color> Sets the background color for subsequent Screen commands. Valid colors are: Black, Blue, Green, Cyan, Red, Magenta, Brown and White VideoFore <background_color> Sets the foreground color for subsequent Screen commands. Valid colors are: Black, Blue, Green, Cyan, Red, Magenta, Brown, White, Grey, LightBlue, LightGreen, LightCyan, LightRed LightMagenta, Yellow and BrightWhite Composite color names must be written as one word, as shown. VideoNormal Restores "normal" video after reverse video has been selected by the VideoReverse command. VideoReverse Reverses the foreground and background colors. WaitChild Suspends Pandora activity until the child program terminates. WaitKey Suspends Pandora activity until the user presses a key. The child program continues running but is blocked from getting keyboard input. WaitKey is valid only while a child program is running. Note the difference between GetKey and WaitKey. If no child is running then GetKey should be used. GetKey suspends both Pandora itself and the child program until the user presses a key. WaitKey suspends Pandora but lets the child run unmolested. Here's a simple example of the use of WaitKey: Load "program.exe" Go WaitKey KillChild This starts up a program and lets it run until the user presses a key, any key. Obviously this assumes that said program runs without asking for any keyboard input. WaitKey can be very useful in scripts written to demo programs. See also GetKey, IfKey and PassKey. WaitPeriod <n> Ticks/Seconds/Minutes Suspends Pandora activity for the specified period of time. The argument has exactly the same form as that for the Pause command. Suppose you want to set up a program for people to try at a trade show. You want to limit each user to running the program for 3 minutes in order to gove plenty of people an opportunity. The following script will give you an idea of how to do it. Label next Wipe Screen 0 0 "Press any key for a 3-minute try" GetKey Load "program.exe" Go WaitPeriod 3 minutes KillChild Jump next Note the difference between WaitPeriod and Pause. Pause suspends both Pandora and the child program (if any) for the given period. WaitPeriod suspends Pandora but lets the child run. The following example demonstrates this with a script fragment that runs a program in slow motion by alternately letting it run for one tick and then freezing it for three. The effect may be rather jerky. Label SlowDown WaitPeriod 1t Pause 3t Jump SlowDown WaitScreen <row> <column> "string" Waits for the given string to appear on the screen starting at the given position. Pandora continually searches for the string in the video buffer. Use this command with care: Pandora will wait forever if necessary for the string to appear and there may be no way to interrupt the wait other than by pressing Ctrl-Alt-Del. WaitUntil <time> Suspends Pandora activity until the given time of day. Times should be expressed using 24-hour-clock notation. Thus to wait until 10:15 pm, one should code: WaitUntil 22:15 This command may be used in any context, that is with or without a child program running. When there is no child running you can abort a WaitUntil by pressing the Escape key. Wipe Clears the screen. (A BIOS function is used to do this.) WriteScreen <filename> Writes a copy of the current screen image to the named file. The image can be restored using the ReadScreen command. Note that this command works only with 25x80-character text-mode screens, and that the screen attributes are stored along with the characters. You can create simple slideshows using WriteScreen and ReadScreen. Keyboard Control Commands -------- ------- -------- I added some commands so that I could experiment with using Pandora to control pop-up memory-resident programs with hot keys. The commands are Alt, Ctrl, LeftShift and RightShift. Each takes an argument of On or Off. The effect of, for example: Alt On is to duplicate pressing the Alt key on the keyboard. Suppose that you have a memory-resident program that pops up when you press both shift keys simultaneously; then you can make Pandora pop it up with the commands: LeftShift On RightShift On Note that once you have used such a command, the effect is as if you had pressed the equivalent key and remained pressing it. To release the key, you must give a command such as: LeftShift Off otherwise you may experience strange keyboard behavior. Also please note that these commands, like CapsLock etc., affect only the real keyboard. They have no effect on simulated keyboard input generated by the Key command. Wait Commands ---- -------- All of the Wait commands cause Pandora to suspend command processing until some external event occurs. Normally this is an event triggered by the child program such as its displaying a certain message on the screen. Waits allow you to synchronize your Pandora scripts with events in the child program. It is also possible to synchronize with external events such as the user pressing a key (WaitKey) or a certain time of day rolling around (WaitUntil). Key strings --- ------- A string provided as an argument to the Key or IfKey command contains symbols identifying keys on the standard IBM keyboard. With the IfKey command, the string expresses a list of keys to be matched to the last keypress; the order in which the keys are expressed is immaterial. The rules for naming keys are as follows: Any printable character (except '~' or '[') represents the key that generates it. e.g., "ABC..., abc..., 123..., !#$%&*()-=+\|`;:'".,/?><{}" The caret (^) and open square bracket ([) are used as escape characters and if intended literally must be doubled. e.g., "^^ signifies a caret and [[ a bracket." A named key is represented by the name in square brackets. Here is a complete list of the key names that Pandora recognizes: [Esc] [Bksp] [Tab] and [Enter] [Home] and [End] [Ins] or [Insert], [Del] or [Delete] [PgUp] or [PageUp], [PgDn] or [PageDown] [F1] [F2] [F3] [F4] [F5] [F6] [F7] [F8] [F9] [F10] [F11] and [F12] Arrow keys are identified as follows: [Up], [Down], [Left] and [Right] A pure ASCII or extended-ASCII code, equivalent to that generated at the keyboard by holding down the Alt key and entering a decimal code on the numeric keypad, can be indicated by putting the appropriate number in square brackets. e.g. "[227] becomes a pi." Any character may be prefaced by one or more shift indicators: [Alt], [Ctrl] or [Shift]. The caret is an alternative for [Ctrl]. Literal control characters should not be included in strings. Any that are present will be ignored. Use the ^[key] or [Ctrl][key] notation. I acknowledge that this scheme for naming characters is not complete. One cannot, for example, distinguish between the two Enter keys. Here are some examples of key names: [Alt][F10] Alt-F10 [Shift]2 @ (more simply expressed just by @ itself) [Esc] Esc ^[[ Esc [Ctrl][Enter] Ctrl-Enter [3] Ctrl-C (^C would be more usual, however) ^2 Null Other strings ----- ------- Strings supplied as arguments to commands such as Screen and Output may contain printable characters representing themselves and control characters expressed in the common keyboard-equivalent notation. Control-X is indicated by a caret followed by an X (that is, '^X') for any suitable X. In this notation, carriage return is '^M' and linefeed is '^J'. A literal caret is expressed by doubling the character, that is by '^^'. Some tips for creating Pandora scripts ---- ---- --- -------- ------- ------- Use the Cursor and Output commands with programs, such as DOS utilities, that write their screen output in scrolling or teletype fashion. Use the Screen command with programs that do full-screen output. Don't let yourself get confused by the differences between key strings (used with Key and IfKey) and character strings (used with other commands). The latter style of string is a standard in programming but a key string will be new to many people. Remember that a key string identifies a sequence of codes generated by keys on a keyboard, including many for which there are no equivalent characters. In a key string, for example, "[Home]" serves to identify a particular key while in a character string it represents a sequence of six characters: [-H-o-m-e-]. Pandora can be used to run a sequence of programs or one program repeatedly. After one program terminates and Pandora regains control with an OnDeath, Kill or WaitChild command, another Load and Go can be issued. Often when you are having trouble debugging a Pandora script, it helps to make it operate in slow motion by throwing in a TypeRate command with an argument of 10 or 20. A few programs cannot cope at all with keyboard input fed at the maximum rate Pandora is capable of; with these programs, judicious use of TypeRate is a must. Using Pandora with Large Programs ----- ------- ---- ----- -------- If you are animating a large program, you may need to watch the length of your Pandora script. The presence of comment lines never hurts because they are stripped off as the script is loaded. Also it never costs to indent commands because leading whitespace on a line is also removed. Ways of reducing memory requirements for a script include keeping labels short (say to two characters) and limiting each field separator to a single character. With programs that are memory-hogs, occupying nearly all of available low memory, you may find insufficient space to squeeze in Pandora, small though it is. You may be tempted to seek a solution in loading Pandora into high memory (using, for example, DOS 5's LOADHIGH or QEMM's LOADHI) leaving all of low memory for the application. Unfortunately, because of the way these loaders operate, this does not work. I am looking for a way around this problem but have no confidence that I shall succeed in finding one. Notes ----- Pandora seems to be incompatible with SUPER PCKWIK. Should you run this program, do not rely on Pandora working correctly. The OpenKeyFile, KeyFile and IfKeyFileEOF commands were added in version 1.6. I do not guarantee that support for these commands will be maintained in future versions. Equivalent functionality will always be provided but the commands involved are subject to change. Sample Scripts for version 2.1 still work with this version. --------- In the May 16, 1990 issue of PC Magazine, a utility called PAN was published. PAN is a registered trademark for electronic services for the entertainment industry owned by the Pan Network. In the event anyone may have been confused, the utility -- which continues to be available -- has been renamed to PANDORA. Further information regarding PAN can be obtained by contacting THE PAN NETWORK at P.O. Box 162, Shippack, PA 19474, (215) 584-0300.