home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast.iso / pcmag / vol9n09.zip / PAN.DOC < prev    next >
Text File  |  1990-04-04  |  14KB  |  308 lines
  1. UTILITIES
  2. PETE MACLEAN
  3. Vol. 9, No. 9
  4. PAN Documentation
  5.  
  6.  
  7. PAN script commands are entered one per line, and any amount of "white space"
  8. (blanks and tabs) may be inserted before and between fields.  Each command 
  9. begins with a keyword, such as Output or Label.  Keywords may be entered in 
  10. any combination of upper and lower case.  String arguments may be delimited 
  11. by any character, though double quotes (as used below and in the figures) are 
  12. suggested for the sake of readability.  
  13.  
  14. Note that PAN does little error checking.  If a script does not do what you 
  15. expect, consider the possibility that there is some error--a missing EndIf
  16. perhaps--that a compiler or other typical language processor would catch but 
  17. that PAN does not.
  18.  
  19. Decimal numbers are used unless otherwise indicated.  
  20. The virgule (|) indicates a choice between or among parameters.
  21.  
  22. SCRIPT COMMANDS
  23. Break on|off determines how PAN handles a Ctrl-C.  If the GetKey command 
  24. retrieves a Ctrl-C when Break is set on, PAN treats it as an abort and 
  25. terminates (if no program is running).  If Break is set off, then a Ctrl-C is 
  26. handled as any other character.  (Note: Ctrl-Break receives no special handling
  27. in the original version of PAN, but this may be changed in future versions 
  28. available on PC MagNet.)
  29.  
  30. Cursor row column positions the cursor at an location on (or off) the screen.
  31. As with all PAN commands that refer to screen coordinates, the row and column
  32. arguments are entered as decimal integers, numbered from zero, with the top 
  33. left corner of the screen being row 0, column 0.  No check for legal values is
  34. made and no error indication is given.  If an argument is omitted or invalid 
  35. (that is, non-numeric), a default value of zero is used.  Note: the cursor can
  36. be made to "disappear" by moving it to a location beyond the limits of the 
  37. screen, as, for example, by entering the command:
  38.  
  39. Cursor 25 0
  40.  
  41. Else reverses conditional execution inside an If...EndIf command group.
  42. EndIf terminates the effect of an IfKey or IfLoad command.  Every "if" command
  43. should have a matching EndIf, but PAN does not check for this.
  44.  
  45. Flush flushes the keyboard holding buffer.  This command is generally used in
  46. association with the GetKey command to discard any accumulated keycodes before
  47. soliciting a keypress.
  48.  
  49. GetKey waits for the user to enter a keystroke, which then becomes available
  50. for testing with the IfKey command.
  51.  
  52. Go "argument(s)" initiates execution of a program that has been loaded with 
  53. the Load command.  The program is run as if it had been started from the DOS
  54. prompt with the given argument string.
  55.  
  56. IfKey "list" tests whether the last keypress (that is, that captured by a
  57. GetKey command) matches one of those in the given list.  If there is a match,
  58. the subsequent commands are executed.  If the match fails, then command 
  59. execution is inhibited until a matching Else or EndIf command is encountered.
  60.  
  61. For example, the command
  62.  
  63. IfKey "1234567890"
  64.  
  65. would result in a match if any digit were pressed.
  66.  
  67. IfLoad "file" attempts to load a program into memory for subsequent execution.
  68. The filename of the program must end in .EXE or .COM, and the extension must 
  69. be included as part of file.  Execution of the loaded program does not start 
  70. until a Go command in the script is encountered.  The commands following the
  71. IfLoad are performed if the load is successful; if it fails, the commands 
  72. following an Else or EndIf are performed.  For example:
  73.  
  74. EndIf
  75.  
  76. Jump label transfers control to the given label (see the Label command).
  77. Key "string" feeds the characters that comprise string to the running program
  78. by entering them, one by one, into the keyboard holding buffer.  This simulates
  79. user keyboard input.  Thus, for example, the command 
  80.  
  81. Key "Yes[Enter]"
  82.  
  83. produces an effect equivalent to that of a user typing Yes then pressing the 
  84. Enter key.  Note: the Key command is valid only when PAN is running a program.
  85.  
  86. Label label defines a label that can be used as the object of a Jump command.
  87. This command is in most respects a no-operation.
  88.  
  89. Load "file" loads a program (file) into memory for subsequent execution.  As 
  90. with IfLoad (above), the .EXE or .COM extension must be included, and program
  91. execution does not begin until a Go command in the script is processed.  
  92. Should the load fail for any reason, PAN provides a suitable diagnostic message
  93. and terminates.  If the user wishes PAN to maintain control after a failed 
  94. load, the IfLoad command should be used instead.
  95.  
  96. Output "string" displays a string on the screen at the current cursor location.
  97. The cursor is updated in the process.  The Output command should be used when 
  98. using PAN to animate applications (like DOS utilities) that simply scroll the 
  99. screen. (The Screen command, by contrast, should be used with screen-oriented
  100. applications.) Because Output invokes a DOS service to write to the screen, it 
  101. cannot be used while PAN is running a program.  Here is an example:
  102.  
  103. Output "This string scrolls
  104. onto the screen.^M^J"
  105.  
  106. (Note: ^M^J stand for a carriage return plus a linefeed.)
  107.  
  108. Pause n T|S|M pauses for a specified period.  Permissible values of n are 
  109. 1 - 255 for T (ticks) or S (seconds), or 1 - 60 for M (minutes).  (The timer 
  110. ticks on a standard PC occur at a rate of 18.2 per second.)  You could invoke 
  111. a delay of two and a half minutes by entering:
  112.  
  113. Pause 2 minutes
  114. Pause 30 seconds
  115.  
  116. PAN interprets only the first letter of the units field, that is, T, S or M.  
  117. If the units field is omitted, PAN assumes seconds.
  118.  
  119. Quit terminates PAN.  If PAN is not running a program, it quits immediately.  
  120. If PAN is running a program, then it quits only when that program ends.
  121.  
  122. Screen row column "string" writes a string of characters to the screen, 
  123. starting at the character position defined by the row and column numbers 
  124. (0 to 24 and 0 to 79, respectively).  Thus, for example: 
  125.  
  126. Screen 10 40 "This appears on
  127. line 10 starting at column 40"
  128.  
  129. The operation uses a direct write to the video buffer.  The video attribute 
  130. used is that set by the last Video command.
  131.  
  132. TypeRate ticks controls the rate at which characters are fed by the Key 
  133. command into the keyboard holding buffer.  The number to be entered represents 
  134. the count of the 18.2-to-a-second ticks to be skipped between each pair of 
  135. keyed characters.  In most situations, setting TypeRate to zero is the best 
  136. choice; the keys are then fed to the animated program as quickly as it will 
  137. accept them.  If you want the user to clearly see what is being "typed," a 
  138. TypeRate between 2 and 9 is suggested.  
  139.  
  140. Video attribute sets a video attribute for writes by subsequent Screen 
  141. commands.  Note:  the  number entered for attribute is in hexadecimal notation.
  142. The default screen attribute (70h) sets a white foreground and black background.
  143.  
  144. WaitChild suspends PAN activity until the animated program terminates.
  145.  
  146. WaitScreen row column "string" waits for the specified string to appear on 
  147. screen, starting at the position indicated by the row and column numbers.  
  148. PAN continually searches for the string in the video buffer.  Note: Use this 
  149. command with care:  PAN will wait forever, if necessary, for the string to 
  150. appear, and you may be left with no way to interrupt the wait other than to 
  151. press Ctrl-Alt-Del.
  152.  
  153. WaitUntil HH:MM suspends activity until the specified time of day, as expressed
  154. in 24-hour notation.  For example, to wait until 10:15 pm, your script would 
  155. contain the line:
  156.  
  157. WaitUntil 22:15
  158.  
  159. Wipe clears the screen.  (This command uses a BIOS function.)
  160.  
  161. (Note:  Additional commands may have been added to PAN since this was written. 
  162.  Please check for documentation files when you download the program.)
  163.  
  164. KEY STRINGS
  165. A string provided as an argument to the Key or IfKey command contains symbols 
  166. that identify keys on the standard IBM keyboard.  With the IfKey command, the 
  167. string expresses a list of keys to be matched to the last keypress; the order 
  168. in which the keys are expressed is immaterial.
  169.  
  170. The rules for naming keys are as follows:
  171.  
  172.         * Any printable character except ^ or [   directly represents the key 
  173.           that generates it.  The caret (^) and the open square bracket ([) 
  174.           are used as escape characters, and must be doubled if intended to 
  175.           stand for themselves.  Thus ^^ signifies a caret and [[ a bracket.
  176.     * A named key is represented by putting its name in square brackets, 
  177.           for example, [Esc], [Home], [End], [Enter], [Ins], [Del], [PgUp], 
  178.           and [PgDn], and [F1], [F2], [F3], [F4], [F5], [F6], [F7], [F8], [F9],
  179.           and [F10].  Arrow keys are identified as [Up], [Down], [Left] and 
  180.           [Right].
  181.     * Either a regular ASCII or an extended-ASCII code, equivalent to that 
  182.           produced by holding down the Alt- key and entering a decimal code on 
  183.           the numeric keypad, can be indicated by putting the appropriate 
  184.           number in square brackets.  Thus, for example, as part of an IfKey 
  185.           or Key command, you might enter:
  186.  
  187. "[227] generates the pi symbol."
  188.  
  189.     * Any character may be prefaced by one or more shift indicators: [Alt],
  190.           [Ctrl] or [Shift].  Note:  the caret may be used as an alternative 
  191.           to [Ctrl].
  192.     * Literal control characters should not be included in strings; any 
  193.           that are present will be ignored.  Use the ^[key] or [Ctrl][key] 
  194.           notation instead.
  195.     
  196. Below are some examples of key names:
  197.  
  198. [Alt][F10]     Alt-F10
  199. [Shift]2       @
  200. [Esc]          Esc
  201. ^[[            Esc
  202. [Ctrl][Enter]  Ctrl-Enter
  203. [3]            Ctrl-C 
  204. ^2             Null
  205.     This scheme for naming characters makes no pretense of being complete. 
  206.         You cannot enter F11 or F12, for example, nor distinguish between the
  207.         two Enter keys.
  208.  
  209.  
  210. Strings supplied as arguments to commands such as Screen and Output may 
  211. contain printable characters (those that directly represent themselves) and 
  212. control characters that are expressed in the common keyboard-equivalent 
  213. notation.  Thus, for any suitable, Ctrl-X is indicated by a caret followed by
  214. an X, that is, by ^X.  In this notation, a carriage return is ^M and a linefeed
  215. is ^J.  A literal caret is expressed by doubling the character, that is, by ^^.
  216.  
  217. Cursor 25 0
  218.  
  219. IfKey "1234567890"
  220.  
  221. IfLoad "c:\program.com"
  222.    Output "The program has been
  223.     loaded succesfully!^M^J"
  224.    Go
  225.    Quit
  226. Else
  227.    Output "The program could
  228.     not be loaded!^M^J"
  229.    Quit
  230. EndIf
  231.  
  232. Key "Yes[Enter]"
  233.  
  234. Output "This string scrolls
  235. onto the screen.^M^J"
  236.  
  237. Pause 2 minutes
  238. Pause 30 seconds
  239.  
  240. Screen 10 40 "This appears on
  241. line 10 starting at column 40"
  242.  
  243. WaitUntil 22:15
  244.  
  245. "[227] generates the pi symbol."
  246.  
  247. [Alt][F10]     Alt-F10
  248. [Shift]2       @ 
  249. [Esc]          Esc
  250. ^[[            Esc
  251. [Ctrl][Enter]  Ctrl-Enter
  252. [3]            Ctrl-C
  253. ^2             Null
  254.  
  255.  
  256. TIPS FOR CREATING PAN SCRIPTS
  257.  
  258. Use the Cursor and Output commands with programs, such as DOS utilities, that
  259. write their screen output in scrolling ("teletype") fashion.  Use the Screen 
  260. command with programs that do full-screen output.
  261.  
  262. Don't be confused by the differences between key strings (used with Key and 
  263. IfKey) and character strings (used with other commands).  The latter string 
  264. style is a standard in programming, but a key string will be new to many 
  265. people.  Remember that a key string identifies a sequence of codes generated 
  266. by keys on a keyboard, including many for which there are no equivalent 
  267. characters.  In a key string, for example, [Home] serves to identify a single, 
  268. specific key, while in a character string it represents a 6-character sequence 
  269. of keystrokes.
  270.  
  271. PAN can be used to run a sequence of programs or one program repeatedly.  After
  272. one program terminates and PAN regains control with a WaitChild command, 
  273. another Load and Go can be issued.
  274.  
  275. If you are animating a large program, you may need to watch the length of your 
  276. PAN script.  The presence of comment lines never hurts because they are 
  277. stripped off as the script is loaded.  Also it never costs to indent commands 
  278. because leading whitespace on a line is also removed.  Ways of reducing memory 
  279. requirements for a script include keeping labels short (say to two characters) 
  280. and limiting each field separator to a single character.
  281.  
  282.  
  283. PROGRAMMING NOTES:  EXTENDING PAN
  284.  
  285. The following are guidelines for adding new commands to PAN:
  286.  
  287.     Implementing a new command requires adding the command keyword to the 
  288.     COMMAND_KEYS table and the name of the associated procedure to the list 
  289.     labeled C_TABLE in the source code.  Conditional commands (Ifs, Elses, and 
  290.     so on) must be placed in their own little sections at the ends of the two 
  291.     tables.
  292.  
  293.     The procedure that processes a command must return with AX holding a count 
  294.     of the number ticks to be used for a delay or time-out.  If AX is zero 
  295.     (the usual case), PAN processes the next command immediately.  If AX is 
  296.     non-zero, then BX must contain a recall address.  PAN delays for the 
  297.     designated period and then executes a call to that recall address.  If the 
  298.     recall code needs to institute a further delay, it must explicitly store a 
  299.     tick count in the word called TIMEOUT.  For an example, study the code for 
  300.     the WaitUntil command (procedure C_WAITUNTIL).
  301.  
  302.     If a command procedure needs to invoke a DOS function, it should be 
  303.     prohibited from executing while PAN is in background mode.  The variable 
  304.     PAN_STATE should be tested to determine PAN's current mode.  See C_OUTPUT 
  305.     for an example.  If you need a fatal-error escape from a command procedure,
  306.     you should code a jump to COMMAND_ERROR with SI holding the address of a 
  307.     suitable diagnostic message.
  308.