Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PROGRAMS / UTILS / TECLADO / PANDORA.ZIP / PANDORA.DOC < prev

Wrap

Text File | 1990-11-07 | 24.3 KB | 568 lines

Pandora Commands ------- -------- (for Pandora v1.2) by Pete Maclean [75776,660] This file provides documentation on writing scripts for Pandora (originally published as PAN). Please note that several commands have been added since the PAN article was published in PC Magazine. These new commands are: CapsLock, DOS, IfAfter, IfBefore, IfScreen, Lock, NumLock, ScrollLock, Unlock and Mode. The behavior of a few other commands has been changed trivially. 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 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. Break On/Off Sets the condition for how Pandora handles a Control-C. If the GetKey command retrieves a Control-C when Break is set on then Pandora treats it as an abort and terminates (as long as no program is being run). If Break is set off then a Control-C is handled as any other character. Note that Control-Breaks are not handled in any special way -- but this may be changed in future. 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 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" Submits a string to the DOS command interpreter. This powerful addition to 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! Warning: This facility in Pandora depends on the resident portion of the DOS Command Interpreter (COMMAND.COM) being loaded. Pandora does its best to check that the requisite program is present but if your system is set up to use an alternate command processor then the DOS command may produce strange results or hang the system. Further warning: Pandora takes advantage of an undocumented feature of DOS to make this command work. It should be reliable but cannot be guaranteed to work with all versions of DOS. Else Reverses conditional execution inside an If-EndIf command group. EndIf Terminates the effect of an If command (i.e. IfKey, IfLoad or IfScreen). Every If must have a matching EndIf. 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. GetKey Waits for the user to depress a key on the keyboard which then becomes available for testing with the IfKey command. Go "arguments" Initiates execution of a program that has been loaded with a Load or IfLoad command. The program 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 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" 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 succesfully!^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 when Pandora is running a program. 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. 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 the user wishes Pandora to maintain control after a failed load then the IfLoad command should be used instead. Lock This command locks the keyboard. If you want Pandora to have full control over keyboard input to the target 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 Output 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 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. Because Output invokes a DOS service to write to the screen, it cannot be used while Pandora is running a program. 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. 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. Quit Terminates Pandora. If Pandora is not running a program then it quits immediately. If Pandora is running a program then it quits only when that program quits. 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 command. ScrollLock On/Off Simulates toggling the ScrollLock key. The argument must be "On" or "Off". 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 skipped 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. WaitChild Suspends Pandora activity until the animated program terminates. 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 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 Wipe Clears the screen. (A BIOS function is used to do this.) 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. e.g., "[Esc] [Home] [End] [Enter] [Ins] [Del] [PgUp] and [PgDn]" and "[F1] [F2] [F3] [F4] [F5] [F6] [F7] [F8] [F9] and [F10]" 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 enter F11 or F12, for example, nor can one 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 a WaitChild command, another Load and Go can be issued. 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. What's New in Pandora 1.4 ------ --- -- ------- --- Pete Maclean [75776,660] Keyboard Control -------- ------- 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. What Was New in Pandora 1.3 ---- --- --- -- ------- --- Screen Handling ------ -------- Thanks to some better understanding that I have gained of PC video modes and BIOS screen functions, I have improved Pandora's screen handling in various ways. The Wipe command is now implemented in a completely different way and should work consistently. (Previously, it sometimes had no effect and sometimes changed the video mode.) The Mode command is also improved and gives an error if an application program sets a video mode that Pandora cannot handle (i.e., a graphics mode). Please note that Pandora is not designed for use with graphics-mode programs. You may, nevertheless, be able to automate such programs with Pandora as long as you scrupulously avoid all commands that affect the screen: Mode, Screen, IfScreen, WaitScreen and Wipe. Environment Tables ----------- ------ Several early users had trouble getting Pandora to pass on the desired environment to its children. To accomodate all needs I have added an Env command 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. What Was New in Pandora 1.2 ---- --- --- -- ------- --- For legal reasons the program, originally known as PAN, was renamed Pandora. This change keeps it nicely in line with my previous PC Magazine utilities Bess and Emma. CapsLock/NumLock/ScrollLock --------------------------- Three commands were added for setting the condition of CapsLock, NumLock, and ScrollLock. The commands follow the keynames and take an argument of "On" or "Off". To set CapsLock on, for example, the appropriate command is: CapsLock On Note that these lock keys affect only characters typed by the user on the keyboard. They do *not* affect the interpretation of arguments to Pandora's Key command. Thus, the command: Key "abc" delivers the precise string "abc" to the running program irrespective of the CapsLock setting. My thanks to Fran Finnegan for suggesting this enhancement. What Was New in PAN version 1.1 ---- --- --- -- --- ------- --- Three new commands have been added in this first update to PAN: DOS, IfAfter, and IfBefore. In addition, the IfScreen command has been fixed and a couple of other minor bugs corrected. PAN is known to have problems operating with certain screen and printer drivers. These are being investigated. Also it is known that PAN does not work correctly with WordPerfect. Here rae descriptions of the new commands: DOS "command" Submits a string to the DOS command interpreter. This powerful addition to PAN 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! Warning: This facility in PAN depends on the resident portion of the DOS Command Interpreter (COMMAND.COM) being loaded. PAN does its best to check that the requisite program is present but if your system is set up to use an alternate command processor then the DOS command may produce strange results or hang the system. Further warning: PAN takes advantage of an undocumented feature of DOS to make this command work. It should be reliable but cannot be guaranteed to work with all versions of DOS. 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