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.