UTILITIES PETE MACLEAN Vol. 9, No. 9 PAN Documentation PAN script commands are entered one per line, and any amount of "white space" (blanks and tabs) may be inserted before and between fields. Each command begins with a keyword, such as Output or Label. Keywords may be entered in any combination of upper and lower case. String arguments may be delimited by any character, though double quotes (as used below and in the figures) are suggested for the sake of readability. Note that PAN does little error checking. If a script does not do what you expect, consider the possibility that there is some error--a missing EndIf perhaps--that a compiler or other typical language processor would catch but that PAN does not. Decimal numbers are used unless otherwise indicated. The virgule (|) indicates a choice between or among parameters. SCRIPT COMMANDS Break on|off determines how PAN handles a Ctrl-C. If the GetKey command retrieves a Ctrl-C when Break is set on, PAN treats it as an abort and terminates (if no program is running). If Break is set off, then a Ctrl-C is handled as any other character. (Note: Ctrl-Break receives no special handling in the original version of PAN, but this may be changed in future versions available on PC MagNet.) Cursor row column positions the cursor at an location on (or off) the screen. As with all PAN commands that refer to screen coordinates, the row and column arguments are entered as decimal integers, numbered from zero, with the top left corner of the screen being row 0, column 0. No check for legal values is made and no error indication is given. If an argument is omitted or invalid (that is, non-numeric), a default value of zero is used. Note: the cursor can be made to "disappear" by moving it to a location beyond the limits of the screen, as, for example, by entering the command: Cursor 25 0 Else reverses conditional execution inside an If...EndIf command group. EndIf terminates the effect of an IfKey or IfLoad command. Every "if" command should have a matching EndIf, but PAN does not check for this. Flush flushes the keyboard holding buffer. This command is generally used in association with the GetKey command to discard any accumulated keycodes before soliciting a keypress. GetKey waits for the user to enter a keystroke, which then becomes available for testing with the IfKey command. Go "argument(s)" initiates execution of a program that has been loaded with the Load command. The program is run as if it had been started from the DOS prompt with the given argument string. IfKey "list" tests whether the last keypress (that is, 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. For example, the command IfKey "1234567890" would result in a match if any digit were pressed. IfLoad "file" attempts to load a program into memory for subsequent execution. The filename of the program must end in .EXE or .COM, and the extension must be included as part of file. Execution of the loaded program does not start until a Go command in the script is encountered. 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: EndIf Jump label transfers control to the given label (see the Label command). Key "string" feeds the characters that comprise string to the running program by entering them, one by one, into the keyboard holding buffer. This simulates user keyboard input. Thus, for example, the command Key "Yes[Enter]" produces an effect equivalent to that of a user typing Yes then pressing the Enter key. Note: the Key command is valid only when PAN is running a program. Label label defines a label that can be used as the object of a Jump command. This command is in most respects a no-operation. Load "file" loads a program (file) into memory for subsequent execution. As with IfLoad (above), the .EXE or .COM extension must be included, and program execution does not begin until a Go command in the script is processed. Should the load fail for any reason, PAN provides a suitable diagnostic message and terminates. If the user wishes PAN to maintain control after a failed load, the IfLoad command should be used instead. 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 when using PAN to animate applications (like DOS utilities) that simply scroll the screen. (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 PAN is running a program. Here is an example: Output "This string scrolls onto the screen.^M^J" (Note: ^M^J stand for a carriage return plus a linefeed.) Pause n T|S|M pauses for a specified period. Permissible values of n are 1 - 255 for T (ticks) or S (seconds), or 1 - 60 for M (minutes). (The timer ticks on a standard PC occur at a rate of 18.2 per second.) You could invoke a delay of two and a half minutes by entering: Pause 2 minutes Pause 30 seconds PAN interprets only the first letter of the units field, that is, T, S or M. If the units field is omitted, PAN assumes seconds. Quit terminates PAN. If PAN is not running a program, it quits immediately. If PAN is running a program, then it quits only when that program ends. Screen row column "string" writes a string of characters to the screen, starting at the character position defined by the row and column numbers (0 to 24 and 0 to 79, respectively). Thus, for example: Screen 10 40 "This appears on line 10 starting at column 40" The operation uses a direct write to the video buffer. The video attribute used is that set by the last Video command. TypeRate ticks controls the rate at which characters are fed by the Key command into the keyboard holding buffer. The number to be entered represents the count of the 18.2-to-a-second ticks to be skipped between each pair of keyed characters. In most situations, setting TypeRate to zero is the best choice; the keys are then fed to the animated program as quickly as it will accept them. If you want the user to clearly see what is being "typed," a TypeRate between 2 and 9 is suggested. Video attribute sets a video attribute for writes by subsequent Screen commands. Note: the number entered for attribute is in hexadecimal notation. The default screen attribute (70h) sets a white foreground and black background. WaitChild suspends PAN activity until the animated program terminates. WaitScreen row column "string" waits for the specified string to appear on screen, starting at the position indicated by the row and column numbers. PAN continually searches for the string in the video buffer. Note: Use this command with care: PAN will wait forever, if necessary, for the string to appear, and you may be left with no way to interrupt the wait other than to press Ctrl-Alt-Del. WaitUntil HH:MM suspends activity until the specified time of day, as expressed in 24-hour notation. For example, to wait until 10:15 pm, your script would contain the line: WaitUntil 22:15 Wipe clears the screen. (This command uses a BIOS function.) (Note: Additional commands may have been added to PAN since this was written. Please check for documentation files when you download the program.) KEY STRINGS A string provided as an argument to the Key or IfKey command contains symbols that identify 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 [ directly represents the key that generates it. The caret (^) and the open square bracket ([) are used as escape characters, and must be doubled if intended to stand for themselves. Thus ^^ signifies a caret and [[ a bracket. * A named key is represented by putting its name in square brackets, for example, [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 [Up], [Down], [Left] and [Right]. * Either a regular ASCII or an extended-ASCII code, equivalent to that produced 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. Thus, for example, as part of an IfKey or Key command, you might enter: "[227] generates the pi symbol." * Any character may be prefaced by one or more shift indicators: [Alt], [Ctrl] or [Shift]. Note: the caret may be used as an alternative to [Ctrl]. * Literal control characters should not be included in strings; any that are present will be ignored. Use the ^[key] or [Ctrl][key] notation instead. Below are some examples of key names: [Alt][F10] Alt-F10 [Shift]2 @ [Esc] Esc ^[[ Esc [Ctrl][Enter] Ctrl-Enter [3] Ctrl-C ^2 Null This scheme for naming characters makes no pretense of being complete. You cannot enter F11 or F12, for example, nor distinguish between the two Enter keys. Strings supplied as arguments to commands such as Screen and Output may contain printable characters (those that directly represent themselves) and control characters that are expressed in the common keyboard-equivalent notation. Thus, for any suitable, Ctrl-X is indicated by a caret followed by an X, that is, by ^X. In this notation, a carriage return is ^M and a linefeed is ^J. A literal caret is expressed by doubling the character, that is, by ^^. Cursor 25 0 IfKey "1234567890" 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 Key "Yes[Enter]" Output "This string scrolls onto the screen.^M^J" Pause 2 minutes Pause 30 seconds Screen 10 40 "This appears on line 10 starting at column 40" WaitUntil 22:15 "[227] generates the pi symbol." [Alt][F10] Alt-F10 [Shift]2 @ [Esc] Esc ^[[ Esc [Ctrl][Enter] Ctrl-Enter [3] Ctrl-C ^2 Null TIPS FOR CREATING PAN SCRIPTS Use the Cursor and Output commands with programs, such as DOS utilities, that write their screen output in scrolling ("teletype") fashion. Use the Screen command with programs that do full-screen output. Don't be confused by the differences between key strings (used with Key and IfKey) and character strings (used with other commands). The latter string style 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 single, specific key, while in a character string it represents a 6-character sequence of keystrokes. PAN can be used to run a sequence of programs or one program repeatedly. After one program terminates and PAN 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 PAN 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. PROGRAMMING NOTES: EXTENDING PAN The following are guidelines for adding new commands to PAN: Implementing a new command requires adding the command keyword to the COMMAND_KEYS table and the name of the associated procedure to the list labeled C_TABLE in the source code. Conditional commands (Ifs, Elses, and so on) must be placed in their own little sections at the ends of the two tables. The procedure that processes a command must return with AX holding a count of the number ticks to be used for a delay or time-out. If AX is zero (the usual case), PAN processes the next command immediately. If AX is non-zero, then BX must contain a recall address. PAN delays for the designated period and then executes a call to that recall address. If the recall code needs to institute a further delay, it must explicitly store a tick count in the word called TIMEOUT. For an example, study the code for the WaitUntil command (procedure C_WAITUNTIL). If a command procedure needs to invoke a DOS function, it should be prohibited from executing while PAN is in background mode. The variable PAN_STATE should be tested to determine PAN's current mode. See C_OUTPUT for an example. If you need a fatal-error escape from a command procedure, you should code a jump to COMMAND_ERROR with SI holding the address of a suitable diagnostic message.